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