Command Line API¶

Standard Options¶

All ocelote commands support the following options:

-h, --help¶: Prints help text for the command to the console.

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

-q, --quiet¶: Do not log progress messages to the console.

-v, --verbose¶: Logs more detailed progress messages to the console.

--log PATH¶: Logs detailed progress to the indicated file.

authenticate s3¶

Acquires, tests, and stores S3 credentials. By default, prompts the user for:

Region Name,
Bucket Name,
AWS Access Key ID, and
AWS Secret Access Key

for uploading assessments to S3. Please contact the HazDev team for help with these credentials. After credentials are provided, tests the credentials can be used to log in to S3. If successful, saves the credentials to ~/.ocelote/credentials.json. Users can disable the test using the --no-check option. In this case, credentials are saved without testing their ability to login.

If updating credentials, you can leave a credential unchanged by pressing <enter> at its prompt without typing anything. Alternatively, use the --reset option to delete all stored S3 credentials from ~/.ocelote/credentials.json.

--no-check¶: Saves input credentials as-is, without testing the credentials can be used to log in to S3.

--reset¶: Deletes all stored S3 credentials from ~/.ocelote/credentials.json.

authenticate sciencebase¶

Acquires, tests, and stores ScienceBase credentials. By default, prompts the user for:

AD Email, and
AD password

for uploading assessments to ScienceBase. Note that the AD email should include the @usgs.gov or other suffix. After credentials are provided, tests the credentials can be used to log in to ScienceBase. If successful, saves the credentials to ~/.ocelote/credentials.json. Users can disable the test using the --no-check option. In this case, credentials are saved without testing their ability to login.

Important

Your AD password is NEVER saved to file. It is only used to test that the AD email can be used to log in to ScienceBase.

--no-check¶: Saves input credentials as-is, without testing the credentials can be used to log in to ScienceBase.

--reset¶: Deletes all stored ScienceBase credentials from ~/.ocelote/credentials.json.

initialize fire¶

Initializes a fire folder. Requires a fire name or path as input. The initialized folder will include a fire.py metadata file, and the fire name metadata will be auto-populated to match the name of the new folder.

When the fire input is a name or relative path (as is usually the case), then the new fire will be initialized in the current folder. Use the --parent option to specify a different parent folder instead.

FIRE¶: The name or path of the new fire folder.

-p PATH, --parent PATH¶: Specifies the parent folder in which to initialize the fire folder. Ignored if the FIRE input is an absolute path. The parent option is typically an absolute path. If a relative path, then the parent is parsed relative to the current folder.

initialize version¶

Initializes a folder for a new assessment version. Requires a version string as input. The name of the initialized folder will match the version string, and the folder will contain:

an empty inputs subfolder,
version.py,
datasets.py, and
configuration.py

The version string will be auto-populated in version.py. If the new version is 1.0, then the version note will also auto-populate.

If the BARC package is from BAER, EROS, or GTAC, then you can use the --from baer, --from eros, or --from gtac option to auto-populate provenance metadata for the fire perimeter, dNBR, and burn severity datasets.

By default, initializes the new version in the current folder. Alternatively, use the --fire to indicate the fire folder in which to initialize the new version. If FIRE is a relative path, then it is parsed relative to the current folder.

By default, if the command detects previous assessment versions, then the new version will inherit the datasets.py and configuration.py metadata files from the most highest version that is still lower than the new version. Use the --no-inherit option to disable metadata inheritance. Alternatively, use the --inherit to specify an explicit version from which to inherit metadata.

VERSION¶: The version string of the new assessment

--from SOURCE¶: Auto-populates provenance metadata for the fire perimeter, dNBR, and burn severity datasets to match the indicated source. Supported sources include: baer, eros, and gtac.

-f PATH, --fire PATH¶: Specifies the name or path of the fire folder in which to initialize the new version. If a name or relative path, then the fire folder is parsed relative to the current folder.

--no-inherit¶: Disables metadata inheritance. The new version will use the default datasets.py and configuration.py files.

--inherit VERSION¶: Specifies an explicit version from which to inherit metadata. If VERSION is a name or a relative path, then it is parsed relative to the fire folder.

download¶

Scans datasets.py and downloads the indicated datasets. Also downloads NOAA Atlas 14 data, which can be used to select I15_mm_hr values in configuration.py. The NOAA Atlas 14 data is downloaded for the coordinate at the center of the analysis domain. Saves the downloaded datasets in the inputs subfolder.

Currently supports the following downloads:

Dataset	Source
DEM	USGS National Map, 1/3 arc-second DEM
EVT	LANDFIRE LFPS
KF-factors	STATSGO archive
Debris retainments	Los Angeles County archives
Rainfall PFEs	NOAA Atlas 14

After downloading, updates the provenance metadata for any downloaded datasets in datasets.py.

By default, interprets the current folder as the assessment version for which to download data. Use the VERSION parameter to specify the name or path of a specific version instead. If VERSION is a name or relative path (as is usually the case), then it is parsed relative to the current folder. Alternatively, use the --fire option to specify the path to the desired fire folder.

VERSION¶: The name or path of the assessment version for which to download data.

-f PATH, --fire PATH¶: The path to the fire folder holding the assessment version.

--no-atlas14¶: Does not download NOAA Atlas 14 data.

preprocess¶

Preprocesses datasets prior to an assessment. Rasterizes datasets, reprojects to match the spatial projection of the DEM, and clips to the bounds of the buffered fire perimeter. Saves preprocessed rasters to the preprocessed folder.

Preprocessing is implemented via the wildcat package, so you can modify the preprocessing configuration using configuration.py. Please consult the wildcat docs for details on available settings.

By default, interprets the current folder as the assessment version to preprocess. Use the VERSION parameter to specify the name or path of a specific version instead. If VERSION is a name or relative path (as is usually the case), then it is parsed relative to the current folder. Alternatively, use the --fire option to specify the path to the desired fire folder.

VERSION¶: The name or path of the assessment version to preprocess.

-f PATH, --fire PATH¶: The path to the fire folder holding the assessment version.

run¶

Runs an assessment, and exports the results in a format conforming to the PWFDF data specification. Before starting the assessment, the command heavily validates all four configuration files, ensuring all necessary metadata fields are provided. The validation also checks that metadata values match expected values and formats, as appropriate. Advanced users can use the --ignore-name, --ignore-tiles, and --ignore-excluded to skip certain optional consistency checks (more details below).

After validating metadata, the command proceeds to run an assessment. The assessment consists of the following steps:

Characterize watershed,
Delineate stream segment network,
Filter network to model-worthy segments,
Run likelihood, volume, combined hazard, and rainfall threshold models

and is implemented by the wildcat package. As such, you can modify the assessment configuration using configuration.py. Please consult the wildcat docs for details on available settings.

The assessment results are exported to a results subfolder, and also a results.zip zip archive. The results folder is intended for personnel performing quality control. The contents of this folder are never used for uploads, so you can open and inspect these files as you like. By contrast, results.zip is used to upload results, so should never be altered.

Note

The results.zip file contains an embedded checksum that is used to check if the archive has been altered. If you do alter results.zip, then ocelote will refuse to upload the results, and you will need to re-run the assessment.

The assessment also produces a slim <fire id>.zip archive, which contains a subset of the assessment results. This archive provides a backup contingency in case we are unable to distribute results via ScienceBase. In this case, you can email the slim archive to stakeholders until a full ScienceBase release becomes available.

VERSION¶: The name or path of the assessment version to run.

-f PATH, --fire PATH¶: The path to the fire folder holding the assessment version.

--ignore-name¶: Does not perform consistency checks on the fire name. Using this option (1) allows a fire name to end in the word “Fire”, and (2) allows a fire with subfire metadata to not end in “Complex”.

--ignore-tiles¶: Does not require DEM tile metadata in datasets.py. This option is ignored if the DEM was downloaded from the USGS National Map.

--ignore-excluded¶: Does not require exclusion mask source metadata to be the text “Created by USGS personnel”. Use this option if another party provided the exclusion mask.

upload s3¶

Uploads assessment results to S3 for the web map. By default, uses credentials saved by the authenticate s3 command to upload the assessment. However, advanced users can use the --region, --bucket, --access-key-id, and --secret-access-key options to override the saved values.

By default, interprets the current folder as the assessment version to upload. Use the VERSION parameter to specify the name or path of a specific version instead. If VERSION is a name or relative path (as is usually the case), then it is parsed relative to the current folder. Alternatively, use the --fire option to specify the path to the desired fire folder.

VERSION¶: The name or path of the assessment version to upload.

-f PATH, --fire PATH¶: The path to the fire folder holding the assessment version.

--region REGION¶: Overrides any saved AWS region name.

--bucket BUCKET¶: Overrides any saved AWS bucket name.

--access-key-id ID¶: Overrides any saved AWS access key ID.

--secret-access-key KEY¶: Overrides any saved AWS secret access key.

upload sciencebase¶

Uploads assessment results to ScienceBase for permanent archival. Before uploading files, checks (1) the assessment version is not already on ScienceBase, and (2) that version numbers proceed sequentially.

By default, uses credentials saved by the authenticate sciencebase command to upload the assessment. However, advanced users can use the --user-email, and --password options to override the saved values.

By default, uploads assessments to the live PWFDF collection (ScienceBase catalog item 6818f950d4be0208bc3e0165). Use the --parent option to upload results to a different parent item instead. This can be useful for uploading results to a mock collection for testing purposes.

VERSION¶: The name or path of the assessment version to upload.

-f PATH, --fire PATH¶: The path to the fire folder holding the assessment version.

--user-email EMAIL¶: Overrides any saved AD user email.

--password PASSWORD¶: Overrides any saved AD password.

--parent ID¶: Uploads assessment results to the indicated parent collection.