diff --git a/src/echosms/benchmarkdata.py b/src/echosms/benchmarkdata.py index 244d5ef..25ad28b 100644 --- a/src/echosms/benchmarkdata.py +++ b/src/echosms/benchmarkdata.py @@ -7,12 +7,12 @@ class BenchmarkData: """Convenient interface to the benchmark dataset. - This dataset contains the TS values from Jech et al., 2015. + This dataset contains the TS results from Jech et al., 2015. Jech, J.M., Horne, J.K., Chu, D., Demer, D.A., Francis, D.T.I., Gorska, N., Jones, B., Lavery, A.C., Stanton, T.K., Macaulay, G.J., Reeder, D.B., Sawada, K., 2015. Comparisons among ten models of acoustic backscattering used in aquatic ecosystem research. - Journal of the Acoustical Society of America 138, 3742–3764. https://doi.org/10.1121/1.4937607 + Journal of the Acoustical Society of America 138, 3742–3764. """ def __init__(self): @@ -26,11 +26,23 @@ def __init__(self): self.freq_data = pd.read_csv(freq_data_file) def dataset_angle(self): - """Return a Pandas dataframe containing the TS as a function of incidence angle dataset.""" + """Provide the angle benchmark data. + + Returns + ------- + : Pandas DataFrame + The TS as a function of incidence angle. + """ return self.angle_data def dataset_freq(self): - """Return a Pandas dataframe containing the TS as a function of frequency dataset.""" + """Provide the frequency benchmark data. + + Returns + ------- + : Pandas DataFrame + The TS as a function of frequency. + """ return self.freq_data # def dataset_angle(self, names): diff --git a/src/echosms/dcmmodel.py b/src/echosms/dcmmodel.py index 26cd52b..c1d0ddc 100644 --- a/src/echosms/dcmmodel.py +++ b/src/echosms/dcmmodel.py @@ -40,18 +40,18 @@ def calculate_ts_single(self, medium_c, medium_rho, a, b, theta, f, model_type, b : float Length of the cylinderical target [m]. theta : float - Pitch angle(s) to calculate the scattering at [degrees]. An angle of 0 is head on, + Pitch angle(s) to calculate the scattering at [°]. An angle of 0 is head on, 90 is dorsal, and 180 is tail on. f : float Frequencies to calculate the scattering at [Hz]. model_type : str - The model type. Supported model types are given in the model_types class variable. + The model type. Supported model types are given in the model_types class attribute. target_c : float, optional Sound speed in the fluid inside the sphere [m/s]. - Only required for `model_type` of ``fluid filled`` + Only required for `model_type` of ``fluid filled``. target_rho : float, optional Density of the fluid inside the sphere [kg/m³]. - Only required for `model_type` of ``fluid filled`` + Only required for `model_type` of ``fluid filled``. Returns ------- diff --git a/src/echosms/mssmodel.py b/src/echosms/mssmodel.py index dd80efc..18c3bbe 100644 --- a/src/echosms/mssmodel.py +++ b/src/echosms/mssmodel.py @@ -42,7 +42,7 @@ def calculate_ts_single(self, medium_c, medium_rho, a, theta, f, model_type, a : float Radius of the spherical target [m]. theta : float - Pitch angle(s) to calculate the scattering at [degrees]. An angle of 0 is head on, + Pitch angle(s) to calculate the scattering at [°]. An angle of 0 is head on, 90 is dorsal, and 180 is tail on. f : float Frequencies to calculate the scattering at [Hz]. @@ -50,10 +50,10 @@ def calculate_ts_single(self, medium_c, medium_rho, a, theta, f, model_type, The model type. Supported model types are given in the model_types class variable. target_c : float, optional Sound speed in the fluid inside the sphere [m/s]. - Only required for `model_type` of ``fluid filled`` + Only required for `model_type` of ``fluid filled``. target_rho : float, optional Density of the fluid inside the sphere [kg/m³]. - Only required for `model_type` of ``fluid filled`` + Only required for `model_type` of ``fluid filled``. shell_c : float, optional Sound speed in the spherical shell [m/s]. Only required for `model_type`s that include a fluid shell. diff --git a/src/echosms/psmsmodel.py b/src/echosms/psmsmodel.py index 704b357..3c60948 100644 --- a/src/echosms/psmsmodel.py +++ b/src/echosms/psmsmodel.py @@ -34,19 +34,19 @@ def calculate_ts_single(self, medium_c, medium_rho, a, b, theta, f, model_type, Prolate spheroid major axis radius [m]. b : float Prolate spheroid minor axis radius [m]. - theta : float or array of float - Pitch angle(s) to calculate the scattering at [degrees]. An angle of 0 is head on, + theta : float + Pitch angle(s) to calculate the scattering at [°]. An angle of 0 is head on, 90 is dorsal, and 180 is tail on. - f : float or array of float + f : float Frequencies to calculate the scattering at [Hz]. model_type : str The model type. Supported model types are given in the model_types class variable. target_c : float, optional Sound speed in the fluid inside the target [m/s]. - Only required for `model_type` of ``fluid filled`` + Only required for `model_type` of ``fluid filled``. target_rho : float, optional Density of the fluid inside the target [kg/m³]. - Only required for `model_type` of ``fluid filled`` + Only required for `model_type` of ``fluid filled``. Returns ------- diff --git a/src/echosms/referencemodels.py b/src/echosms/referencemodels.py index f2a08c2..5b14caa 100644 --- a/src/echosms/referencemodels.py +++ b/src/echosms/referencemodels.py @@ -27,15 +27,38 @@ def __init__(self): pass def models(self): - """Return the full set of model definitions.""" + """Provide the full set of model definitions. + + Returns + ------- + : dict + The contents of the ```target definitions.toml`` file in the form of a dict. + """ return self.defs def model_names(self): - """Return the names of all model definitions.""" + """Names of all model definitions. + + Returns + ------- + : iterable of str + All model names in the ``target definitions/toml`` file. + """ return [n['name'] for n in self.defs['target']] def get_model_specification(self, name): - """Get the model defintions for a particular model.""" + """Get the model defintions for a particular model. + + Parameters + ---------- + name : str + The name of a model in the ``target definitions.toml`` file. + + Returns + ------- + : dict + The model definitions for the requested model or ``None`` if no model with that name. + """ models = pd.DataFrame(self.defs['target']) m = models.query('name == @name') if len(m) == 1: @@ -49,8 +72,23 @@ def get_model_parameters(self, name): Model parameters are a subset of the model specification where the non-numerical items have been removed. + + Parameters + ---------- + name : str + The name of a model in the ``target definitions.toml`` file. + + Returns + ------- + : dict + The model parameters for the requested model or ``None`` if no model with that name. + """ s = self.get_model_specification(name) + + if s is None: + return s + # Remove the entries that are not parameters p = s del p['name']