pwfdf download¶

Synopsis¶

pwfdf download [options]

Description¶

Searches the PWFDF collection and downloads matching assessments to the local file system. By default, downloads assessments into the current folder. Use the --parent option to download assessments into a different folder. Within the parent folder, assessments are downloaded as sub-folders whose names match the fire ID. These names may contain spaces, apostrophes, and multiple periods. Use the --normalize option to replace these characters with underscores and hyphens.

By default, downloads all files in each matching hazard assessments. Use the --files or --exclude-files option to only download a subset of assessment files instead. Supported file selectors 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.

Note

You are not required to use the file extension when selecting files. For example, both metadata.json and metadata are valid selectors.

By default, throws an error if the command would download more than 2 GB of data. Use the --max-gb option to change this limit. Note that the command extracts downloaded zip folders by default, so the final file size may exceed this limit. Use the --no-extract option to prevent the extraction of downloaded zip archives.

In some cases, you may want to examine what the command would download, before actually downloading anything. Use the --dry-run option to run the command without downloading any files. The logs will indicate (1) the assessments that would have been downloaded, (2) the expected size of the download, and (3) the folders in which the assessments would be downloaded.

Example:

pwfdf download

Options¶

-h, --help¶: Displays the command’s help text and exits.

-t, --show-traceback¶: Shows the full traceback when an error occurs.

Folder Paths¶

Options that manage the paths of folders in which assessments are downloaded.

--parent PATH¶

The path to the parent folder into which assessment sub-folders should be downloaded.

Example:

pwfdf download --parent /path/to/my/folder

--normalize¶

Normalizes assessment sub-folder names to remove spaces, punctuation, and periods not included in the file extension.

Example:

pwfdf download --normalize

--strict¶

Raises an error if the parent folder exists and is not empty.

Example:

pwfdf download --string

--duplicates ACTION¶

Specifies what should happen when an assessment sub-folder 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

Example:

pwfdf download --duplicates replace

Downloaded Files¶

Options controlling how and which files are downloaded.

--files FILE...¶

Specifies which files should be downloaded from matching assessments. Cannot be used if the --exclude-files option is used.

Example:

pwfdf download --files Shapefile metadata median-thresholds
pwfdf download --files Shapefile.zip metadata.json median-thresholds.csv

--exclude-files FILE...¶

Indicates the files that should not be downloaded from matching assessments. All other files are downloaded. Cannot be used if the --files option is used.

Example:

pwfdf download --exclude-files GeoJSON configuration fgdc-metadata
pwfdf download --exclude-files GeoJSON.zip configuration.txt fgdc-metadata.xml

--no-extract¶

Prevents the extraction of downloaded zip archives. Using this option will ensure that the final size of the download does not exceed --max-gb.

Example:

pwfdf download --no-extract

--max-gb¶

Specifies a maximum allowed size of downloaded files in gigabytes. (Default is 2 GB). Raises an error if downloading the files would require more memory than this limit.

Warning

This option limits the total data transferred over an internet connection. The final size on the local filesystem may be larger than --max-gb if the download contains zip archives and the zip archives are distracted. Use the --no-extract option to prevent the extraction of zip archives.

Example:

pwfdf download --max-gb 3

Misc Download¶

Miscellaneous options for downloading assessments.

--failures ACTION¶

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

Example:

pwfdf download --failures ignore

--dry-run¶

Runs the command without downloading any files. Use this option to determine what a download would do, without downloading data or altering the local filesystem. The logs will indicate (1) the assessments that would have been downloaded, and (2) the expected size of the download.

Example:

pwfdf download --dry-run

Tags¶

--fire NAME¶

The name of a fire to search. Note that the fire name is the portion of the assessment ID before the start date. A fire name must exactly match the provided text to match an assessment. Place the fire name in quotes if the name contains whitespace or punctuation.

Examples:

pwfdf download --fire Eaton
pwfdf download --fire "South Rim"

--version VERSION | MAJOR¶

A version number or major version number to search.

Examples:

# All version 1 assessments
pwfdf download --version 1

# Only version 1.1
pwfdf download --version 1.1

--latest¶

Only return the latest assessment version of matching fires.

Examples:

pwfdf download --latest
pwfdf download --version 1 --latest

Date Ranges¶

--start-date DATE | DATE RANGE¶

A date or date range in when the fire started.

Examples:

pwfdf download --start-date 2025
pwfdf download --start-date 2025-06
pwfdf download --start-date 2025-06-11
pwfdf download --start-date 2025 2027
pwfdf download --start-date 2025-06-15 2025-08-10

--assessment-date DATE | DATE RANGE¶

A date or date range in which the assessment was conducted.

Examples:

pwfdf download --assessment-date 2025
pwfdf download --assessment-date 2025-06
pwfdf download --assessment-date 2025-06-11
pwfdf download --assessment-date 2025 2027
pwfdf download --assessment-date 2025-06-15 2025-08-10

--publication-date DATE | DATE RANGE¶

A date or date range in which the assessment was published to ScienceBase.

Examples:

pwfdf download --publication-date 2025
pwfdf download --publication-date 2025-06
pwfdf download --publication-date 2025-06-11
pwfdf download --publication-date 2025 2027
pwfdf download --publication-date 2025-06-15 2025-08-10

Extent¶

Options for searching well-known spatial regions whose coordinates are already known by ScienceBase.

--extent NAME¶

The name of an extent (such as a state or country) to search. Place the name in quotes if it contains spaces or punctuation. Cannot be used if the --extent-id option is used.

Examples:

# Named extents
pwfdf download --extent California
pwfdf download --extent "Los Angeles, CA"
pwfdf download --extent "Grand Canyon National Park"

# Hydrologic unit codes
pwfdf download --extent 05

--extent-id ID¶

The ID of an extent to search. Cannot be used if the --extent option is used.

Example:

# Searches California
pwfdf download --extent-id 35

# Searches the 05 HUC-2 watershed
pwfdf download --extent-id 2000387

--extent-type TYPE¶

The type of extent to search. This option is usually not necessary, but can guard against searching a wrong extent with a similar name.

Tip

Use the pwfdf extents types command to obtain a list of supported types.

Example:

pwfdf download --extent "Los Angeles, CA" --extent-type "U.S. County"

--extent-relation RELATION¶

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`	Matches assessments that are fully contained within the extent.
`disjoint`	Matches assessments that do not intersect the extent at any point.

Example:

pwfdf download --extent California --extent-relation within

Geometry¶

Custom geospatial searches in which you provide the coordinates of the region to search.

--bbox PATH | "XMIN, YMIN, XMAX, YMAX"¶

A bounding box to search. Usually the path to a supported GIS file, such as a Shapefile or GeoJSON. May also be a comma-delimited, WGS-84 "XMIN, YMIN, XMAX, YMAX" coordinate sequence. If a GIS file, then the bounding box is calculated from the contained geometries.

Examples:

pwfdf download --bbox path/to/my/file.shp
pwfdf download --bbox "-121, 32, -119, 34"

--point PATH | "LON, LAT"¶

A geospatial point to search. Either a comma-delimited "LON, LAT" sequence, or the path to a supported GIS file, such as a Shapefile or GeoJSON. If a GIS file, then the point is calculated as the center of the bounding box for the contained geometries.

Examples:

pwfdf download --point path/to/my/file.shp
pwfdf download --point "-121, 32"

--geometry PATH | GEOJSON¶

A spatial geometry to search. Usually the path to a file in a supported GIS file, such as a Shapefile or GeoJSON. May also be a valid WGS-84 GeoJSON geometry string, but this syntax is generally not recommended, as it is difficult to use in practice.

In practice, only relatively coarse geometries are supported, as the geometry cannot cause the underlying query URL to exceed 2000 characters. As a rule of thumb, geometries with fewer than 100 coordinate points are expected to usually work.

Examples:

pwfdf download --geometry path/to/my/file.shp
pwfdf download --geometry "{\"type\":\"Point\",\"coordinates\":[-121, 32]}"

--geometry-relation RELATION¶

The spatial relationship between a geospatial search and the search results. Options are:

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

Example:

pwfdf download --bbox my-file.shp --geometry-relation intersects
pwfdf download --point my-file.shp --geometry-relation within
pwfdf download --geometry my-file.shp --geometry-relation disjoint

Geometry File IO¶

Options for reading geometries from supported vector feature file formats.

--geometry-layer NAME¶

The name of a data layer in the GIS file from which to extract the geometry. Cannot be used when the --geometry-index option is used.

Example:

pwfdf download --geometry my-file.geojson --geometry-layer "My Data Layer"

--geometry-index INDEX¶

The index of a data layer in the GIS file from which to extract the geometry. Cannot be used when the --geometry-layer option is used.

Example:

pwfdf download --geometry my-file.geojson --geometry-index 2

--geometry-driver DRIVER¶

Specifies the file format driver to use to open the geometry file. Note that the format driver is usually auto-detected from the file extension. Use this option if the geometry file uses a non-standard file extension. Refer to the first column of the geometry file formats table for a list of supported driver names.

Example:

pwfdf download --geometry my-file.unusual --geometry-driver Shapefile

--geometry-encoding ENCODING¶

Specifies the file encoding to use to read the geometry file. Note that the encoding is auto-detected for most formats.

Example:

pwfdf download --geometry my-file.shp --geometry-encoding Windows-1252

API Queries¶

Options for controlling low-level interactions with the ScienceBase API.

--max-per-query N¶

Specifies the maximum number of product records that the ScienceBase API should return per query. Note that the command may perform multiple API queries if the total number of matching assessments exceeds this number. Defaults to 500 and cannot exceed 1000.

Example:

pwfdf download --max-per-query 1000

--max-queries N¶

Specifies a maximum allowed number of ScienceBase API queries. Raises an error if this number is exceeded.

Example:

pwfdf download --max-queries 5

--timeout SECONDS¶

Specifies the maximum allowed amount of time to connect with the ScienceBase server. Raises an error if the command cannot connect in this time frame. Defaults to 15 seconds.

Example:

pwfdf download --timeout 60

Product Limits¶

--max-fires N¶

Specifies a maximum allowed number of fires in the search results. Raises an error if this number is exceeded.

Example:

pwfdf download --fire Eaton --max-fires 1

--max-assessments N¶

Specifies a maximum allowed number of assessments in the search results. Raises an error if this number is exceeded.

Example:

pwfdf download --fire Eaton --max-assessments 1

--max-products N¶

Specifies a maximum number of allowed product records in the ScienceBase API response. Raises an error if this number is exceeded, or skips the remaining records if the --truncate option is also provided.

Caution

Most users should not use this option. Instead, use --max-queries to limit API queries, or use --max-fires and/or --max-assessments to limit the size of the search results.

Example:

pwfdf download --max-products 1000

Paging¶

Low-level options for implementing custom ScienceBase paging schemes.

--offset N¶

The number of ScienceBase products to skip before retrieving search results.

Example:

pwfdf download --offset 50

--truncate¶

Truncates results after --max-products products, skipping all remaining products.

Example:

pwfdf download --max-products 50 --truncate

Logging¶

-q, --quiet¶

Do not log progress messages to the console.

Example:

pwfdf download -q

-v, --verbose¶

Prints more detailed progress messages to the console. (Useful for debugging).

Example:

pwfdf download -v

--log PATH¶

Logs detailed progress to the indicated file

Example:

pwfdf download --log my-file.log