Installation¶

Prerequisites¶

Python¶

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.12 --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 setup your credentials for uploading assessments to various web platforms.

Tip

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

Amazon Simple Storage Service (S3)¶

Start by using the authenticate s3 command to setup credentials for uploading to S3 (for the web map). Use:

ocelote authenticate s3

and follow the prompts to set up your credentials. You should contact the HazDev team for help with these credentials. If you plan on running many assessments, then you should request read access to the S3 bucket, as this will allow you to verify when you have uploaded results.

ScienceBase¶

Next, use the authenticate sciencebase command to setup your credentials for uploading to ScienceBase (for long-term archival). Use:

ocelote authenticate sciencebase

and follow the prompts to set up your credentials. Note that 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.

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 very 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.0.0 release to the current directory using:

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

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.