Add Social Vulnerability Index (SVI) subpackage

python/svi_client/CONTRIBUTING.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

python/svi_client/LICENSE

@@ -0,0 +1 @@
+../../LICENSE

python/svi_client/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE
+include src/hydrotools/nwm_client/data/*

python/svi_client/README.md

@@ -0,0 +1,33 @@
+# OWPHydroTools :: SVI Client
+
+## Installation
+
+
+## Usage
+
+
+### Code
+```python
+```
+### Example output
+```console
+```
+### System Requirements
+
+## Development
+
+```bash
+$ python3 -m venv env
+$ source env/bin/activate
+$ python3 -m pip install -U pip
+$ python3 -m pip install -U setuptools
+$ python3 -m pip install -e ".[develop]"
+```
+
+To generate a source distribution:
+```bash
+$ python3 -m pip install -U wheel build
+$ python3 -m build
+```
+
+The packages generated in `dist/` can be installed directly with `pip` or uploaded to PyPI using `twine`.

python/svi_client/SECURITY.md

@@ -0,0 +1 @@
+../../SECURITY.md

python/svi_client/TERMS.md

@@ -0,0 +1 @@
+../../TERMS.md

python/svi_client/pyproject.toml

@@ -0,0 +1,6 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=42",
+  "wheel",
+]

python/svi_client/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+markers =
+    slow: marks tests as slow (deselect with '-m "not slow"')
+

python/svi_client/setup.cfg

@@ -0,0 +1,44 @@
+[metadata]
+name = hydrotools.svi_client
+version = attr: hydrotools.svi_client._version.__version__
+author = Austin Raney
+author_email = [email protected]
+description = Retrieve Social Vulnerability Index data from The Center for Disease Control / The Agency for Toxic Substances and Disease Registry.
+long_description = file: README.md
+long_description_content_type = text/markdown
+charset = UTF-8
+license = USDOC
+license_files =
+    LICENSE
+url = https://github.com/NOAA-OWP/hydrotools
+project_urls =
+    Documentation = https://noaa-owp.github.io/hydrotools/hydrotools.svi_client.html
+    Source = https://github.com/NOAA-OWP/hydrotools/tree/main/python/svi_client
+    Tracker = https://github.com/NOAA-OWP/hydrotools/issues
+classifiers =
+    Development Status :: 3 - Alpha
+    Intended Audience :: Education
+    Intended Audience :: Science/Research
+    License :: Free To Use But Restricted
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+    Topic :: Scientific/Engineering :: Hydrology
+    Operating System :: OS Independent
+
+[options]
+packages = find_namespace:
+package_dir =
+    =src
+install_requires =
+    hydrotools._restclient
+    numpy >=1.20.0
+    pandas
+python_requires = >=3.7
+
+[options.packages.find]
+where = src
+
+[options.extras_require]
+develop =
+    pytest

python/svi_client/src/hydrotools/svi_client/__init__.py

@@ -0,0 +1,4 @@
+# removing __version__ import will cause build to fail. see: https://github.com/pypa/setuptools/issues/1724#issuecomment-627241822
+from ._version import __version__
+
+from .clients import SVIClient

python/svi_client/src/hydrotools/svi_client/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

python/svi_client/src/hydrotools/svi_client/clients.py

@@ -0,0 +1,87 @@
+import io
+from http import HTTPStatus
+from hydrotools._restclient import RestClient
+import pandas as pd
+
+# local imports
+from . import url_builders
+from .types import GeographicScale, Year, utilities
+
+
+class SVIClient:
+    _base_url = "https://svi.cdc.gov/"
+
+    def __init__(self) -> None:
+        self._rest_client = RestClient(
+            base_url=self._base_url, cache_filename="svi_client_cache"
+        )
+
+    def get(
+        self, location: str, geographic_scale: GeographicScale, year: Year
+    ) -> pd.DataFrame:
+        """[summary]
+
+        Parameters
+        ----------
+        location : str
+            state / national name or abbreviation (e.g. "AL", "US", "Wyoming", "new york")
+        geographic_scale : GeographicScale "census_tract" or "county"
+            "county" scale data *not* available in 2000 or 2010
+        year : Year
+            2000, 2010, 2014, 2016, or 2018
+
+        Returns
+        -------
+        pd.DataFrame
+            Dataframe of Social Vulnerability Index values at the census tract or county scale
+
+        Examples
+        --------
+        >>> client = SVIClient()
+        ... df = client.get("AL", "census_tract", "2018")
+                    ST    STATE ST_ABBR  STCNTY  ... M_UNINSUR  EP_UNINSUR MP_UNINSUR  E_DAYPOP
+        0      1  ALABAMA      AL    1015  ...        12      -999.0     -999.0       656
+        1      1  ALABAMA      AL    1015  ...        12      -999.0     -999.0       146
+        ...   ..      ...     ...     ...  ...       ...         ...        ...       ...
+        1178   1  ALABAMA      AL    1015  ...       129        10.0        4.0      1832
+        1179   1  ALABAMA      AL    1069  ...        98        17.7        4.4      2566
+
+        """
+
+        url_path = url_builders.build_csv_url(
+            location=location, geographic_scale=geographic_scale, year=year
+        )
+
+        request = self._rest_client.get(url_path)
+
+        if request.status != HTTPStatus.OK:  # 200
+            ...
+
+        serialized_text = io.StringIO(request.text())
+
+        return pd.read_csv(serialized_text)
+
+    @staticmethod
+    def svi_documentation_url(year: Year) -> str:
+        year = utilities.validate_year(year)
+
+        urls = {
+            "2000": "https://www.atsdr.cdc.gov/placeandhealth/svi/documentation/pdf/SVI2000Documentation-H.pdf",
+            "2010": "https://www.atsdr.cdc.gov/placeandhealth/svi/documentation/pdf/SVI-2010-Documentation-H.pdf",
+            "2014": "https://www.atsdr.cdc.gov/placeandhealth/svi/documentation/pdf/SVI2014Documentation_01192022.pdf",
+            "2016": "https://www.atsdr.cdc.gov/placeandhealth/svi/documentation/pdf/SVI2016Documentation_01192022.pdf",
+            "2018": "https://www.atsdr.cdc.gov/placeandhealth/svi/documentation/pdf/SVI2018Documentation_01192022_1.pdf",
+        }
+
+        url = urls.get(year, None)
+
+        # raise error if valid year not in urls.
+        # when new svi releases are added, this will purposefully break.
+        if url is None:
+            # raise error
+            error_message = (
+                f"documentation for year: {year} has not been added to SVIClient."
+            )
+            raise ValueError(error_message)
+
+        return url

python/svi_client/src/hydrotools/svi_client/types/__init__.py

@@ -0,0 +1,2 @@
+from .type_definitions import LOCATIONS, GeographicScale, DataFormat, Year
+from . import utilities

python/svi_client/src/hydrotools/svi_client/types/type_definitions.py

@@ -0,0 +1,70 @@
+from hydrotools._restclient import Alias, AliasGroup
+
+# typing imports
+from typing import Literal
+
+GeographicScale = Literal["census_tract", "county"]
+DataFormat = Literal["csv", "shp"]
+Year = Literal["2000", "2010", "2014", "2016", "2018", 2000, 2010, 2014, 2016, 2018]
+
+# Geography options:
+# source https://svi.cdc.gov/xmldata/SVI_StatesForDownload.xml
+# used by form on https://svi.cdc.gov/data-download-wcms.html
+
+# TODO: add "PuertoRico" and "States". will need to consider what datasets are available for these locations
+LOCATIONS = AliasGroup(
+    [
+        Alias("US", ["us", "united states"]),
+        Alias("Alabama", ["al", "alabama"]),
+        Alias("Alaska", ["ak", "alaska"]),
+        Alias("Arizona", ["az", "arizona"]),
+        Alias("Arkansas", ["ar", "arkansas"]),
+        Alias("California", ["ca", "california"]),
+        Alias("Colorado", ["co", "colorado"]),
+        Alias("Connecticut", ["ct", "connecticut"]),
+        Alias("Delaware", ["de", "delaware"]),
+        Alias("DistrictofColumbia", ["dc", "district of columbia"]),
+        Alias("Florida", ["fl", "florida"]),
+        Alias("Georgia", ["ga", "georgia"]),
+        Alias("Hawaii", ["hi", "hawaii"]),
+        Alias("Idaho", ["id", "idaho"]),
+        Alias("Illinois", ["il", "illinois"]),
+        Alias("Indiana", ["in", "indiana"]),
+        Alias("Iowa", ["ia", "iowa"]),
+        Alias("Kansas", ["ks", "kansas"]),
+        Alias("Kentucky", ["ky", "kentucky"]),
+        Alias("Louisiana", ["la", "louisiana"]),
+        Alias("Maine", ["me", "maine"]),
+        Alias("Maryland", ["md", "maryland"]),
+        Alias("Massachusetts", ["ma", "massachusetts"]),
+        Alias("Michigan", ["mi", "michigan"]),
+        Alias("Minnesota", ["mn", "minnesota"]),
+        Alias("Mississippi", ["ms", "mississippi"]),
+        Alias("Missouri", ["mo", "missouri"]),
+        Alias("Montana", ["mt", "montana"]),
+        Alias("Nebraska", ["ne", "nebraska"]),
+        Alias("Nevada", ["nv", "nevada"]),
+        Alias("NewHampshire", ["nh", "new hampshire"]),
+        Alias("NewJersey", ["nj", "new jersey"]),
+        Alias("NewMexico", ["nm", "new mexico"]),
+        Alias("NewYork", ["ny", "new york"]),
+        Alias("NorthCarolina", ["nc", "north carolina"]),
+        Alias("NorthDakota", ["nd", "north dakota"]),
+        Alias("Ohio", ["oh", "ohio"]),
+        Alias("Oklahoma", ["ok", "oklahoma"]),
+        Alias("Oregon", ["or", "oregon"]),
+        Alias("Pennsylvania", ["pa", "pennsylvania"]),
+        Alias("RhodeIsland", ["ri", "rhode island"]),
+        Alias("SouthCarolina", ["sc", "south carolina"]),
+        Alias("SouthDakota", ["sd", "south dakota"]),
+        Alias("Tennessee", ["tn", "tennessee"]),
+        Alias("Texas", ["tx", "texas"]),
+        Alias("Utah", ["ut", "utah"]),
+        Alias("Vermont", ["vt", "vermont"]),
+        Alias("Virginia", ["va", "virginia"]),
+        Alias("Washington", ["wa", "washington"]),
+        Alias("WestVirginia", ["wv", "west virginia"]),
+        Alias("Wisconsin", ["wi", "wisconsin"]),
+        Alias("Wyoming", ["wy", "wyoming"]),
+    ]
+)

python/svi_client/src/hydrotools/svi_client/types/utilities.py

@@ -0,0 +1,30 @@
+import typing
+
+
+# local imports
+from .type_definitions import LOCATIONS, GeographicScale, Year
+
+
+def validate_location(location: str) -> str:
+    location_key = LOCATIONS.get(location.lower())  # noqa
+
+    if location_key is None:
+        ...
+
+    return location_key
+
+
+def validate_geographic_scale(geographic_scale: GeographicScale) -> str:
+    if geographic_scale not in typing.get_args(GeographicScale):
+        ...
+
+    return geographic_scale
+
+
+def validate_year(year: Year) -> str:
+    year_str = str(year)
+
+    if year_str not in typing.get_args(Year):
+        ...
+
+    return year_str