Skip to content

Commit

Permalink
fix typos and polish
Browse files Browse the repository at this point in the history
  • Loading branch information
gavinmacaulay committed Sep 24, 2024
1 parent db07af6 commit 2bc12d0
Showing 1 changed file with 13 additions and 3 deletions.
16 changes: 13 additions & 3 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ This will return one TS value corresponding to the parameters given. If you want

It is also fine to have multiple items with multiple values:

```py hl_lines="3 6"
```py hl_lines="3 4 6"
p = {'medium_rho': 1026.8,
'medium_c': 1477.4,
'a': np.arange(0.01, 0.02, 0.001),
Expand Down Expand Up @@ -118,7 +118,7 @@ The `multiprocess = True` parameter in the call to `calculate_ts` will cause ech
Some models require parameters for which it is not sensible to duplicate them across rows in a DataFrame or as a dimension in a DataArray (e.g., the data that specifies the three-dimensional shape of a fish swimbladder).
EchoSMs allows for this with the concept of _non-expandable_ parameters - these are not expanded into DataFrame columns or DataArray dimensions.

But, as it is very convenient to have all the model parameters in one data structure, echoSMs will store the non-expandable parameters as DataFrame or DataArray attributes. Due to a bug in the DataFrame implementation, the parameters are actually stored as a nested dictionary under a `parameters` key. An example of this is the PTDWBAModel():
But, as it is very convenient to have all the model parameters in one data structure, echoSMs will store the non-expandable parameters as DataFrame or DataArray attributes. Due to a bug in the DataFrame implementation, the parameters are actually stored as a nested dictionary under a `parameters` key. An example of this is the `PTDWBAModel`:

```py
from echosms import PTDWBAModel, as_dataframe
Expand All @@ -144,12 +144,22 @@ For the PTDWBA model, only `theta` and `phi` are expandable, so `p` contains jus
p.attrs.['parameters']
```

If you pass the dictionary form of the parameters to a model, this treatment of non-expanding parameters is done automatically:
Note that while `rho`, and `c` look like parameters that would be expanded, they are in the list of non-expandable parameters, so are not expanded. This is because the structure of the PTDWBA model means that it it not sensible to have variable parameters for `rho` and `c`.

If you pass the dictionary form of the parameters to a model, this treatment of non-expanding parameters is done automatically, where

```py
model.calculate_ts(m, expand=True)
```

returns the same results as

```py
p = as_dataframe(m, model.no_expand_parameters)
model.calculate_ts(p, inplace=True)`
print(p)
```

## 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`](https://ices-tools-dev.github.io/echoSMs/api_reference/#referencemodels) class. For example, the names of all the model definitions are available wiht:
Expand Down

0 comments on commit 2bc12d0

Please sign in to comment.