Improve documentation layout and some minor code polishing

Author: gavinmacaulay

docs/api_reference.md

@@ -4,85 +4,39 @@ This is the API reference for the echoSMs package.
 
 Each type of model is contained in a separate Python class (with name ending in ``Model``), but with common calling signatures across all model classes, as defined in ``ScatterModelBase``. There are also classes to provide ready access to the benchmark models and reference model definitions. There are also utility functions.
 
-## ScatterModelBase
+## ::: echosms.ScatterModelBase
 
-::: echosms.ScatterModelBase
-
-## DCMModel
-
-::: echosms.DCMModel
+## ::: echosms.DCMModel
 
 ## DWBA models
 
-There are several models that use the distorted-wave Born approximation, documented below:
-
-### DWBA
+There are several models that use the distorted-wave Born approximation, documented below. There are also some functions to
+make cylinder and spheroid shapes for use in the DWBA models.
 
 ::: echosms.DWBAModel
-    options:
-        heading_level: 4
-
-### PT-DWBA
-
 ::: echosms.PTDWBAModel
-    options:
-        heading_level: 4
-
-### SDWBA
-
 ::: echosms.SDWBAModel
-    options:
-        heading_level: 4
-
-### Utilities
+::: echosms.dwbautils
 
-::: echosms.utilsdwba
-    options:
-        heading_level: 4
+## ::: echosms.ESModel
 
-## ESModel
+## ::: echosms.HPModel
 
-::: echosms.ESModel
+## ::: echosms.KAModel
 
-## HPModel
-
-::: echosms.HPModel
-
-## KAModel
-
-::: echosms.KAModel
-
-## KRMModel
+## KRM model & utilities
 
 ::: echosms.KRMModel
+::: echosms.KRMdata
+::: echosms.KRMorganism
+::: echosms.KRMshape
 
-## MSSModel
-
-::: echosms.MSSModel
-
-## PSMSModel
-
-::: echosms.PSMSModel
-
-## ReferenceModels
-
-::: echosms.ReferenceModels
-
-## BenchmarkData
+## ::: echosms.MSSModel
 
-::: echosms.BenchmarkData
+## ::: echosms.PSMSModel
 
 ## Utilities
 
+::: echosms.BenchmarkData
+::: echosms.ReferenceModels
 ::: echosms.utils
-
-## KRMData
-::: echosms.KRMdata
-
-## KRMfish
-
-::: echosms.KRMfish
-
-## KRMshape
-
-::: echosms.KRMshape

docs/benchmark_data.md

@@ -5,8 +5,7 @@ The benchmark data for the acoustic scattering models in [Jech et al. (2015)](ht
 - Model runs over a range of frequencies
 - Model runs over a range of incident angles at a frequency of 38 kHz
 
-These are provided as text files (see below), or as Pandas DataFrames via the
-[BenchmarkData][benchmarkdata] class.
+These are provided as text files (see below), or as Pandas DataFrames via the [benchmarkdata] class.
 
 ## TS(f)
 

docs/usage.md

@@ -170,7 +170,7 @@ The `multiprocess = True` parameter in the call to `calculate_ts` will cause ech
 
 ## Reference model definitions
 
-[Jech et al., (2015)](https://doi.org/10.1121/1.4937607) presented _reference_ models for a range of scattering objects: spheres, spherical shells, prolate spheroids, and finite cylinders for several boundary conditions (fixed rigid, pressure release, fluid-filled) and parameters (backscatter as a function of frequency and incident angle). These model definitions are included in echoSMs via the [`ReferenceModels`](api_reference.md#referencemodels) class, along with other objects, such as calibration spheres. For example, the names of all the model definitions are available with:
+[Jech et al., (2015)](https://doi.org/10.1121/1.4937607) presented _reference_ models for a range of scattering objects: spheres, spherical shells, prolate spheroids, and finite cylinders for several boundary conditions (fixed rigid, pressure release, fluid-filled) and parameters (backscatter as a function of frequency and incident angle). These model definitions are included in echoSMs via the [`ReferenceModels`](api_reference.md#echosms.ReferenceModels) class, along with other objects, such as calibration spheres. For example, the names of all the model definitions are available with:
 
 ```py
     from echosms import ReferenceModels
@@ -272,7 +272,7 @@ Note that the `parameters()` call does not return all of the parameters needed b
 
 ## Benchmark model TS
 
-[Jech et al., (2015)](https://doi.org/10.1121/1.4937607) presented _benchmark_ model runs for the reference models. The TS results from these benchmarks are available in echoSMs via the [`BenchMarkData`](api_reference.md#benchmarkdata) class. This class is a simple wrapper around code that reads the CSV-formatted file of benchmark values into a Pandas DataFrame, whereupon they can be accessed like this:
+[Jech et al., (2015)](https://doi.org/10.1121/1.4937607) presented _benchmark_ model runs for the reference models. The TS results from these benchmarks are available in echoSMs via the [`BenchMarkData`](api_reference.md#echosms.BenchmarkData) class. This class is a simple wrapper around code that reads the CSV-formatted file of benchmark values into a Pandas DataFrame, whereupon they can be accessed like this:
 
 ```py
     from echosms import BenchmarkData

mkdocs.yml

@@ -61,7 +61,7 @@ plugins:
                     merge_init_into_class: true
                     show_bases: true
                     inherited_members: true
-                    show_root_heading: false
+                    show_root_heading: true
                     show_root_toc_entry: false
                     show_source: true
                     heading_level: 3

src/echosms/__init__.py

@@ -16,13 +16,13 @@
 from .kamodel import KAModel
 from .krmmodel import KRMModel
 from .hpmodel import HPModel
-from .krmdata import KRMdata, KRMfish, KRMshape
+from .krmdata import KRMdata, KRMorganism, KRMshape
 
 __all__ = ['ScatterModelBase', 'BenchmarkData', 'ReferenceModels',
            'MSSModel', 'PSMSModel', 'DCMModel', 'ESModel', 'PTDWBAModel',
            'DWBAModel', 'SDWBAModel', 'KAModel', 'KRMModel', 'HPModel',
            'wavenumber', 'wavelength', 'Neumann', 'h1', 'spherical_jnpp', 'prolate_swf',
-           'theoretical_Sa', 'KRMdata', 'KRMfish', 'KRMshape',
+           'theoretical_Sa', 'KRMdata', 'KRMorganism', 'KRMshape',
            'pro_rad1', 'pro_rad2', 'pro_ang1',
            'as_dataframe', 'as_dataarray', 'as_dict', 'split_dict',
            'create_dwba_spheroid', 'create_dwba_cylinder']

src/echosms/benchmarkdata.py

@@ -20,7 +20,7 @@ class BenchmarkData:
     Notes
     -----
     The column names in the source benchmark files have been changed to be the same as those used
-    in the [ReferenceModels][referencemodels] model definitions.
+    in the [referencemodels] model definitions.
 
     References
     ----------

src/echosms/utilsdwba.py renamed to src/echosms/dwbautils.py

@@ -3,7 +3,6 @@
 
 import matplotlib.pyplot as plt
 import numpy as np
-import pandas as pd
 import trimesh
 
 from echosms import MSSModel, PSMSModel, DCMModel, ESModel, PTDWBAModel, KAModel, DWBAModel