download(*, fire=None, version=None, latest=False, start_date=None, assessment_date=None, publication_date=None, extent=None, extent_type=None, extent_relation='intersects', bbox=None, point=None, geometry=None, geometry_relation='intersects', geometry_layer=None, geometry_driver=None, geometry_encoding=None, max_queries=None, max_per_query=500, max_fires=None, max_assessments=None, max_products=None, offset=0, truncate=False, timeout=15, session=None, parent=None, normalize=False, strict=False, duplicates='error', files=None, exclude_files=False, extract=True, max_gb=2, failures='warn', dry_run=False)

Searches the PWFDF collection and downloads matching assessments to the local file system. By default, downloads all files. These include:

Name	Description
metadata.json	A JSON file with metadata about an assessment’s fire event, implementation, hazard models, and input datasets.
GeoJSON.zip	Hazard assessment results in a GeoJSON format.
Shapefile.zip	Hazard assessment results in a Shapefile format.
median-thresholds.csv	Holds a table of median rainfall thresholds as calculated over the stream segment network and catchment basins.
inputs.zip	A zip archive of hazard assessment input datasets that are not accessible via a separate DOI.
configuration.txt	Records the configuration settings used by the wildcat package to implement the hazard assessment.
fgdc-metadata.xml	FGDC-compliant XML metadata describing the assessment for the ScienceBase interface.

Returns a dict mapping each assessment name onto the Path of the folder holding the assessment’s downloaded files.

Folder Paths

download(..., *, parent)
download(..., *, normalize=True)
download(..., *, strict=True)
download(..., *, duplicates)

File path download options. Downloads matching assessments into subfolders matching the assessment names. By default, creates subfolders in the current folder. Use parent to specify a different parent folder instead. By default, subfolder names may include spaces and punctuation. Set normalize=True to replaces spaces and punctuation with underscores and hyphens. Set strict=True to raise an error if the parent folder is not empty. Use duplicates to indicate what should happen if an assessment subfolder already exists. Options are:

Action	Description
skip (default)	Does not download the assessment if its sub-folder already exists.
replace	Downloads the assessment and overwrites the existing folder.
error	Raises an error

Downloaded Files

download(..., *, files)
download(..., *, files, exclude_files=True)
download(..., *, extract=False)
download(..., *, max_gb)

Options controlling downloaded files. Use files to only download specified files. Alternatively, use files and set exclude_files=True to download everything except the specified files. By default, extracts any downloaded zip archives. Set extract=False to prevent this behavior. By default, raises an error if the downloaded data would exceed 2 GB. Use max_gb to change this limit.

Misc Download

download(..., *, failures)
download(..., *, dry_run=True)

Misc download options. Use failures to indicate what should happen when an assessment fails to download. Options are:

Action	Description
error	Raises a DownloadError and exits.
warn (default)	Raises a DownloadWarning and continues to the next assessment.
ignore	Continues to the next assessment.

Set dry_run=True to run the command without actually downloading any data. The effects of the command can then be determined by inspecting the logs.

Fire Event

download(..., *, fire)

Searches for assessments whose fire matches the given name. Note that the provided fire name must exactly match an assessment’s fire name (case-insensitive). Partial matches are not supported.

Version Number

download(..., *, version)
download(..., *, latest=True)

Searches for assessments matching the provided version number. If a full 2-part version number, only returns assessments matching that version. Use a single number to match assessments with a given major version number. Set latest=True to only return the latest assessment version of matching fires. If version is a major version number, and latest=True, matches the latest assessment with the specified major version number.

Date Range

download(..., *, start_date)
download(..., *, assessment_date)
download(..., *, publication_date)

Searches for assessments matching a given date range. Use start_date to filter by the fire start date, assessment_date to filter by the date the assessment was run, and publication_date to filter by the date that the assessment was published to ScienceBase.

In general, a date input may be a (1) integer year, (2) datetime.date object, (3) datetime.datetime object, (4) YYYY, YYYY-MM, or YYYY-MM-DD date string, or (5) a tuple of two such inputs. If the input is a year or a month, matches all assessments that fall within that interval. If the input is a 2-tuple, then it is interpreted as a date range and the search matches assessments that fall between the two dates. If the first date is a year or month, then the date range will begin on the first day of that interval. If the last date is a year or month, then the range will end on the final day of that interval.

Extent

download(..., *, extent)
download(..., *, extent_type)
download(..., *, extent_relation)

Searches for assessments in a spatial area with well-known coordinates, such as a country or state. The extent may be the name of a supported extent, or an integer extent ID. Use extent_relation to set the spatial relationship between the extent and the search results. Options are:

Relation	Description
intersects	(default) Matches assessments that intersect the extent at any point
within	Only matches assessments that are fully contained within the extent
disjoint	Matches assessments that do not intersect the extent at any point

Use extent_type to specify the type of extent being searched. This option is usually not necessary, but can be useful for guarding against extents with similar names.

Geometry

download(..., *, bbox)
download(..., *, point)
download(..., *, geometry)
download(..., *, geometry_relation)

Searches for assessments in a custom geospatial area. You may use one of the following search types at a time:

Search Type	Description
bbox	Searches a custom bounding box. The input may be either (1) a WGS-84 [xmin, ymin, xmax, ymax] coordinate sequence, or (2) a GIS file path. If a file, then the bounding box is calculated from the contained geometries.
point	Searches a custom geospatial point. The input may be either (1) a [lon, lat] sequence, or (2) a GIS file path. If a file, then the point is determined as the center of the bounding box of the contained geometries.
geometry	Searches a custom geospatial geometry. The input may be either (1) a WGS-84 GeoJSON-like dict (with type and coordinates keys), or (2) a GIS file path. In practice, only coarse geometries are supported (fewer than 100 coordinate points).

Note

GIS files may use any CRS. Unlike explicit coordinate points, they are not limited to WGS-84.

Use geometry_relation to set the spatial relationship between the geometry and the search results. Options are:

Relation	Description
intersects	(default) Matches assessments that intersect the geometry at any point
within	Only matches assessments that are fully contained within the geometry
disjoint	Matches assessments that do not intersect the geometry at any point

Geometry File IO

download(..., *, geometry_layer)
download(..., *, geometry_driver)
download(..., *, geometry_encoding)

Advanced options for reading a geometry from a GIS file. Use geometry_layer when the file has multiple data layers. The layer may either be a layer name, or an integer index. Reads the first layer if not otherwise specified. Use geometry_driver to specify the file format when the file uses a non-standard extension. Most drivers will automatically detect the file encoding, but you can use geometry_encoding to explicitly specify the encoding if detection fails.

Product Limits

download(..., *, max_fires)
download(..., *, max_assessments)
download(..., *, max_products)

Options that ensure search results fall within expected parameters. Use max_fires to raise an error if the total number of matching fire events exceeds an expected limit. Use max_assessments to raise an error if the total number of matching assessments exceeds an expected limit. The max_products input is not recommended for most users, but can be used to raise an error if the total number of matching ScienceBase product records exceeds an expected limit.

API Queries

download(..., *, max_queries)
download(..., *, max_per_query)

Advanced options for querying the ScienceBase API. Use max_queries to raise an error if the total number of required API queries would exceed an allowed limit. Use max_per_query to specify the total number of product records that should be retrieved per API query. Defaults to 500 and may not exceed 1000.

Paging

download(..., *, max_products, truncate=True)
download(..., *, offset)

Advanced options for implementing custom paging schemes. Use offset to skip the first N search results before retrieving content. Set truncate=True to truncate results after max_products products, skipping all remaining products (and not raising a max products limit error).

Web Request

download(..., *, timeout)
download(..., *, session)

Advanced web request options. Use timeout to specify a maximum time in seconds for connecting to the ScienceBase server (default is 15 seconds). This option is typically a scalar, but may also use a vector with two elements. In this case, the first value is the timeout to connect with the server, and the second value is the time for the server to return the first byte. You can also set timeout=None, in which case server queries will never time out. This may be useful for some slow connections, but is generally not recommended as your code may hang indefinitely if the server fails to respond.

Use the session option to provide a pre-instantiated requests.Session object for querying the ScienceBase API. If not provided, the command creates (and then closes) a new Session for the request. If you provide a Session object as input, then the session is used to implement the query, but is not closed afterwards. This can be useful when calling pwfdf_api multiple times, as the Session object will preserve the underlying TCP connection, which can improve performance.

Inputs:

• fire (str) – The name of a fire event

• version (str | int) – A version number, or major version number

• latest (bool) – True to filter search results to the latest version.

• start_date (str | int | datetime.date | datetime.datetime | tuple) – A date range in which matching fire events began

• assessment_date (str | int | datetime.date | datetime.datetime | tuple) – A date range in which matching assessment were performed

• publication_date (str | int | datetime.date | datetime.datetime | tuple) – A date range in which matching assessments were published to ScienceBase

• extent (str | int) – An extent name or integer ID

• extent_type (str) – The type of extent being searched

• extent_relation (str) – The spatial relationship between the extent and the search results

• bbox (str | Path | [float, float, float, float]) – A custom bounding box to search. Either a file path, or a WGS-84 [xmin, ymin, xmax, ymax] coordinate sequence

• point (str | Path | [float, float]) – A custom geospatial point to search. Either a file path, or a [lon, lat] point.

• geometry (str | Path | dict) – A custom geospatial geometry to search. Either a file path or a WGS-84 GeoJSON geometry-like dict

• geometry_relation (str) – The spatial relationship between the geometry and the search results

• geometry_layer (str | int) – The name or index of a data layer in a geometry file

• geometry_driver (str) – The file format driver to use to read a geometry file

• geometry_encoding (str) – The file encoding to use to read a geometry file

• max_fires (int) – A maximum allowed number of fires in the search results

• max_assessments (int) – A maximum allowed number of assessments in the search results

• max_products (int) – A maximum allowed number of ScienceBase product records in the search results

• max_queries (int) – A maximum allowed number of ScienceBase API queries

• max_per_query (int) – The number of product records to retrieve per ScienceBase API query

• offset (int) – The number of product records to skip before retrieving results

• truncate (bool) – True to skip all products after the first max_products results. False (default) to raise an error if nproducts > max_products

• timeout (float | (float, float)) – The maximum allowed number of seconds to connect with the ScienceBase server

• session (requests.Session) – A pre-existing requests.Session object that should be used to connect with the ScienceBase API

• parent (Path ? str) – The path to the parent folder where assessment subfolders will be created

• normalize (bool) – True to replace spaces and punctuation in subfolder names with underscores and hyphens. False (default) to use the raw assessment names

• strict (bool) – True to raise an error if the parent folder is not empty. False (default) to ignore the status of the parent folder

• duplicates (str) – What should happend when an assessment sub-folder already exists

• files (list[str]) – Indicates which files to download

• exclude_files (bool) – True to download all files except the indicated files. False (default) to only download the indicated files

• extract (bool) – True (default) to unzip any download zip archives. False to not unzip the archives

• max_gb (float) – A maximum allowed size of downloaded files in gigabytes. Raises an error if the download would exceed this limit

• failures (str) – What should happen if an assessment fails to download

• dry_run (bool) – True to not download any data. False (default) to download data

Outputs:

dict[str, Path] – Maps assessment names onto the Paths of their downloaded subfolders