From 171595f1da06df1b48a9a6201bff1e4ebc205003 Mon Sep 17 00:00:00 2001 From: Gavin Macaulay Date: Wed, 11 Sep 2024 15:11:29 +1200 Subject: [PATCH] Improve documentation layout and clarity of text --- docs/contributing.md | 44 -------------------------------------- docs/conventions.md | 42 ++++++++++++++++++++++++++++++++++++ docs/index.md | 6 ++++++ mkdocs.yml | 2 +- src/echosms/ptdwbamodel.py | 2 +- 5 files changed, 50 insertions(+), 46 deletions(-) delete mode 100644 docs/contributing.md create mode 100644 docs/conventions.md diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index fce51b4..0000000 --- a/docs/contributing.md +++ /dev/null @@ -1,44 +0,0 @@ -# Contributing to echoSMs - -We welcome all contributions to echoSMs, be it code, test cases, bug reports, discussion of models, etc. Please use the [github](https://github.com/ices-tools-dev/echoSMs) facilities for this (i.e., [issues](https://github.com/ices-tools-dev/echoSMs/issues), [pull requests](https://github.com/ices-tools-dev/echoSMs/pulls), and [discussions](https://github.com/ices-tools-dev/echoSMs/discussions)). We are also happy to accept directly code that we can add to echoSMs on your behalf. - -An objective of echoSMs is to provide scattering models in a form that is easy to access, use, and compare to other models. To help with that, we specify model parameter units, angle conventions, and required model outputs that code contributions should support. We also suggest coding conventions that should be followed. - -## Units - -We use SI units for the model parameters for model inputs and outputs, except for angles (degrees instead of radians) and target strength (use use deciBels). - -| Parameter | Units | Notes | -|-----------|-------|--| -|length, diameter, radius, thickness, etc|m|| -|density|kg/m³|| -|sound speed|m/s|| -|angle|°|[see below][coordinate-systems]| -|frequency|Hz|| -|target strength|dB|reference value is 1 m²| - -## Coordinate systems - -A single coordinate system should be used for all models provided by echoSMs. The aim is to ease the comparison of results between different models. - -The right-handed spherical coordinate system as defined by ISO 80000-2[^1] is to be used, where organisms are oriented such that _θ_ corresponds to pitch and _ɸ_ to roll, as illustrated below, where the organism lies along the _z_-axis and the positive _x_-axis extends above the organism: - - - -![The coordinate system](resources/coordinate_system.svg){:style="height:400px;width400px"} - -The definitions are such that _θ_ values of 0°, 90°, and 180° correspond to acoustic wave incidence angles of head on, dorsal, and tail on, respectively, and positive values of _ɸ_ indicate incidence angles from the positive _y_-axis side of the organism. Note that the definition of these angles is in terms of the acoustic wave, not the orientation of the organism. All model code should accept angles and produce results in this coordinate system. If the model calculations use a different coordinate system, the code should internally convert between the system given above and the version used in the code. - -## Code style - -Contributions of code should follow standardised or community-agreed styles and be provided in (or added to) a structure suitable for packaging and uploading to package libraries. For Python this includes `pip` and/or `conda`, for R this would be `CRAN`, for Matlab this would be a toolbox on the MATLAB File Exchange, etc. - -Python code should follow [PEP8](https://peps.python.org/pep-0008) and docstrings should use [PEP257](https://peps.python.org/pep-0257/) with the contents following the [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html). An exception to PEP8 is made to allow lines of up to 100 characters. - -[^1]: [ISO. 2019.](https://www.iso.org/obp/ui/en/#iso:std:iso:80000:-2:ed-2:v2:en) ISO 80000-2. Part 2: Mathematics. diff --git a/docs/conventions.md b/docs/conventions.md new file mode 100644 index 0000000..46497dc --- /dev/null +++ b/docs/conventions.md @@ -0,0 +1,42 @@ +# Conventions + +## Units + +We use SI units for the model parameters, except for angles (we use degrees instead of radians) and target strength (we use deciBels). All model code must accept inputs and produce results using the units below. If the model calculations use different units internally, the code should internally convert between the them. + +| Parameter | Units | Notes | +|-----------|-------|--| +|length, diameter, radius, thickness, etc|m|| +|density|kg/m³|| +|sound speed|m/s|| +|angle|°|See [Coordinate systems][coordinate-systems]| +|frequency|Hz|| +|target strength|dB|reference value is 1 m²| + +## Coordinate systems + +A single coordinate system should be used for all models provided by echoSMs. The aim is to ease the comparison of results between different models. + +The right-handed spherical coordinate system as defined by ISO 80000-2[^1] is to be used, as illustrated below. The organism should lie along the _z_-axis with the positive _x_-axis extending above the dorsal surface of the organism: + + + +![The coordinate system](resources/coordinate_system.svg){:style="height:400px;width400px"} + +The definitions are such that for _ɸ_=0°, _θ_ values of 0°, 90°, and 180° correspond to acoustic wave incidence angles of head on, dorsal, and tail on, respectively. Note that the definition of these angles is in terms of the acoustic wave, not the orientation of the organism (which should always be as shown in the illustration). + +All model code should accept angles and produce results in this coordinate system. If the model calculations use a different coordinate system, the code should internally convert between the system given above and the version used in the code. + +## Code style + +Contributions of code should follow standardised or community-agreed styles and be provided in (or added to) a structure suitable for packaging and uploading to package libraries. For Python this includes `pip` and/or `conda`, for R this would be `CRAN`, for Matlab this would be a toolbox on the MATLAB File Exchange, etc. + +Python code should follow [PEP8](https://peps.python.org/pep-0008) and docstrings should use [PEP257](https://peps.python.org/pep-0257/) with the contents following the [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html). An exception to PEP8 is made to allow lines of up to 100 characters. + +[^1]: [ISO. 2019.](https://www.iso.org/obp/ui/en/#iso:std:iso:80000:-2:ed-2:v2:en) ISO 80000-2. Part 2: Mathematics. diff --git a/docs/index.md b/docs/index.md index ce7960a..1fa3139 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,6 +10,12 @@ Quantitative interpretation of acoustic echograms requires software expertise to The goal of this project is to make acoustic scattering models available to fisheries and plankton acoustic scientists via the world wide web. By providing the models in an open-access and open-source software language (e.g, Python, R) and providing morphological and anatomical data in open data formats (e.g., HDF5, relational databases), the proper and appropriate use of these models can extend to the entire fisheries and plankton acoustics’ community. +## Contributing to echoSMs + +We welcome all contributions to echoSMs, be it code, test cases, bug reports, discussion of models, etc. Please use the [github](https://github.com/ices-tools-dev/echoSMs) facilities for this (i.e., [issues](https://github.com/ices-tools-dev/echoSMs/issues), [pull requests](https://github.com/ices-tools-dev/echoSMs/pulls), and [discussions](https://github.com/ices-tools-dev/echoSMs/discussions)). We are also happy to accept directly code that we can add to echoSMs on your behalf. + +An objective of echoSMs is to provide scattering models in a form that is easy to access, use, and compare to other models. To help with that, we [specify][conventions] model parameter units, angle conventions, and required model outputs that code contributions should support. We also suggest coding conventions that should be followed. + ## Scattering Models The initial set of acoustic scattering models will be those used in [Jech et al. (2015)](https://doi.org/10.1121/1.4937607). Acoustic model development will follow 3–4 phases: diff --git a/mkdocs.yml b/mkdocs.yml index 5636621..dfa43ec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,7 +2,7 @@ site_name: echoSMs nav: - Introduction: index.md - Usage: usage.md - - Contributing: contributing.md + - Conventions: conventions.md - Benchmarks: benchmark_data.md - API reference: api_reference.md - Other software: other_software.md diff --git a/src/echosms/ptdwbamodel.py b/src/echosms/ptdwbamodel.py index b4f78ac..17b7b80 100644 --- a/src/echosms/ptdwbamodel.py +++ b/src/echosms/ptdwbamodel.py @@ -27,7 +27,7 @@ def calculate_ts_single(self, volume, theta, phi, f, voxel_size, rho, c, **kwarg Warning ------- Input parameters `theta`, `phi`, and the orientation of `volume` do not currently follow the - echoSMs [coordinate system](contributing.md#coordinate-systems). + echoSMs [coordinate system](conventions.md#coordinate-systems). Parameters ----------