README.md

echopype-examples

This repository hosts demonstration examples for Echopype, an open-source Python library that enables scalable and interoperabe water column sonar data processing.

The examples are written as exectuable Jupyter Notebooks that you can easily run and modify on locally on your own machine or a cloud virtual machine.

See all examples via JupyterBook

All notebooks are rendered at: https://echopype-examples.readthedocs.io/

Run the notebooks locally on your computer

If you want to run these notebooks on your local computer, follow the steps below:

• Clone and go into the repo

  # clone the repo
  git clone https://github.com/OSOceanAcoustics/echopype-examples.git
  
  # go into the repo folder
  cd echopype-examples

• Create a conda environment using the environment.yml file in the conda folder. We recommend using Mamba (see steps here to install).

  # create an environment
  mamba env create -n echopype-examples -f conda/environment.yml
  
  # activate the environment
  conda activate echopype-examples

• Try out the notebooks in the notebooks folder!

Run the notebooks on the cloud via Binder

You can run the notebooks directly on the cloud using Mybinder.org, by clicking the "launch binder" badge at the top of this page.

This will create a pre-configured JupyterLab with all the example notebooks under the notebooks folder. However, note that:

• It usually takes a few minutes to spin up Binder
• The computational resources are very minimal on Binder, so some example notebooks that handle many files may take a very long time or fail
• Any changes you make to the notebooks won't be saved permanently because Binder provides a temporary workspace

Contribute to the example notebooks

Contributions are welcome and greatly appreciated!

The steps to set up a development environment is the same as the above. But:

• If you want to use the latest changes in the Echopype main branch, use conda/environment-ep-main.yml when creating the conda environment
• If you already have a functional Echopype development environment (see here) and want to use that, you can install additional packages needed for this repo by:

  conda install -c conda-forge geopandas cartopy datashader holoviews hvplot

  Note that it is often cleaner and easier to just create a new environment.

To build the JupyterBook locally:

# install jupyter book
conda install -c conda-forge jupyter-book

# go into the repo folder
cd echopype-examples

# build the jupyter book
jupyter-book build notebooks