Welcome to echoshader

Open Source Python package for building ocean sonar data visualizations based on the HoloViz suite of Python tools.

What are ocean sonar systems?

Ocean sonar systems, such as echosounders, are the workhorse to study life in the ocean. They provide continuous observations of fish and zooplankton by transmitting sounds and analyzing the echoes bounced off these animals, just like how medical ultrasound images the interior of the human body. In recent years these systems have been widely deployed on ships, autonomous vehicles, and moorings, bringing in large volumes of data that allow scientists to study changes in marine ecosystems.

What is echoshader?

Echoshader aims to enhance the capability to interactively visualize large volumes of ocean sonar data to accelerate data exploration and discovery. The project goes hand-in-hand with the ongoing development of echopype, which handles the standardization, pre-processing, and organization of these data.

By providing an accessible and customizable platform for echo data visualization, the project can accelerate advancements in oceanographic research for the benefit of conservation and sustainable resource management.

Installation

Echoshader supports Python 3.13 and 3.14. We recommend creating a new environment before installing echoshader:

mamba create -c conda-forge -n echoshader --yes python=3.13
mamba activate echoshader

To install the latest release from PyPI:

python -m pip install echoshader

To install the latest development version from GitHub:

python -m pip install git+https://github.com/echostack-org/echoshader.git

We recommend using mamba to manage conda environments.

Quick start

Echoshader provides reusable visualization elements for standardized ocean sonar data stored as xarray datasets.

import echoshader
import xarray as xr

ds = xr.open_zarr("examples/notebooks/MVBS.zarr")

ds.eshader.echogram(
    channel="WBT 400143-15 ES38B_ES",
    vert_dim="depth",
)

Available visualization elements include echograms, tricolor echograms, vessel tracks, 3-D curtain plots, histograms, summary tables, curves, and NASC plots. Start with examples/notebooks/element_examples.ipynb. The first part processes one RAW file and demonstrates acoustic geometries; the second downloads and extracts the small example dataset as MVBS.zarr. Run the notebook from examples/notebooks/ so the dataset is saved there.

The dataset is also available directly as MVBS.zip. Extract it into examples/notebooks/ to obtain examples/notebooks/MVBS.zarr.

Once the dataset is available, launch the example application from the repository root:

python -m echoshader.app.launcher examples/app/app_config.yaml --port 1805

Open http://localhost:1805/basic. The example YAML resolves its dataset path relative to its own location. See the application guide for configuration and interaction details.

Development setup

This section is intended for those who are actively developing echoshader.

First, fork and clone the echoshader repository, then create and activate a development environment:

mamba create -c conda-forge -n echoshader-dev --yes python=3.13
mamba activate echoshader-dev

From the repository directory, install echoshader in editable mode together with the development and testing dependencies defined in pyproject.toml:

python -m pip install -e ".[dev,test]"

To link the environment with a Jupyter kernel:

python -m ipykernel install --user \
    --name echoshader-dev \
    --display-name "echoshader-dev"

To run the test suite:

pytest