cgrudz / DataAssimilationBenchmarks.jl

Package Information and Documentation
https://cgrudz.github.io/DataAssimilationBenchmarks.jl/dev/
Apache License 2.0
13 stars 5 forks source link

Add usage examples and workflow to README.md #7

Closed peanutfun closed 2 years ago

peanutfun commented 2 years ago

The README.md documents the API of the module. As the argument lists are quite extensive, I think it would be helpful to add "typical" usage examples for some of the methods and solvers. In particular, this would help to demonstrate some kind of workflow. Starting out with generating a time series, an example could show how to run different data assimilation methods included in this package, and then how to evaluate the output and compare the methods against each other.

Currently, one has to look up a typical argument list in the tests, which is cumbersome.

openjournals/joss-reviews#4129

cgrudz commented 2 years ago

I think the following documentation section satisfies this https://cgrudz.github.io/DataAssimilationBenchmarks.jl/dev/submodules/experiments/ParallelExperimentDriver/#Example-usage though this package still assumes that one will dev the package to design their own experiments and create typical hyper-paramter configurations to load with them. I'm leaving this issue open for now while the review continues and while we re-submit our package for further discussion if the system makes sense.

cgrudz commented 2 years ago

I decided to add an additional section that sketches the overall workflow, where the documentation is organized a bit to emulate this workflow precisely:

https://cgrudz.github.io/DataAssimilationBenchmarks.jl/dev/submodules/experiments/Workflow/

This section in the documentation now discusses how one will go from an installation to the point of running a twin experiment following the submodules in the docs. I think this is now a better solution, though I will certainly take further suggestions on how to clarify the use example of the software.

peanutfun commented 2 years ago

Very good, thank you!