Python API

The complete reference guide to using pwfdf-api within a Python session.

Main Functions

assessments

Search the PWFDF collection and return the names of matching assessments

browse

Open PWFDF search results in a web browser

download

Search PWFDF and download matching assessments to the local file system

metadata

Serach PWFDF and return metadata.json info for matching assessments

Documentation

version

Returns the version number of the current pwfdf-api installation

docs

Opens the pwfdf-api package docs in a web browser

data_spec

Opens the PWFDF data specification in a web browser

Low Level Functions

sbjson

Return sbJSON info for PWFDF assessments

query

Query the PWFDF collection and return the ScienceBase API response

url

Return the URL used to search PWFDF with given search filters

Auxiliary Modules

extents

Info on supported extents

catalog

Info on ScienceBase catalog resources

parent

Info on the PWFDF parent item

item

Info on queried ScienceBase items

logging

Configure pwfdf-api logging streams

Main Commands

pwfdf_api.assessments(*, 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)

Searches the PWFDF collection with any provided search criteria, and returns the names of hazard assessments that match all the provided search criteria. The output list of assessment names is sorted in alphabetical order.

Fire Event
assessments(..., *, 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
assessments(..., *, version)
assessments(..., *, 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
assessments(..., *, start_date)
assessments(..., *, assessment_date)
assessments(..., *, 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
assessments(..., *, extent)
assessments(..., *, extent_type)
assessments(..., *, 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
assessments(..., *, bbox)
assessments(..., *, point)
assessments(..., *, geometry)
assessments(..., *, 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
assessments(..., *, geometry_layer)
assessments(..., *, geometry_driver)
assessments(..., *, 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
assessments(..., *, max_fires)
assessments(..., *, max_assessments)
assessments(..., *, 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
assessments(..., *, max_queries)
assessments(..., *, 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
assessments(..., *, max_products, truncate=True)
assessments(..., *, 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
assessments(..., *, timeout)
assessments(..., *, 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

Outputs:

list[str] – The names of assessments that match all given search filters. The names are sorted in alphabetical order.

pwfdf_api.browse(*, fire=None, version=None, 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=None, offset=None, json=False, fields=None, new=0, autoraise=True)

Opens PWFDF search results in a web browser.

Open Search Results
browse(...)
browse(..., *, json=True)
browse(..., *, json=True, fields)

By default, opens the search results in the ScienceBase user interface. Set json=True to open an sbJSON API response instead. Use fields to indicate the sbJSON fields to include in the response.

Fire Event
browse(..., *, 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
browse(..., *, version)

Searches for assessments matching the provided version number.

Caution

The version must be a full 2-part version number. Major version numbers are not supported.

Date Range
browse(..., *, start_date)
browse(..., *, assessment_date)
browse(..., *, 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
browse(..., *, extent)
browse(..., *, extent_type)
browse(..., *, 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
browse(..., *, bbox)
browse(..., *, point)
browse(..., *, geometry)
browse(..., *, 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
browse(..., *, geometry_layer)
browse(..., *, geometry_driver)
browse(..., *, 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.

Paging
browse(..., *, max)
browse(..., *, offset)

Paging options for the ScienceBase API. Use max to set the maximum number of ScienceBase product records that should be retrieved. Defaults to 500 and cannot exceed 1000. Use offset to specify the number of ScienceBase products to skip before retrieving search results.

Browser Options
browse(..., *, new)
browse(..., *, autoraise=False)

Web browser options. The new input controls how the page is opened. 0 opens in the current window, 1 opens a new window, and 2 opens a new tab. Set autoraise=False to disable raising the opened page when possible.

Note

Many web browsers ignore both these options.

Inputs:

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

  • version (str) – A version number

  • 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 (int) – The maximum number of ScienceBase records to retrieve per API query

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

  • json (bool) – True to open the web page for an sbJSON API response. False (default) to open results in the ScienceBase user interface

  • fields (list[str]) – A list of sbJSON fields to query

  • new (0 | 1 | 2) – (0 - default) current window, (1) new window, (2) new tab

  • autoraise (bool) – True (default) to autoraise the page. False to not autoraise

Outputs:

bool – True if the page was opened successfully. Otherwise False.

pwfdf_api.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

pwfdf_api.metadata(*, 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, failures='error')

Searches the PWFDF collection and returns metadata.json info for all matching assessments as a dict. The keys of the dict are the names of the matching hazard assessments, and each value is a dict holding the assessment’s metadata.json info. Each assessment’s metadata includes information on the fire event, assessment version, bounding box, input datasets, and hazard model implementation. You can find complete documentation of the metadata fields in the PWFDF data spec.

Fire Event
metadata(..., *, 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
metadata(..., *, version)
metadata(..., *, 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
metadata(..., *, start_date)
metadata(..., *, assessment_date)
metadata(..., *, 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
metadata(..., *, extent)
metadata(..., *, extent_type)
metadata(..., *, 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
metadata(..., *, bbox)
metadata(..., *, point)
metadata(..., *, geometry)
metadata(..., *, 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
metadata(..., *, geometry_layer)
metadata(..., *, geometry_driver)
metadata(..., *, 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
metadata(..., *, max_fires)
metadata(..., *, max_assessments)
metadata(..., *, 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
metadata(..., *, max_queries)
metadata(..., *, 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
metadata(..., *, max_products, truncate=True)
metadata(..., *, 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
metadata(..., *, timeout)
metadata(..., *, 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.

Missing Metadata
metadata(..., *, failures)

Specifies what should happen if an assessment is missing metadata.json info. Options are:

Action

Description

error (default)

Raises a MetadataError and exits

warning

Raises a MetadataWarning, returns only the assessment’s ID, and continues to the next assessment

ignore

Returns only the assessment’s ID, and continutes to the next assessment
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

  • failures (str) – What should happen when an assessment is missing metadata.json info

Outputs:

dict[str, dict] – The metadata.json info for the matching assessments

Documentation

pwfdf_api.version()

Returns the version number of the current pwfdf-api installation

version()

Returns the version number. Note that the version number does not begin with a v prefix.

Outputs:

str – The version number of the current installation

pwfdf_api.docs(*, new=0, autoraise=True)

Opens the pwfdf-api docs in a web browser

Open Docs
docs()

Opens the pwfdf-api docs in a web browser. Returns a boolean indicating whether the page was successfully opened.

Browser Options
docs(..., *, new)
docs(..., *, autoraise=False)

Web browser options. The new input controls how the page is opened. 0 opens in the current window, 1 opens a new window, and 2 opens a new tab. Set autoraise=False to disable raising the opened page when possible.

Note

Many web browsers ignore both these options.

Inputs:

  • new (0 | 1 | 2) – (0 - default) current window, (1) new window, (2) new tab

  • autoraise (bool) – True (default) to autoraise the page. False to not autoraise

Outputs:

bool – True if the page was opened successfully. Otherwise False.

pwfdf_api.data_spec(*, new=0, autoraise=True)

Opens the PWFDF data spec in a web browser

Open Data Spec
data_spec()

Opens the PWFDF data spec in a web browser. Returns a boolean indicating whether the page was successfully opened.

Browser Options
data_spec(..., *, new)
data_spec(..., *, autoraise=False)

Web browser options. The new input controls how the page is opened. 0 opens in the current window, 1 opens a new window, and 2 opens a new tab. Set autoraise=False to disable raising the opened page when possible.

Note

Many web browsers ignore both these options.

Inputs:

  • new (0 | 1 | 2) – (0 - default) current window, (1) new window, (2) new tab

  • autoraise (bool) – True (default) to autoraise the page. False to not autoraise

Outputs:

bool – True if the page was opened successfully. Otherwise False.

Low-level API

pwfdf_api.sbjson(*, fields=None, 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)

Searches PWFDF and returns a list of sbJSON metadata dicts for the matching assessments. The output list is sorted in alphabetical order by assessment name.

sbJSON
sbjson(...)
sbjson(..., *, fields)

Searches PWFDF and returns sbJSON metadata for matching assessments. Returns a list of sbJSON metadata dicts as output, with one element per matching assessment. The elements are sorted in alphabetical order by assessment name. Use fields to specify the sbJSON fields that should be included in the assessment dicts.

Fire Event
sbjson(..., *, 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
sbjson(..., *, version)
sbjson(..., *, 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
sbjson(..., *, start_date)
sbjson(..., *, assessment_date)
sbjson(..., *, 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
sbjson(..., *, extent)
sbjson(..., *, extent_type)
sbjson(..., *, 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
sbjson(..., *, bbox)
sbjson(..., *, point)
sbjson(..., *, geometry)
sbjson(..., *, 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
sbjson(..., *, geometry_layer)
sbjson(..., *, geometry_driver)
sbjson(..., *, 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
sbjson(..., *, max_fires)
sbjson(..., *, max_assessments)
sbjson(..., *, 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
sbjson(..., *, max_queries)
sbjson(..., *, 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
sbjson(..., *, max_products, truncate=True)
sbjson(..., *, 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
sbjson(..., *, timeout)
sbjson(..., *, 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

  • fields (list[str]) – A list of sbJSON fields that should be included in the output

Outputs:

list[dict] – The sbJSON metadata records for the matching assessments

pwfdf_api.query(*, fields=None, fire=None, version=None, 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=None, offset=None, timeout=15, session=None)

Performs a single low-level query of the PWFDF collection and returns the ScienceBase API response as a dict.

Query API
query(...)
query(..., *, fields)

Performs a single low-level query of the PWFDF collection via the ScienceBase API and returns the response as a dict. In most cases, the output will include a total key, which reports the number of matching product records. The output will also usually include an items key, which is a list of sbJSON dicts for the assessment products included in the response. Use fields to indicate the sbJSON fields that should be included in the items.

Important

The total will exceed the number of elements in items if the total number of search results exceed the max paging parameter. In such cases, multiple queries may be required to load all the search results.

Fire Event
query(..., *, 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
query(..., *, version)

Searches for assessments matching the provided version number.

Caution

The version must be a full 2-part version number. Major version numbers are not supported.

Date Range
query(..., *, start_date)
query(..., *, assessment_date)
query(..., *, 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
query(..., *, extent)
query(..., *, extent_type)
query(..., *, 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
query(..., *, bbox)
query(..., *, point)
query(..., *, geometry)
query(..., *, 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
query(..., *, geometry_layer)
query(..., *, geometry_driver)
query(..., *, 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.

Paging
query(..., *, max)
query(..., *, offset)

Paging options for the ScienceBase API. Use max to set the maximum number of ScienceBase product records that should be retrieved. Defaults to 500 and cannot exceed 1000. Use offset to specify the number of ScienceBase products to skip before retrieving search results.

Web Request
query(..., *, timeout)
query(..., *, 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) – A version number

  • 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 (int) – The maximum number of ScienceBase records to retrieve per API query

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

  • fields (list[str]) – A list of sbJSON fields that should be included in the items response

  • 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

Outputs:

dict – The ScienceBase API response for the query

pwfdf_api.url(*, fire=None, version=None, 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=None, offset=None, decode=False, json=False, fields=None)

Returns the URL used to search PWFDF with given search filters.

Search URL
url(...)
url(..., *, decode=True)

Returns the URL used to search the PWFDF collection with the given search filters. By default, returns a web-encoded URL. Set decode=True to return a decoded URL, which is more human-readable.

sbJSON Url
url(..., *, json=True)
url(..., *, json=True, fields)

By default, returns the URL for the ScienceBase user interface. Set json=True to return the URL for an sbJSON API response instead. Use fields to indicate the sbJSON fields that should be included in the response.

Fire Event
url(..., *, 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
url(..., *, version)

Searches for assessments matching the provided version number.

Caution

The version must be a full 2-part version number. Major version numbers are not supported.

Date Range
url(..., *, start_date)
url(..., *, assessment_date)
url(..., *, 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
url(..., *, extent)
url(..., *, extent_type)
url(..., *, 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
url(..., *, bbox)
url(..., *, point)
url(..., *, geometry)
url(..., *, 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
url(..., *, geometry_layer)
url(..., *, geometry_driver)
url(..., *, 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.

Paging
url(..., *, max)
url(..., *, offset)

Paging options for the ScienceBase API. Use max to set the maximum number of ScienceBase product records that should be retrieved. Defaults to 500 and cannot exceed 1000. Use offset to specify the number of ScienceBase products to skip before retrieving search results.

Inputs:

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

  • version (str) – A version number

  • 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 (int) – The maximum number of ScienceBase records to retrieve per API query

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

  • decode (bool) – True to return a decoded URL. False (default) to return a percent-encoded URL suitable for web requests.

  • json (bool) – True to return a URL for a JSON response. False (default) to return a URL for the ScienceBase user interface

  • fields (list[str]) – A list of sbJSON fields that should be included in the response

Outputs:

str – The URL used to search PWFDF with the given search filters

Auxiliary Modules