search

OxIonics / ionics_fits

Small python fitting library with an emphasis on Atomic Molecular and Optical Physics
Apache License 2.0
0 stars 0 forks source link

Improve documentation for models in `containers` #91

Closed AUTProgram closed 6 months ago

AUTProgram commented 1 year ago

I had a quick first look at the new model container classes, but from the existing docstrings it's not clear to me what the purpose of each container model is. For example, what does `"aggregating one or more models" mean? Is a repeated model just a convenience class to use the same model on different data (which is what "repeated" implies to me) or does it provide functionality that could not be achieved by using separate models? I'll have a look at source code to find out, but I think it's a sign that the documentation can be improved if the user starts reading source code.

hartytp commented 1 year ago

I see the purpose of docstrings as being largely to document the interface and how the parameters are used. I'm reading your question here as being more about looking for examples, which I find is often best outside of docstrings. For this, I've been using the readme. Specifically, I wonder if https://github.com/OxIonics/ionics_fits#containers answers some of your questions?

Is a repeated model just a convenience class to use the same model on different data (which is what "repeated" implies to me) or does it provide functionality that could not be achieved by using separate models?

A bit of both. It's largely convenience, but the docstring already mentions a couple of features which would not be possible using independent models: common parameters, calculating statistical quantities for results automatically (e.g. what is the mean value of this parameter across the repetitions?)

hartytp commented 1 year ago

If you have concrete suggestions for what you think would be helpful, do feel free to open a PR.