Installation

Prerequisites

Python

Ocelote requires Python 3.11 - 3.13 and AWS CLI v2.0+.

Virtual Environment

You should install ocelote in a clean virtual environment. This is to prevent other geospatial software from interfering with ocelote’s backend. There are many tools for managing virtual environments including miniforge, conda, venv, and virtualenv. If you are not familiar with virtual environments, then miniforge may be a good starting point.

For example, after installing miniforge, you can create a new python environment using:

conda create -n ocelote python=3.13 awscli=2 --yes

and then activate the environment with:

conda activate ocelote

Pip Install

After activating your virtual environment, you can install the latest release using:

pip install ocelote -i https://code.usgs.gov/api/v4/groups/859/-/packages/pypi/simple

The URL in this command instructs pip (Python’s package installer) to install ocelote from the official USGS package registry for the Landslide Hazards Program.

Authenticate

After installing ocelote, you should use the various authenticate commands to set up your credentials for interacting with various web platforms.

Tip

Most users will only need to run the authentication commands once, as ocelote will store the credentials for later use.

Email

Start by using the authenticate email command to save your email address. The email address is required to download EVT data from LANDFIRE. Use:

ocelote authenticate email

and follow the prompts to save your email address.

Amazon Simple Storage Service (S3)

You’ll next set up credentials for uploading assessments to S3 (for the web map). Start by contacting the HazDev to set up single sign-on (SSO) access to S3. We recommend naming your SSO profile “ocelote”, although this is not strictly required. Next, use the authenticate s3 command:

ocelote authenticate s3

and follow the prompts to finalize your credentials. You should contact the HazDev team for help with these credentials.

National Weather Service (NWS)

Finally, use the authenticate nws command to set up credentials for uploading lookup tables to the National Weather Service’s FTP endpoint. Use:

ocelote authenticate nws

and follow the prompts to set up your credentials. You should contact collaborators in the NWS to obtain these credentials.

ScienceBase

You will need to be given write access to the PWFDF collection to upload assessments to ScienceBase. Contact the PWFDF data steward if you do not already have this access.

Changed in version 1.1.3

Ocelote no longer uses an authenticate command to provide ScienceBase credentials. Instead, uploading to ScienceBase now uses token-based authentication. This is discussed in detail in the quickstart guide for uploading to ScienceBase.

Updating ocelote

You can update your ocelote installation to the latest release using:

pip install ocelote --upgrade -i https://code.usgs.gov/api/v4/groups/859/-/packages/pypi/simple

Installing from Lock

Tip

Most users will not need this section.

In rare cases, ocelote may break due to changes in a dependency library. If this occurs, you can use poetry to install ocelote from known working dependencies. This method requires you install poetry in addition to the usual prerequisites.

To use this method, you should first clone the ocelote repository at the desired release. For example, if you have git installed, then you can clone the 1.1.4 release to the current directory using:

git clone https://code.usgs.gov/ghsc/lhp/ocelote.git --branch 1.1.4

Next, use poetry to install ocelote from the poetry.lock file:

poetry install

The poetry.lock file records the dependencies used to test ocelote, so represents a collection of known-working dependencies.