droughtmonitor 0.1.5

A python-based API wrapper for U.S. Drought Monitor

droughtmonitor

-----

Table of Contents

• Introduction
• Installation
• Usage
• License

Introduction

The droughtmonitor package serves as an unofficial API wrapper for U.S. Drought Monitor and provides a set of tools for making programatic access to the underlying data more accessable. The U.S. Drought Monitor website contains a landing page for accessing both tabular and spatial data. However, accessing the data through this channel can be tedious for charts, measures, or analysis that need to be frequently updated. Programatic access is possible through the existing API, but can also be tediuos without prior working knowledge of REST APIs. The droughtmonitor package strikes a balance between the two methods as it allows programatic access to enhance reproducability while requireing no additional techincal overhead beyond basic understanding of python.

Disclaimer This product uses data from the U.S. Drought Monitor API, but is not endorsed by or affiliated with U.S. Drought Monitor or the Federal Government.

Installation

Currently, droughtmonitor can be installed from PyPI using pip. The drought monitor API does not utilize API keys meaning no further setup is required.

# install using pip
pip install droughtmonitor

Usage

Usage of the droughtmonitor package starts by creating an object of the class USDM which is done by specifying a geographic location (geography) and time period (time_period). The geography can take the form of:

• "us" or "conus" for national data (all of the United States or continental US)
• A state abbreviation or FIPS code (ex: "CA", "ca", 6, "06" all return data for California)
• A county FIPS code (ex: 1001, "01001")
• A list of geographies (ex: ["CA", "OR", "WA"])

An optional group_by parameter enables batch processing for multiple geographies:

• group_by="county": Retrieves data for all counties in the specified geography
  • Works with a single state (e.g., geography="CA")
  • Works with a list of states (e.g., geography=["CA", "OR"])
  • Works with national geography (e.g., geography="US") to get all counties in the US
• group_by="state": When geography is national ("US"/"CONUS"), retrieves data for all states

Note on API calls: When using group_by with large geographies, the package may make many API calls. By default, you'll be prompted to confirm that you want to proceed if a query will make more than 50 API calls. You can control this with the confirm=False parameter or adjust the threshold with confirm_threshold.

# import the usdm module from drought monitor
from droughtmonitor import usdm

# create a drought object of the USDM class specifying California from 2020 to 2024
drought = usdm.USDM(geography = "CA", time_period=list(range(2020,2024)))

# create a drought object of the USDM class specifying the continential US in the first month of 2020
drought = usdm.USDM(geography = "conus", time_period=["1/1/2020", "1/31/2020"])

# create a drought object for all counties in California
drought = usdm.USDM(geography = "CA", group_by="county", time_period=[2020, 2021])

# create a drought object for counties in multiple states
drought = usdm.USDM(geography = ["CA", "NV", "AZ"], group_by="county", time_period=[2020, 2021])

# create a drought object for all counties in the US (will prompt for confirmation)
drought = usdm.USDM(geography = "US", group_by="county", time_period=[2020])

# create a drought object for all US states
drought = usdm.USDM(geography = "US", group_by="state", time_period=2024)

Weeks in Drought

Once an object of the USDM class is created, the get_weeks_in_drought method can be used to obtain the number of weeks that the specified geography was at a specified drought level. An optional drought_threshold parameter can be specified as one of [0,1,2,3,4] corresponding to the drought levels used by U.S. Drought Monitor (default is to return measures for all drought levels in distinct columns). Another optional stat parameter can be specified as either "consecutive" or "nonconsecutive" to specify if the number of weeks at the specified drought level needs to be consecutive or not.

Note: This method ignores the group_by parameter since the USDM API only provides weeks in drought data at the county level. The method always returns data at the county level regardless of the geography level specified.

# create drought object for California during 2021 using the state fips code
drought = usdm.USDM(geography = 6 , time_period=2021)

# get number of consecutive weeks at D3 level drought
wid = drought.get_weeks_in_drought(drought_threshold = 3, stat = "consecutive")
wid.head()

# get number of nonconsecutive weeks at all drought levels
wid = drought.get_weeks_in_drought(stat = "nonconsecutive")
wid.head()

# get number of consecutive and nonconsecutive weeks at all drought levels
wid = drought.get_weeks_in_drought()
wid.head()

Comprehensive Statistics

The get_comp_stats method can be used to return several different statistics for each drought level for a specified geography and time period. The argument stat controls which statistic is returned and can be one of ["Area", "AreaPercent", "Population", "PopulationPercent", "DSCI"] (not case sensitive) which correspond to the total area, percentage of an area, the total population, percentage of the population, and the drought severity coverage index. The default behavior is to return the specified statistic for all drought levels (in separate columns). If statistics for only one or a few drought threshold are desired, this can be achieved by specifying the drought_threshold parameter with a single integer or list of integers out of [0,1,2,3,4].

The group_by parameter enables batch processing for multiple geographies. When group_by="county" is specified, statistics are retrieved for all counties in the specified geography (state, list of states, or national). When group_by="state" is specified with national geography, statistics are retrieved for all states.

Basic Examples

# create drought object for a single county from 2000 to 2024 using county fips code
drought = usdm.USDM(geography = "01001" , time_period=list(range(2000,2024)))

# get the percentage of the county that was in each drought level
# for each week in the specified time period
cs = drought.get_comp_stats(stat = "AreaPercent")
cs.head()

# create drought object for california in 2024
drought = usdm.USDM(geography = "CA" , time_period=2024)

# get the total population subject to each drought level for
# every week in 2024
cs = drought.get_comp_stats(stat = "Population")
cs.head()

# return only the area under D2 level drought
cs = drought.get_comp_stats(stat = "Area", drought_threshold = 2)
cs.head()

# get statistics for all counties in California
drought = usdm.USDM(geography = "CA", group_by="county", time_period=2024)
cs = drought.get_comp_stats(stat = "AreaPercent")
cs.head()
# Result includes columns: county_fips, county_name, state_code, state_name, mapStartDate, mapEndDate, etc.

# get statistics for counties in multiple states (CA, NV, AZ)
drought = usdm.USDM(geography = ["CA", "NV", "AZ"], group_by="county", time_period=[2020, 2021])
cs = drought.get_comp_stats(stat = "Population")
cs.head()

# get statistics for all counties in the US (will prompt for confirmation)
# Note: This will make ~16,000 API calls (3,256 counties × 5 statistics)
drought = usdm.USDM(geography = "US", group_by="county", time_period=[2020])
cs = drought.get_comp_stats()
# User will be prompted: "Warning: This query will make approximately 16280 API calls. Do you want to proceed? (yes/no):"

# get statistics for all states
drought = usdm.USDM(geography = "US", group_by="state", time_period=2024)
cs = drought.get_comp_stats(stat = "Population")
cs.head()

# bypass confirmation prompt for large queries
drought = usdm.USDM(geography = "US", group_by="county",
                    time_period=[2020], confirm=False)
cs = drought.get_comp_stats()

# adjust the confirmation threshold (default is 50 API calls)
drought = usdm.USDM(geography = ["CA", "OR", "WA"], group_by="county",
                    time_period=[2020], confirm_threshold=200)
cs = drought.get_comp_stats()

Spatial Data

Spatial data can also be retrieved using droughtmonitor. To do so, create a USDM object and then call the get_spatial_data method. Spatial data is only avaliable at the national level, meaning "us" is the only valid geography for USDM when get_spatial_data is used. For the time_period argument, either a single date or a range of dates can be entered. In the case of a single date, the USDM map that has the closest date to the entered date will be retrieved. In the case of a range of dates being entered, the closest maps to the start and end date will be found, then those maps along with all maps between these dates, will be returned.

Example: retrieving data for a single date.

# import drought monitor
from droughtmonitor import usdm

# create a USDM object for the us with a single date as the time period
drought = usdm.USDM(geography = "us", time_period="1/1/2020")

# return geo-spatial drought data in json format for the map released closest to 1/1/2020
geo = drought.get_spatial_data(format = "json")

# data is returned as a dictionary with the keys equal to the date of the map (in this case the returned spatial data is from "12/31/2019" as that was the map with the closest date to the entered date)
geo['12/31/2019']

Example: retrieving data for a range of dates.

# import drought monitor
from droughtmonitor import usdm

# create a USDM object for the us with a single date as the time period
drought = usdm.USDM(geography = "us", time_period=['1/1/2020','1/31/2020'])

# return geo-spatial drought data in data frame format
geo_data = drought.get_spatial_data(format = "df")

# data is returned as a dictionary with the keys equal to the date
geo_data['12/31/2019']

License

droughtmonitor is distributed under the terms of the MIT license.