Install

Digger may be installed with pip. Two options are supported: (1) installation from an index url or (2) installation directly from the source code cloned or downloaded from the repository. Users who have pip but not git on their machines will want to use option (1).

Option 1: Pip installation from index url

Warning

This method is not expected to work until the v1.1 release is finalized.

To install directly from code.usgs.gov use the following command. This method does not require the user to have git installed on their computer.

pip install digger --index-url  https://code.usgs.gov/api/v4/projects/10580/packages/pypi/simple

Option 2: Pip installation from source code

Step 1: Get source code

First, get digger source code.

git clone https://code.usgs.gov/ghsc/lhp/digger.git

Step 2 (optional): Create environment

You may want to install digger in an environment, for example, using conda. This step is not required.

conda create -n digger-env -c conda-forge python=3.11
conda activate digger-env

Step 3: Install digger

Navigate to the top level of the digger directory. This should be a directory that contains the file pyproject.toml. Run the following command at the terminal to install digger.

pip install -e .

Developer installation

If you are doing development you will want to clone the repository. Then, rather than installing digger with pip, you will install with poetry. Per your preferences, you can pip install poetry or conda install -c conda-forge poetry inside the environment where you plan to install digger.

Next, in the top level of the digger directory:

poetry install --with dev

If you plan to run the tests, you will need to additionally install D-Claw. This is because some of the functions provided within digger have an optional dependency of the backends provided within the clawpack python libraries. These backends allow xarray to open some of the clawpack-style output files.

The tests do not require that D-Claw be compiled. Rather, cloning the repositories and setting environment variables are the necessary steps to ensure the tests may run.

A variety of developer commands have been built in with poetry and poe:

Usage:
  poe [global options] task [task arguments]

Global options:
  -h, --help            Show this help page and exit
  --version             Print the version and exit
  -v, --verbose         Increase command output (repeatable)
  -q, --quiet           Decrease command output (repeatable)
  -d, --dry-run         Print the task contents but don't actually run it
  -C PATH, --directory PATH
                        Specify where to find the pyproject.toml
  -e EXECUTOR, --executor EXECUTOR
                        Override the default task executor
  --ansi                Force enable ANSI output
  --no-ansi             Force disable ANSI output

Configured tasks:
  test_ci               Runs the tests and requires 80% coverage
  test                  Runs the tests and reports missing coverage
  coverage              Prints the coverage report for the tests
  htmlcov               Builds an HTML coverage report (located at 'htmlcov/index.html')
  format                Applies black and isort to digger and its tests
  lint                  Requires digger and its tests to be properly formatted
  docs                  Runs docs

Note that the tests ensure that the examples run, but the examples do not contribute to the calculation of code coverage. Additionally, the tests ensure that the plotting code runs without error but do not evaluate it for correct behavior or use it in calculating coverage.