Getting Started¶

PWFDF is hosted on the USGS ScienceBase catalog, where it is organized as a collection of child items. Each child item represents a particular hazard assessment. A given fire event may have multiple hazard assessments, so each assessment includes a version number to distinguish it from related assessments. When using pwfdf-api, most users will use some combination of the following main commands:

Command	Description
assessments	Searches the collection for assessments matching various criteria
download	Downloads matching assessments to the local file system
metadata	Returns `metadata.json` info for matching assessments
browse	Searches the collection and opens search results in a web browser

Command Line

If working from the command line, these actions are sub-commands of the pwfdf command line interface:

pwfdf assessments ...
pwfdf download ...
pwfdf metadata ...
pwfdf browse ...

Python

If working within Python, these commands are imported from the pwfdf_api module:

from pwfdf_api import assessments, download, metadata, browse
assessments(...)
download(...)
metadata(...)
browse(...)

Each of these commands searches the collection and then returns results for assessments that meet various search criteria, such as: fire name, start date, spatial location, and others. These search filters are discussed in detail in the search guide.

Quick help¶

Command Line

The API provides complete documentation for each command, but you can also print a command’s help text in the terminal. To do so, call the command with the standard --help option. For example:

pwfdf download --help

This help text will include a summary of the command, and will also describe every available option.

Python

The API provides complete documentation for each command, but you can also print a command’s help text within a Python session. To do so, call the standard help function on the command:

from pwfdf_api import download
help(download)

This help text will include a summary of the command, and will also describe every available input argument.

Documentation¶

Command Line

The pwfdf-api provides several commands to quickly open documentation resources in a web browser. You can use the docs command to open the package’s documentation:

pwfdf docs

and the data-spec command to open the PWFDF data specification (which documents hazard assessment contents):

pwfdf data-spec

Python

The pwfdf-api provides several commands to quickly open documentation resources in a web browser. You can use the docs command to open the package’s documentation:

from pwfdf_api import docs
docs()

and the data_spec command to open the PWFDF data specification (which documents hazard assessment contents):

from pwfdf_api import data_spec
data_spec()

ScienceBase¶

The pwfdf-api package leverages the ScienceBase API to search the collection, so the package may stop functioning if ScienceBase is down. The pwfdf-api commands will report when this is the case, and you can also check the ScienceBase Catalog Status Page for more details.

The pwfdf-api provides several advantages over the ScienceBase API for searching the PWFDF collection. First, the pwfdf-api provides a more user-friendly search experience, as the ScienceBase API is highly generalized and requires experience crafting REST API urls. Also, the ScienceBase API implements a paging scheme, wherein multiple API queries may be required to fully retrieve search results. By contrast, pwfdf-api automates this paging functionality, so will return results for all matching assessments with a single command call.