docs: Re-organize README and docs pages (#197)

* substitute EchoPro with echopop in docs

* update README, fix accidental typo in input_files

* update index.md, add constributors

* simplify and add installation guide

README.md

@@ -1,97 +1,49 @@
-# Echopro
+# Echopop
 
-Echopop combines acoustic data analysis results with biological information from trawls (such as length, age, etc.) to produce estimates of biomass, biomass density, abundance, and other characteristics for Pacific hake. It is based on the Matlab EchoPro software originally developed for the [Joint U.S.-Canada Integrated Ecosystem and Pacific Hake Acoustic Trawl Survey](https://www.fisheries.noaa.gov/west-coast/science-data/joint-us-canada-integrated-ecosystem-and-pacific-hake-acoustic-trawl-survey) by the [Fisheries Engineering and Acoustic Technologies Team](https://www.fisheries.noaa.gov/west-coast/sustainable-fisheries/fisheries-engineering-and-acoustic-technologies-team) at the NOAA Northwest Fisheries Science Center.
+Echopop combines acoustic data collected by echosounders with biological "ground truth" information from trawls to produce biological estimates, such as biomass  and abundance. 
 
-Go to https://uw-echospace.github.io/EchoPro/ to view Jupyter notebooks that demonstrate EchoPro functionality and typical workflows.
+Current the processing is configured to work with Acoustic-Trawl survey data for Pacific hake, but we will soon add components to include Pacific krill into the package. The majority of the computational implementation is applicable for other fish and zooplankton species, and we plan to expand the package for general support in the near future.
 
-## Installation
 
-Echopop is not yet available for installation as a package on [PyPI](https://pypi.org/) or [conda-forge](https://conda-forge.org/). Until then, it must be installed either as a **"user"** from the GitHub repository or from the code (mainly for continued development purposes, as a **"developer"**) after "cloning" the GitHub repository using `git`. See the instructions below. Either way, we'll use [conda](https://docs.conda.io) to install EchoPro dependencies from conda packages on `conda-forge`. Installation of these dependencies has been tested extensively with `conda`. 
+## Documentation
 
-There are different ways of installing `conda`, but we recommend the use of [Miniconda with the conda libmamba solver](https://echospace-group-docs.readthedocs.io/en/latest/compute-conda-jupyter.html). `conda` can be used without administrative privileges.
+Learn more about Echopop in the documentation at https://echopop.readthedocs.io.
 
-### Installation as a user
 
-This simpler installation method is recommended if you don't intend to work on developing the EchoPro code base itself.
+## Acknowledgement
 
-1. Download the `condaenvironment.yaml` file. In https://github.com/uw-echospace/EchoPro/blob/master/condaenvironment.yaml, click on "Raw" (on the right) then save the file.
-2. At the terminal (shell), change directory to where you've placed the `condaenvironment.yaml` file.
-3. Install EchoPro dependencies, creating a new conda environment called "echopro": 
-    ```bash
-    conda env create -f condaenvironment.yaml
-    ```
-4. Activate this new conda environment: 
-    ```bash
-    conda activate echopro
-    ```
-5. Install EchoPro from the GitHub repository:
-    - To install the latest release using a [Python wheel](https://realpython.com/python-wheels/) file:
-        ```bash
-        pip install https://uw-echospace.github.io/EchoPro/EchoPro-latest-py3-none-any.whl
-        ```
-    - To install the latest development version:
-        ```bash
-        pip install git+https://github.com/uw-echospace/EchoPro.git
-        ```
+We thank Dezhang Chu (@DezhangChu) of the NOAA Northwest Fisheries Science Center
+for providing the Matlab EchoPro program he developed
+that many elements of Echopop is based on,
+as well as his detailed consultation for implementations specific to Pacific hake.
 
-In order to run EchoPro you will also need to **download the EchoPro configuration files** (see below). To run the example Jupyter notebooks for the sample 2019 inputs, you will also need to download the notebooks and the input data files.
+We also thank Rebecca Thomas (@rebeccathomas-NOAA),
+Beth Phillips (@ElizabethMPhillips),
+Alicia Billings (@aliciabillings-noaa),
+and Julia Clemons (@JuliaClemons-NOAA)
+of the Fisheries Engineering and Acoustics Team (FEAT)
+of the NOAA Northwest Fisheries Science Center for continuing discussions
+that make Echopop better.
 
-### Installation as a developer
+We also thank funding from NOAA Fisheries to support this work.
 
-Follow these steps if you intend to make code contributions to EchoPro:
+<div>
+  <a>
+    <img src="docs/images/noaa_fisheries_logo.png" alt="NOAA_fisheries_logo" width="200">
+  </a>
+</div>
 
-1. Clone the repository (alternatively, fork the repository first, then clone your fork):
-    ```bash
-    git clone https://github.com/uw-echospace/EchoPro.git
-    ```
-2. `cd` to the new `EchoPro` directory:
-    ```bash
-    cd EchoPro
-    ```
-3. Install the dependencies, including dependencies used for development, and create a new conda environment called "echopro": 
-    ```bash
-    conda create -c conda-forge -n echopro python=3.9 --file requirements.txt --file requirements-dev.txt
-    ```
-4. Activate the environment: 
-    ```bash
-    conda activate echopro
-    ```
-5. Install EchoPro in development mode:
-    ```bash
-    pip install -e .
-    ```
 
-The EchoPro configuration files and example Jupyter notebooks are available in the files you have cloned, but you will need to **download the 2019 sample input data files** (see below).
+## Contributors
 
-## Download 2019 sample input files
+Echopop development is currently co-led by Wu-Jung Lee (@leewujung) and Brandyn Lucca (@brandynluca). Brandon Reyes (@b-reyes) and Emilio Mayorga (@emiliom) contributed significantly to a previous version of Echopop.
 
-Download the folder [Matlab_UWfiles/2019_consolidated_files](https://drive.google.com/drive/folders/13o1z5ebn3G05kAmfAVYJ3QqNEgxL8xxw?usp=sharing),
-which contains all input files necessary to run the example notebooks. Note that this link has restricted access and the folder can only be downloaded by approved parties.
 
-These files incorporate modifications from the original input files provided the NWFSC FEAT team (Chu). The changes involve primarily column names, some file names, and the source of mappings between haul numbers and transects numbers.
 
-## Running EchoPro
+## License
 
-First, set `data_root_dir` in [survey_year_2019_config.yml](https://github.com/uw-echospace/EchoPro/blob/master/config_files/survey_year_2019_config.yml)
-to the path to the directory `2019_consolidated_files`, which was downloaded in the previous step.
+Echopop is licensed under the open source [Apache 2.0 license](https://opensource.org/licenses/Apache-2.0).
 
-- For a **User** installation:
-    - Download `survey_year_2019_config.yml` and `initialization_config.yml` from https://github.com/uw-echospace/EchoPro/blob/master/config_files/. After navigating to each file, click on "Raw" (on the right) then save the file. Create a directory called `config_files` to store these files.
-    - Download the notebooks from https://uw-echospace.github.io/EchoPro/ and place them in a new directory named `example_notebooks`, at the same level as the `config_files` directory.
-- For a **Developer** installation:
-    - `survey_year_2019_config.yml` is found in the `config_files` directory.
-    - The notebooks are found in the `example_notebooks` directory.
+---------------
 
-Now start Jupyter **notebook**:
-```bash
-cd example_notebooks
-jupyter-notebook
-```
-
-Select the notebook you'd like to run. Once the notebook is open, set the "kernel" (conda environment) to "echopro" by going to the menu item `Kernel > Change kernel` and selecting "Python [conda env:echopro]".
-
-Note that an interactive widget used for exploring and selecting the semi-variogram currently does not work correctly with **JupyterLab**. This wil be addressed in a future release.
-
-## Tests
-
-Echopop contains several tests to continuously verify functionality as changes are implemented. These tests are found in [EchoPro/tests](https://github.com/uw-echospace/EchoPro/tree/master/EchoPro/tests). They are not currently set up to run automatically in the GitHub Actions Continuous Integration system. Instead, they must be run locally. They require a set of Excel output files from Matlab EchoPro for comparison of restults, available in [this Google Drive folder](https://drive.google.com/drive/folders/1_sUDUJY_e6M9cB3n5uibWeoukPqFP8ZO?usp=drive_link). This link has restricted access and the folder can only be downloaded by approved parties. After downloading the files, please set the file path to the containing folder in `tests/conftest.py`, [here](https://github.com/uw-echospace/EchoPro/blob/master/EchoPro/tests/conftest.py#L45).
+Copyright (c) 2022-2024, Echopop Developers.

docs/_config.yml

@@ -28,7 +28,7 @@ parse:
 
 # Information about where the book exists on the web
 repository:
-  url: https://github.com/uw-echospace/EchoPro  # Online location of your book
+  url: https://github.com/OSOceanAcoustics/echopop  # Online location of your book
   path_to_book: docs  # Optional path to your book, relative to the repository root
   branch: master  # Which branch of the repository should be used when creating links (optional)
 

docs/_toc.yml

@@ -6,7 +6,7 @@ root: index
 parts:
 - caption: Documentation
   chapters:
-  - file: quick_start
+  - file: install
   - file: core_data_structure
   - file: input_files
   - file: theory

docs/index.md

@@ -1,18 +1,54 @@
-# EchoPro
+# Echopop
 
-This site currently hosts example Jupyter notebooks for the Echopop package (https://github.com/uw-echospace/EchoPro/). Over time, the documentation for this package will be added here too.
+Echopop combines acoustic data collected by echosounders with biological "ground truth" information from trawls to produce biological estimates, such as biomass  and abundance. 
 
-The Jupyter notebooks are shown in a "rendered", executed form.
+Current the processing is configured to work with Acoustic-Trawl survey data for Pacific hake, but we will soon add components to include Pacific krill into the package. The majority of the computational implementation is applicable for other fish and zooplankton species, and we plan to expand the package for general support in the near future.
 
-```{admonition} Glitches with some interactive graphical elements
+
+<!-- ```{admonition} Glitches with some interactive graphical elements
 While the notebooks in this site are rendered, there are some glitches in the display we're still working out. In particular, an [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/) interactive graphical element in the semivariogram widget doesn't display correctly. The notebooks do run correctly when executed with Jupyter Notebook ("classic", not JupyterLab).
-```
+``` -->
 
-Go to the individual example notebooks below or in the table of content on the left.
+<!-- Go to the individual example notebooks below or in the table of content on the left.
 
 ```{tableofcontents}
-```
+``` -->
+
+
+## Acknowledgement
+
+We thank Dezhang Chu (@DezhangChu) of the NOAA Northwest Fisheries Science Center
+for providing the Matlab EchoPro program he developed
+that many elements of Echopop is based on,
+as well as his detailed consultation for implementations specific to Pacific hake.
+
+We also thank Rebecca Thomas (@rebeccathomas-NOAA),
+Beth Phillips (@ElizabethMPhillips),
+Alicia Billings (@aliciabillings-noaa),
+and Julia Clemons (@JuliaClemons-NOAA)
+of the Fisheries Engineering and Acoustics Team (FEAT)
+of the NOAA Northwest Fisheries Science Center for continuing discussions
+that make Echopop better.
+
+We also thank funding from NOAA Fisheries to support this work.
+
+<div>
+  <a>
+    <img src="./images/noaa_fisheries_logo.png" alt="NOAA_fisheries_logo" width="200">
+  </a>
+</div>
+
+
+
+## Contributors
+
+Echopop development is currently co-led by Wu-Jung Lee (@leewujung) and Brandyn Lucca (@brandynluca). Brandon Reyes (@b-reyes) and Emilio Mayorga (@emiliom) contributed significantly to a previous version of Echopop.
+
+
+## License
+
+Echopop is licensed under the open source [Apache 2.0 license](https://opensource.org/licenses/Apache-2.0).
 
-## Installation
+---------------
 
-See the [README.md](https://github.com/uw-echospace/EchoPro/blob/master/README.md) in the EchoPro repository for installation and execution instructions. 
+Copyright (c) 2022-2024, Echopop Developers.

docs/input_files.md

@@ -1,4 +1,4 @@
-ipynb# Input files
+# Input files
 
 Input files used in an Echopop run, grouped by data type. The tables below describe the data columns required by Echopop; other columns will be ignored. All input files are in Excel format. File paths, names, and Excel tab names are specified in the survey year configuration file (e.g., `survey_year_2019_config.yml`).
 
@@ -11,7 +11,7 @@ To minimize duplication in the data file description tables below, additional de
 - `species_id`: Species identification code (ID). Identifies what species is associated with the collected data. Pacific hake is 22500.
 - `N/P`: Empty value Not Permitted.
 - `nmi`: Nautical miles.
-- `Old name`: Column name used previously with Matlab EchoPro
+- `Old name`: Column name used previously in the Matlab EchoPro program
 
 ```{contents}
 :local:

docs/install.md

@@ -0,0 +1,46 @@
+# Installation
+
+Echopop is not yet available to be installed on PyPI or conda. We plan to enable these distributions at release v0.4.2 after the current refacotring code is completed.
+
+Until then, you can install Echopop from the repository following the steps below.
+
+## 1. Create a virtual environment
+
+To keep your Echopop environment isolated, it's recommended to create a virtual environment using Conda or Python's built-in `venv` module. Here's an example using Conda:
+
+```bash
+conda create --name echopop-env
+conda activate echopop-env
+```
+
+```{attention} 
+We recommend using the ``libmamba`` solver instead of the classic solver.
+   See instructions `here <https://conda.github.io/conda-libmamba-solver/getting-started/>`_
+   for installation and usage.
+```
+
+
+Or, using Python's venv:
+
+```bash
+python -m venv echopop-env
+source echopop-env/bin/activate  # On Windows, use `echopop-env\Scripts\activate`
+```
+
+## 2. Clone the repo
+Now that you have a virtual environment set up, you can clone the Echopop project repository to your local machine using the following command:
+
+```bash
+git clone https://github.com/OSOceanAcoustics/echopop.git
+```
+
+## 3. Install the package
+
+Navigate to the project directory you've just cloned and install the Echopop package:
+
+```bash
+cd <project_directory>
+pip install -e .
+```
+
+The `-e` flag here means that you are installing Echopop in a development mode, which allows you to not only use but also develop the code.

requirements.txt

@@ -1,7 +1,6 @@
 ipympl
 ipywidgets
 jupyter_contrib_nbextensions
-notebook
 # 9/27/23. See https://github.com/microsoft/azuredatastudio/issues/24436#issuecomment-1723328100
 traitlets<5.10
 geopandas