ScienceBase Collection¶
Child Items¶
The PWFDF Collection is hosted on the USGS’s ScienceBase data catalog as catalog item 6818f950d4be0208bc3e0165. The collection consists of multiple child items, with one item per version of each hazard assessment. Child items follow the naming scheme <fire> <YYYY-MM-DD> v<X.Y> postfire debris-flow hazard assessment, with the following substitutions:
Substitution |
Description |
|---|---|
|
The name of the fire event. |
|
An ISO 8601 date string indicating the start date of the fire event. |
|
The version number of the assessment. |
Assessment Versions¶
A given fire event may have multiple associated hazard assessments. For example: a fire may have a preliminary assessment to support emergency response crews, an initial year-1 base assessment, and then a year-2 assessment that reassesses hazards following a year of vegetative recovery. To distinguish these different products, each hazard assessment is assigned a two-part version number X.Y, where X and Y are both integers. In general, the highest version number represents the most up-to-date assessment, and this section details the versioning scheme.
Major Version¶
We refer to the X integer as the major version number. This number is used to distinguish between preliminary and annually updated assessments. As follows:
|
Description |
|---|---|
0 |
For preliminary assessments completed before the fire is completely contained. (Often to support emergency response crews). |
1 |
Base assessment for the first year following a fire. |
2 |
Assessment for the second year following a fire, updated to account for 1 year of vegetative recovery. |
N |
Assessment for the Nth year following a fire, updated to account for N-1 years of vegetative recovery. |
Minor Version¶
We refer to the Y integer as the minor version number. This number documents updates or corrections to a major assessment. Common uses of the minor version number are:
Updating an assessment to leverage newly available data,
Modeling additional design-storm scenarios, and
Correcting errors in a previous assessment
The following table provides an example of minor version numbers. Please note that this table is only for illustrative purposes, so real minor version numbers are not required to match the causes described here. For example, 1.1 is not required to be an update for new soil burn severity data.
Version |
Description |
|---|---|
1.0 |
Base assessment for year 1. |
1.1 |
Updated year 1 assessment, leveraging newly available soil burn severity data. |
1.2 |
Corrected year 1 assessment, fixing a problem in 1.1 |
Metadata Queries¶
All PWFDF items conform to the sbJSON item model, which allows users to query and filter various metadata fields via structured ScienceBase URL queries. Here, we describe metadata fields unique to the PWFDF collection that may be of particular interest to the user community. We note that the PWFDF collection also supports all standard queries in the sbJSON model, and users can consult the ScienceBase documentation for more information on querying standard sbJSON metadata.
Tip
The following sections provide example URLs for querying PWFDF assessments on ScienceBase. The queries all request JSON search results, but you can view results in the ScienceBase web viewer instead by removing the format=json parameters from the URLs.
Parent ID¶
The ID of the parent PWFDF collection is 6818f950d4be0208bc3e0165. You can use this ID to search for assessments in the PWFDF collection by including the parentId=6818f950d4be0208bc3e0165 parameter in the search URL. For example:
https://www.sciencebase.gov/catalog/items?format=json&parentId=6818f950d4be0208bc3e0165
Fire Name¶
Each assessment includes a Name tag that records the name of the associated fire event. You can search for assessments whose fire event matches a given name by including a filter=tags={type:Name,name:My Fire Name} parameter in the search URL, replacing My Fire Name with the desired fire event. For example:
https://www.sciencebase.gov/catalog/items?format=json&parentId=6818f950d4be0208bc3e0165&filter=tags={type:Name,name:Eaton}
Start Date¶
Each assessment has an associated FireStart date that records the starting date of the fire event. You can search for assessments whose fire started within a given date range by including a filter=dateRange={dateType:FireStart,start:YYYY-MM-DD,end:YYYY-MM-DD} parameter in the search URL, replacing YYYY-MM-DD with an ISO 8601 date string for the first and final dates in the date range. For example:
https://www.sciencebase.gov/catalog/items?format=json&parentId=6818f950d4be0208bc3e0165&filter=dateRange={dateType:FireStart,start:2025-01-01,end:2025-12-31}
Assessment Version¶
Each assessment includes a Version tag that records the version of the associated hazard assessment. You can search for assessments that match a particular version by including a filter=tags={type:Version,name:X.Y} parameter in the search URL, replacing X.Y with the desired version number. For example:
https://www.sciencebase.gov/catalog/items?format=json&parentId=6818f950d4be0208bc3e0165&filter=tags={type:Version,name:1.0}
Assessment Date¶
Each assessment has an associated Assessment date that records the date the assessment was run. You can search for assessments that were implemented within a given date range by including a filter=dateRange={dateType:Assessment,start:YYYY-MM-DD,end:YYYY-MM-DD} parameter in the search URL, replacing YYYY-MM-DD with an ISO 8601 date string for the first and final dates in the date range. For example:
https://www.sciencebase.gov/catalog/items?format=json&parentId=6818f950d4be0208bc3e0165&filter=dateRange={dateType:Assessment,start:2025-01-01,end:2025-12-31}
Spatial Queries¶
Each assessment has an associated WGS84 bounding box, which allows you to query assessments that fall within a given spatial region. A common search type is to locate assessments that fall within a given bounding box. You can implement this by including a filter=spatialQuery={wkt:"POLYGON((Xmin Ymin, Xmin Ymax, Xmax Ymax, Xmax Ymin, Xmin Ymin))",relation=intersects} parameter in the search URL, replacing Xmin, Xmax, Ymin, and Ymax with the coordinates of the edges of the bounding box (in WGS84). For example:
https://www.sciencebase.gov/catalog/items?format=json&parentId=6818f950d4be0208bc3e0165&filter=spatialQuery={wkt:"POLYGON((-124.023++32.483,+-114.562++32.483,+-114.562++38.618,-124.023++38.618,-124.023++32.483))",relation:intersects}
More complex spatial queries are also possible, including generic polygon searches, and additional spatial relationships. Consult the ScienceBase spatial query documentation for more details on these advanced cases.
Extent Queries¶
Another common search type is querying assessments that fall within a given state. You can implement this by including a filter=extentQuery={extent:ID,relation:intersects} parameter in the search URL, replacing ID with the extent ID of the state. For example, to query assessments in California, which has an extent ID of 8, you could use:
https://www.sciencebase.gov/catalog/items?format=json&parentId=6818f950d4be0208bc3e0165&filter=extentQuery={extent:35,relation:intersects}
You can find a list of state extent IDs using:
https://www.sciencebase.gov/catalog/extents?extentType=U.S. State&max=1000
More complex extent queries are also possible, including searching extents other than U.S. states, and additional spatial relationships. Consult the ScienceBase extent query documentation for more details on these advanced cases.
Publication Date¶
Each assessment has an associated Publication date that records the date the assessment was published to ScienceBase. This is often the same as the assessment date, but may be a later date if processing was delayed. You can search for assessments that were published within a given date range by including a filter=dateRange={dateType:Publication,start:YYYY-MM-DD,end:YYYY-MM-DD} parameter in the search URL, replacing YYYY-MM-DD with an ISO 8601 date string for the first and final dates in the date range. For example:
https://www.sciencebase.gov/catalog/items?format=json&parentId=6818f950d4be0208bc3e0165&filter=dateRange={dateType:Publication,start:2025-01-01,end:2025-12-31}