Tutorial prep (#140)

* Update state codes

* Link to WQP swagger doc

Author: thodson-usgs

dataretrieval/codes/states.py

@@ -1,54 +1,108 @@
 """List of 2-digit state codes with commented full names."""
-state_codes = [
-    'al',  # Alabama
-    'ak',  # Alaska
-    'az',  # Arizona
-    'ar',  # Arkansas
-    'ca',  # California
-    'co',  # Colorado
-    'ct',  # Connecticut
-    'de',  # Delaware
-    'dc',  # District of Columbia
-    'fl',  # Florida
-    'ga',  # Georgia
-    'hi',  # Hawaii
-    'id',  # Idaho
-    'il',  # Illinois
-    'in',  # Indiana
-    'ia',  # Iowa
-    'ks',  # Kansas
-    'ky',  # Kentucky
-    'la',  # Louisiana
-    'me',  # Maine
-    'md',  # Maryland
-    'ma',  # Massachusetts
-    'mi',  # Michigan
-    'mn',  # Minnesota
-    'ms',  # Mississippi
-    'mo',  # Missouri
-    'mt',  # Montana
-    'ne',  # Nebraska
-    'nv',  # Nevada
-    'nh',  # New Hampshire
-    'nj',  # New Jersey
-    'nm',  # New Mexico
-    'ny',  # New York
-    'nc',  # North Carolina
-    'nd',  # North Dakota
-    'oh',  # Ohio
-    'ok',  # Oklahoma
-    'or',  # Oregon
-    'pa',  # Pennsylvania
-    'ri',  # Rhode Island
-    'sc',  # South Carolina
-    'sd',  # South Dakota
-    'tn',  # Tennessee
-    'tx',  # Texas
-    'ut',  # Utah
-    'vt',  # Vermont
-    'va',  # Virginia
-    'wa',  # Washington
-    'wv',  # West Virginia
-    'wi',  # Wisconsin
-    'wy',  # Wyoming
-]
+state_codes = {
+    "Alabama":              "al",
+    "Alaska":               "ak",
+    "Arizona":              "az",
+    "Arkansas":             "ar",
+    "California":           "ca",
+    "Colorado":             "co",
+    "Connecticut":          "ct",
+    "Delaware":             "de",
+    "District of Columbia": "dc",
+    "Florida":              "fl",
+    "Georgia":              "ga",
+    "Hawaii":               "hi",
+    "Idaho":                "id",
+    "Illinois":             "il",
+    "Indiana":              "in",
+    "Iowa":                 "ia",
+    "Kansas":               "ks",
+    "Kentucky":             "ky",
+    "Louisiana":            "la",
+    "Maine":                "me",
+    "Maryland":             "md",
+    "Massachusetts":        "ma",
+    "Michigan":             "mi",
+    "Minnesota":            "mn",
+    "Mississippi":          "ms",
+    "Missouri":             "mo",
+    "Montana":              "mt",
+    "Nebraska":             "ne",
+    "Nevada":               "nv",
+    "New Hampshire":        "nh",
+    "New Jersey":           "nj",
+    "New Mexico":           "nm",
+    "New York":             "ny",
+    "North Carolina":       "nc",
+    "North Dakota":         "nd",
+    "Ohio":                 "oh",
+    "Oklahoma":             "ok",
+    "Oregon":               "or",
+    "Pennsylvania":         "pa",
+    "Rhode Island":         "ri",
+    "South Carolina":       "sc",
+    "South Dakota":         "sd",
+    "Tennessee":            "tn",
+    "Texas":                "tx",
+    "Utah":                 "ut",
+    "Vermont":              "vt",
+    "Virginia":             "va",
+    "Washington":           "wa",
+    "West Virginia":        "wv",
+    "Wisconsin":            "wi",
+    "Wyoming":              "wy",
+}
+
+fips_codes = {
+    "Alabama":              "01",
+    "Alaska":               "02",
+    "Arizona":              "04",
+    "Arkansas":             "05",
+    "California":           "06",
+    "Colorado":             "08",
+    "Connecticut":          "09",
+    "Delaware":             "10",
+    "District of Columbia": "11",
+    "Florida":              "12",
+    "Georgia":              "13",
+    "Hawaii":               "15",
+    "Idaho":                "16",
+    "Illinois":             "17",
+    "Indiana":              "18",
+    "Iowa":                 "19",
+    "Kansas":               "20",
+    "Kentucky":             "21",
+    "Louisiana":            "22",
+    "Maine":                "23",
+    "Maryland":             "24",
+    "Massachusetts":        "25",
+    "Michigan":             "26",
+    "Minnesota":            "27",
+    "Mississippi":          "28",
+    "Missouri":             "29",
+    "Montana":              "30",
+    "Nebraska":             "31",
+    "Nevada":               "32",
+    "New Hampshire":        "33",
+    "New Jersey":           "34",
+    "New Mexico":           "35",
+    "New York":             "36",
+    "North Carolina":       "37",
+    "North Dakota":         "38",
+    "Ohio":                 "39",
+    "Oklahoma":             "40",
+    "Oregon":               "41",
+    "Pennsylvania":         "42",
+    "Rhode Island":         "44",
+    "South Carolina":       "45",
+    "South Dakota":         "46",
+    "Tennessee":            "47",
+    "Texas":                "48",
+    "Utah":                 "49",
+    "Vermont":              "50",
+    "Virginia":             "51",
+    "Washington":           "53",
+    "West Virginia":        "54",
+    "Wisconsin":            "55",
+    "Wyoming":              "56",
+}

dataretrieval/wqp.py

@@ -19,6 +19,12 @@
 def get_results(ssl_check=True, **kwargs):
     """Query the WQP for results.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -94,6 +100,12 @@ def get_results(ssl_check=True, **kwargs):
 def what_sites(ssl_check=True, **kwargs):
     """Search WQP for sites within a region with specific data.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -134,6 +146,12 @@ def what_sites(ssl_check=True, **kwargs):
 def what_organizations(ssl_check=True, **kwargs):
     """Search WQP for organizations within a region with specific data.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -172,6 +190,12 @@ def what_organizations(ssl_check=True, **kwargs):
 def what_projects(ssl_check=True, **kwargs):
     """Search WQP for projects within a region with specific data.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -210,6 +234,12 @@ def what_projects(ssl_check=True, **kwargs):
 def what_activities(ssl_check=True, **kwargs):
     """Search WQP for activities within a region with specific data.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -252,6 +282,12 @@ def what_detection_limits(ssl_check=True, **kwargs):
     """Search WQP for result detection limits within a region with specific
     data.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -296,6 +332,12 @@ def what_detection_limits(ssl_check=True, **kwargs):
 def what_habitat_metrics(ssl_check=True, **kwargs):
     """Search WQP for habitat metrics within a region with specific data.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -334,6 +376,12 @@ def what_habitat_metrics(ssl_check=True, **kwargs):
 def what_project_weights(ssl_check=True, **kwargs):
     """Search WQP for project weights within a region with specific data.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -375,6 +423,12 @@ def what_project_weights(ssl_check=True, **kwargs):
 def what_activity_metrics(ssl_check=True, **kwargs):
     """Search WQP for activity metrics within a region with specific data.
 
+    Any WQP API parameter can be passed as a keyword argument to this function.
+    More information about the API can be found at:
+    https://www.waterqualitydata.us/#advanced=true
+    or the Swagger documentation at:
+    https://www.waterqualitydata.us/data/swagger-ui/index.html?docExpansion=none&url=/data/v3/api-docs#/
+
     Parameters
     ----------
     ssl_check: bool
@@ -487,16 +541,19 @@ def _alter_kwargs(kwargs):
 
     return kwargs
 
+
 def _warn_v3_profiles_outage():
     """Private function for warning message about WQX 3.0 profiles
     """
 
-    warnings.warn(('USGS discrete water quality data availability '
-                   'and format are changing. Beginning in March 2024 '
-                   'the data obtained from legacy profiles will not '
-                   'include new USGS data or recent updates to existing '
-                   'data. To view the status of changes in data '
-                   'availability and code functionality, visit: '
-                   'https://doi-usgs.github.io/dataRetrieval/articles/Status.html. '
-                   'If you have additional questions about these changes, '
-                   'email [email protected].'))
+    warnings.warn(
+        'USGS discrete water quality data availability '
+        'and format are changing. Beginning in March 2024 '
+        'the data obtained from legacy profiles will not '
+        'include new USGS data or recent updates to existing '
+        'data. To view the status of changes in data '
+        'availability and code functionality, visit: '
+        'https://doi-usgs.github.io/dataRetrieval/articles/Status.html. '
+        'If you have additional questions about these changes, '
+        'email [email protected].'
+    )