(install-digger)=
# Install

Digger may be installed with [pip](https://pypi.org/project/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.

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

## Option 2: Pip installation from source code

(clone)=
### Step 1: Get source code

First, get `digger` source code.

```bash
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.

```bash
conda create -n digger-env -c conda-forge python=3.13
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.

```bash
pip install -e .
```

### Optional dependencies

Some digger tools use [ObsPy](https://docs.obspy.org/) and [PyWavelets](https://pywavelets.readthedocs.io/en/latest/). On some computers it is difficult to install these dependencies. Because not all users will use the tools that require these dependencies, they are optional. If you need to use them and you install with pip, you can execute the following to get all optional dependencies. The below developer installation instructions will install the optional dependencies as well.

```bash
pip install -e .[all]
```


Digger has some dependencies that are only distributed through conda. For full functionality, also execute the following from within the environment in which you plan to run digger.

```bash
conda install conda-forge::ffmpeg
```

(dev-guide)=
## Developer installation

If you are doing development you will want to [clone](clone) the repository. Then, rather than installing `digger` with pip, you will  install with [`poetry`](https://python-poetry.org/docs/#installation). 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:

```bash
poetry install --all-groups --all-extras
```

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](https://github.com/clawpack/geoclaw/blob/master/src/python/geoclaw/xarray_backends.py) provided within the clawpack python libraries. These backends allow [xarray](https://docs.xarray.dev/en/stable/) to open some of the clawpack-style output files.

The tests do not require that D-Claw be compiled. Rather, [cloning the repositories](https://claw.code-pages.usgs.gov/dclaw/src/installation.html#clone-repositories) and [setting environment variables](https://claw.code-pages.usgs.gov/dclaw/src/installation.html#set-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](https://poethepoet.natn.io/index.html):

```
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:
  audit                 Checks package dependencies for security issues
  update                Deletes poetry.lock and reinstalls the project
  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
  checkpretty           Runs 'poe format' and 'poe lint' in sequence
  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.

:::{note}
The test `test_make_scoops_known_outcome` in `tests/make/test_scoops_analytical.py` sometimes fails locally but passes on Gitlab CI. This is an known issue.
:::