dapper 1.7.0__tar.gz → 1.7.2__tar.gz

dapper-1.7.2/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: dapper
+Version: 1.7.2
+Summary: DAPPER benchmarks the performance of data assimilation (DA) methods.
+Author: Patrick N. Raanes
+Author-email: patrick.n.raanes@gmail.com
+Project-URL: Documentation, https://nansencenter.github.io/DAPPER/
+Project-URL: Source, https://github.com/nansencenter/DAPPER
+Project-URL: Tracker, https://github.com/nansencenter/DAPPER/issues
+Keywords: data-assimilation enkf kalman-filtering state-estimation particle-filter kalman bayesian-methods bayesian-filter chaos
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENCE.txt
+Requires-Dist: scipy>=1.14
+Requires-Dist: numpy~=2.0
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: ipython>=7.34
+Requires-Dist: ipdb
+Requires-Dist: jupyter
+Requires-Dist: notebook<7
+Requires-Dist: mpl-tools==0.4.1
+Requires-Dist: tqdm~=4.67
+Requires-Dist: colorama~=0.4.1
+Requires-Dist: tabulate~=0.8.3
+Requires-Dist: pathos~=0.3
+Requires-Dist: dill==0.3.8
+Requires-Dist: patlib==0.3.7
+Requires-Dist: struct-tools==0.2.5
+Requires-Dist: threadpoolctl<4.0.0,>=3.0.0
+Provides-Extra: qt
+Requires-Dist: PyQt5; extra == "qt"
+Requires-Dist: qtpy; extra == "qt"
+Provides-Extra: debug
+Requires-Dist: line_profiler; extra == "debug"
+Requires-Dist: pre-commit; extra == "debug"
+Provides-Extra: test
+Requires-Dist: tox; extra == "test"
+Requires-Dist: coverage>=5.1; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-sugar; extra == "test"
+Requires-Dist: pytest-benchmark; extra == "test"
+Requires-Dist: pytest-clarity; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: doc
+Requires-Dist: mkdocs-material; extra == "doc"
+Requires-Dist: mkdocstrings; extra == "doc"
+Requires-Dist: mkdocstrings-python; extra == "doc"
+Requires-Dist: mkdocs-gen-files; extra == "doc"
+Requires-Dist: mkdocs-literate-nav; extra == "doc"
+Requires-Dist: mkdocs-section-index; extra == "doc"
+Requires-Dist: mkdocs-glightbox; extra == "doc"
+Requires-Dist: mkdocs-jupyter; extra == "doc"
+Requires-Dist: pybtex; extra == "doc"
+Provides-Extra: build
+Requires-Dist: twine; extra == "build"
+Requires-Dist: jupytext<=1.15; extra == "build"
+Provides-Extra: dev
+Requires-Dist: line_profiler; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: coverage>=5.1; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-sugar; extra == "dev"
+Requires-Dist: pytest-benchmark; extra == "dev"
+Requires-Dist: pytest-clarity; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: jupytext<=1.15; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mkdocstrings; extra == "dev"
+Requires-Dist: mkdocstrings-python; extra == "dev"
+Requires-Dist: mkdocs-gen-files; extra == "dev"
+Requires-Dist: mkdocs-literate-nav; extra == "dev"
+Requires-Dist: mkdocs-section-index; extra == "dev"
+Requires-Dist: mkdocs-glightbox; extra == "dev"
+Requires-Dist: mkdocs-jupyter; extra == "dev"
+Requires-Dist: pybtex; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+It is usually best to install from source (github),
+so that you the code is readily available to play with.
+See full README on [github](https://github.com/nansencenter/DAPPER).

{dapper-1.7.0 → dapper-1.7.2}/README.md

@@ -8,7 +8,7 @@
 !
 -->
 
-<img src="/docs/imgs/logo_wtxt.png" align="left" width="250"/>
+<img src="https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/logo_wtxt.png" alt="DAPPER logo" align="left" width="250"/>
 
 DAPPER is a set of templates for **benchmarking** the performance of **data assimilation** (DA) methods.
 The numerical experiments provide support and guidance for new developments in DA.
@@ -26,20 +26,19 @@ and then estimate that truth given the models and noisy observations.
 
 ## Getting started
 
-[Install](#installation), then
-read, run and try to understand `examples/basic_{1,2,3}.py`.
-Some of the examples also exist as Jupyter notebooks, and can be run in the cloud
-*without installation* (but requiring Google login): [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](http://colab.research.google.com/github/nansencenter/DAPPER).
-This [screencast](https://www.youtube.com/watch?v=YtalK0Zkzvg&t=6475s)
-provides an overview to DAPPER.
-The [documentation](https://nansencenter.github.io/DAPPER)
-includes general guidelines and the API reference,
-but most users must expect to read the code as well.
-If used towards a publication, please cite as
-*The experiments used (inspiration from) DAPPER [ref], version 1.6.0*,
-or similar, where [ref] points to [![DOI](https://joss.theoj.org/papers/10.21105/joss.05150/status.svg)](https://doi.org/10.21105/joss.05150).
-Also see the interactive [tutorials on DA theory](https://github.com/nansencenter/DA-tutorials)
-with Python.
+- Read & run [examples](examples)/`basic_1.py` and `basic_2.py`,
+  or their corresponding notebooks [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](http://colab.research.google.com/github/nansencenter/DAPPER)
+  (requires Google login).
+- This [screencast](https://www.youtube.com/watch?v=YtalK0Zkzvg&t=6475s)
+  provides an overview to DAPPER.
+- [Install](#installation).
+- The [documentation](https://nansencenter.github.io/DAPPER)
+  includes general guidelines and the API reference,
+  but most users must expect to read the code as well.
+- If used towards a publication, please cite as
+  *The experiments used (inspiration from) DAPPER [ref], version 1.6.0*,
+  or similar, where [ref] points to [![DOI](https://joss.theoj.org/papers/10.21105/joss.05150/status.svg)](https://doi.org/10.21105/joss.05150).
+- Also see the interactive [tutorials on DA theory](https://github.com/nansencenter/DA-tutorials) with Python.
 
 ## Highlights
 
@@ -49,7 +48,7 @@ through a variety of typical [test cases](#test-cases-models) and statistics. It
 (b) facilitates comparative studies, thus promoting the
 (a) reliability and
 (b) relevance of the results.
-For example, the figure below is generated by `examples/basic_3.py`,
+For example, the figure below is generated by `docs/examples/basic_3.py`,
 reproduces figure 5.7 of [these lecture notes](http://cerea.enpc.fr/HomePages/bocquet/teaching/assim-mb-en.pdf).
 DAPPER is
 (c) open source, written in Python, and
@@ -59,10 +58,10 @@ this promotes the
 (d) dissemination of the underlying science,
 and makes it easy to adapt and extend.
 
-![Comparative benchmarks with Lorenz-96 plotted as a function of the ensemble size (N)](./docs/imgs/ex3.svg)
+![Comparative benchmarks with Lorenz-96 plotted as a function of the ensemble size (N)](https://github.com/nansencenter/DAPPER/raw/master/docs/images/ex3.svg)
 
 DAPPER demonstrates how to parallelise ensemble forecasts (e.g., the QG model),
-local analyses (e.g., the LETKF), and independent experiments (e.g., `examples/basic_3.py`).
+local analyses (e.g., the LETKF), and independent experiments (e.g., `docs/examples/basic_3.py`).
 It includes a battery of diagnostics and statistics,
 which all get averaged over subdomains (e.g., "ocean" and "land") and then in time.
 Confidence intervals are computed, including correction for auto-correlations,
@@ -72,7 +71,7 @@ which may be paused for further interactive inspection.
 In summary, DAPPER is well suited for teaching and fundamental DA research.
 Also see its [drawbacks](#similar-projects).
 
-![EnKF - Lorenz-96](./docs/imgs/ex1.jpg)
+![EnKF - Lorenz-96](https://github.com/nansencenter/DAPPER/raw/master/docs/images/ex1.jpg)
 
 <!-- Non-highlighted features:
 - Time sequences use via `tools.chronos.Chronology` and `tools.chronos.Ticker`.
@@ -89,7 +88,7 @@ Also see its [drawbacks](#similar-projects).
 
 Successfully tested on Linux/Mac/Windows.
 
-### Prerequisite: Python>=3.9
+### Prerequisite: Python>=3.12
 
 If you're an expert, setup a python environment however you like.
 Otherwise:
@@ -132,7 +131,7 @@ You should now be able to do run your script with
 `python path/to/script.py`.  
 For example, if you are in the DAPPER dir,
 
-    python examples/basic_1.py
+    python docs/examples/basic_1.py
 
 **PS**: If you closed the terminal (or shut down your computer),
 you'll first need to run `conda activate dapper-env`
@@ -142,23 +141,23 @@ you'll first need to run `conda activate dapper-env`
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable line-length -->
-Method                                                 | Literature reproduced
------------------------------------------------------- | ------------------------
-EnKF <sup>1</sup>                                      | [Sakov08](https://nansencenter.github.io/DAPPER/bib.html#bib.sakov2008deterministic), [Hoteit15](https://nansencenter.github.io/DAPPER/bib.html#bib.hoteit2015mitigating), [Grudzien2020](https://nansencenter.github.io/DAPPER/bib.html#bib.grudzien2020numerical)
-EnKF-N                                                 | [Bocquet12](https://nansencenter.github.io/DAPPER/bib.html#bib.bocquet2012combining), [Bocquet15](https://nansencenter.github.io/DAPPER/bib.html#bib.bocquet2015expanding)
-EnKS, EnRTS                                            | [Raanes2016](https://nansencenter.github.io/DAPPER/bib.html#bib.raanes2016thesis)
-iEnKS / iEnKF / EnRML / ES-MDA <sup>2</sup>            | [Sakov12](https://nansencenter.github.io/DAPPER/bib.html#bib.sakov2012iterative), [Bocquet12](https://nansencenter.github.io/DAPPER/bib.html#bib.Bocquet12), [Bocquet14](https://nansencenter.github.io/DAPPER/bib.html#bib.bocquet2014iterative)
-LETKF, local & serial EAKF                             | [Bocquet11](https://nansencenter.github.io/DAPPER/bib.html#bib.bocquet2011ensemble)
-Sqrt. model noise methods                              | [Raanes2014](https://nansencenter.github.io/DAPPER/bib.html#bib.raanes2014ext)
-Particle filter (bootstrap) <sup>3</sup>               | [Bocquet10](https://nansencenter.github.io/DAPPER/bib.html#bib.bocquet2010beyond)
-Optimal/implicit Particle filter  <sup>3</sup>         | [Bocquet10](https://nansencenter.github.io/DAPPER/bib.html#bib.bocquet2010beyond)
-NETF                                                   | [Tödter15](https://nansencenter.github.io/DAPPER/bib.html#bib.todter2015second), [Wiljes16](https://nansencenter.github.io/DAPPER/bib.html#bib.wiljes2016second)
-Rank histogram filter (RHF)                            | [Anderson10](https://nansencenter.github.io/DAPPER/bib.html#bib.anderson2010non)
-4D-Var                                                 |
-3D-Var                                                 |
-Extended KF                                            |
-Optimal interpolation                                  |
-Climatology                                            |
+| Method                                               | Literature reproduced                                                                                                                        |
+|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| EnKF <sup>1</sup>                                    | [Sakov08](https://nansencenter.github.io/DAPPER/references/#sakov2008b), [Hoteit15](https://nansencenter.github.io/DAPPER/references/#hoteit2015a), [Grudzien2020](https://nansencenter.github.io/DAPPER/references/#grudzien2020a) |
+| EnKF-N                                               | [Bocquet12](https://nansencenter.github.io/DAPPER/references/#bocquet2012a), [Bocquet15](https://nansencenter.github.io/DAPPER/references/#bocquet2015)                                 |
+| EnKS, EnRTS                                          | [Raanes2016](https://nansencenter.github.io/DAPPER/references/#raanes2016thesis)                                                              |
+| iEnKS / iEnKF / EnRML / ES-MDA <sup>2</sup>          | [Sakov12](https://nansencenter.github.io/DAPPER/references/#sakov2012a), [Bocquet12](https://nansencenter.github.io/DAPPER/references/#Bocquet12), [Bocquet14](https://nansencenter.github.io/DAPPER/references/#bocquet2014) |
+| LETKF, local & serial EAKF                           | [Bocquet11](https://nansencenter.github.io/DAPPER/references/#bocquet2011)                                                                   |
+| Sqrt. model noise methods                            | [Raanes2014](https://nansencenter.github.io/DAPPER/references/#raanes2014)                                                                   |
+| Particle filter (bootstrap) <sup>3</sup>             | [Bocquet10](https://nansencenter.github.io/DAPPER/references/#bocquet2010a)                                                                  |
+| Optimal/implicit Particle filter  <sup>3</sup>       | [Bocquet10](https://nansencenter.github.io/DAPPER/references/#bocquet2010a)                                                                  |
+| NETF                                                 | [Tödter15](https://nansencenter.github.io/DAPPER/references/#todter2015a), [Wiljes16](https://nansencenter.github.io/DAPPER/references/#wiljes2016)                                 |
+| Rank histogram filter (RHF)                          | [Anderson10](https://nansencenter.github.io/DAPPER/references/#anderson2010)                                                                 |
+| 4D-Var                                               |                                                                                                                                              |
+| 3D-Var                                               |                                                                                                                                              |
+| Extended KF                                          |                                                                                                                                              |
+| Optimal interpolation                                |                                                                                                                                              |
+| Climatology                                          |                                                                                                                                              |
 <!-- markdownlint-restore -->
 
 <sup>1</sup>: Stochastic, DEnKF (i.e. half-update), ETKF (i.e. sym. sqrt.).
@@ -184,22 +183,22 @@ grep -r "xp.*iEnKS" dapper/mods
 Simple models facilitate the reliability, reproducibility,
 and interpretability of experiment results.
 
-Model                | Lin | TLM** | PDE?  | Phys.dim. | State len | Lyap≥0 | Implementer
------------          | --- | ----- | ----  | --------- | --------- | ------ | ----------
-Id                   | Yes | Yes   | No    | N/A       | *         | 0      | Raanes
-Linear Advect. (LA)  | Yes | Yes   | Yes   | 1d        | 1000 *    | 51     | Evensen/Raanes
-DoublePendulum       | No  | Yes   | No    | 0d        | 4         | 2      | Matplotlib/Raanes
-Ikeda                | No  | Yes   | No    | 0d        | 2         | 1      | Raanes
-LotkaVolterra        | No  | Yes   | No    | 0d        | 5 *       | 1      | Wikipedia/Raanes
-Lorenz63             | No  | Yes   | "Yes" | 0d        | 3         | 2      | Sakov
-Lorenz84             | No  | Yes   | No    | 0d        | 3         | 2      | Raanes
-Lorenz96             | No  | Yes   | No    | 1d        | 40 *      | 13     | Raanes
-Lorenz96s            | No  | Yes   | No    | 1d        | 10 *      |  4     | Grudzien
-LorenzUV             | No  | Yes   | No    | 2x 1d     | 256 + 8 * | ≈60    | Raanes
-LorenzIII            | No  | No    | No    | 1d        | 960 *     | ≈164   | Raanes
-Vissio-Lucarini 20   | No  | Yes   | No    | 1d        | 36 *      | 10     | Yumeng
-Kuramoto-Sivashinsky | No  | Yes   | Yes   | 1d        | 128 *     | 11     | Kassam/Raanes
-Quasi-Geost (QG)     | No  | No    | Yes   | 2d        | 129²≈17k  | ≈140   | Sakov
+| Model                | Lin | TLM`**` | PDE?  | Phys.dim. | State len | Lyap≥0 | Implementer         |
+|----------------------|-----|-------|-------|-----------|-----------|--------|---------------------|
+| Id                   | Yes | Yes   | No    | N/A       | `*`         | 0      | Raanes              |
+| Linear Advect. (LA)  | Yes | Yes   | Yes   | 1d        | 1000 `*`    | 51     | Evensen/Raanes      |
+| DoublePendulum       | No  | Yes   | No    | 0d        | 4         | 2      | Matplotlib/Raanes   |
+| Ikeda                | No  | Yes   | No    | 0d        | 2         | 1      | Raanes              |
+| LotkaVolterra        | No  | Yes   | No    | 0d        | 5 `*`       | 1      | Wikipedia/Raanes    |
+| Lorenz63             | No  | Yes   | "Yes" | 0d        | 3         | 2      | Sakov               |
+| Lorenz84             | No  | Yes   | No    | 0d        | 3         | 2      | Raanes              |
+| Lorenz96             | No  | Yes   | No    | 1d        | 40 `*`      | 13     | Raanes              |
+| Lorenz96s            | No  | Yes   | No    | 1d        | 10 `*`      | 4      | Grudzien            |
+| LorenzUV             | No  | Yes   | No    | 2x 1d     | 256 + 8 `*` | ≈60    | Raanes              |
+| LorenzIII            | No  | No    | No    | 1d        | 960 `*`     | ≈164   | Raanes              |
+| Vissio-Lucarini 20   | No  | Yes   | No    | 1d        | 36 `*`      | 10     | Yumeng              |
+| Kuramoto-Sivashinsky | No  | Yes   | Yes   | 1d        | 128 `*`     | 11     | Kassam/Raanes       |
+| Quasi-Geost (QG)     | No  | No    | Yes   | 2d        | 129²≈17k  | ≈140   | Sakov               |
 
 - `*`: Flexible; set as necessary
 - `**`: Tangent Linear Model included?
@@ -248,42 +247,42 @@ Therefore, if you have an *operational* or real-world application,
 such as WRF, you should look into one of the alternatives,
 sorted by approximate project size.
 
-Name               | Developers            | Purpose (approximately)
------------------- | --------------------- | -----------------------------
-[DART][1]          | NCAR                  | General
-[PDAF][7]          | AWI                   | General
-[JEDI][21]         | JCSDA (NOAA, NASA, ++)| General
-[OpenDA][3]        | TU Delft              | General
-[EMPIRE][4]        | Reading (Met)         | General
-[ERT][2]           | Statoil               | History matching (Petroleum DA)
-[PIPT][14]         | CIPR                  | History matching (Petroleum DA)
-[MIKE][9]          | DHI                   | Oceanographic
-[OAK][10]          | Liège                 | Oceanographic
-[Siroco][11]       | OMP                   | Oceanographic
-[Verdandi][6]      | INRIA                 | Biophysical DA
-[PyOSSE][8]        | Edinburgh, Reading    | Earth-observation DA
+| Name               | Developers            | Purpose (approximately)           |
+|--------------------|----------------------|-----------------------------------|
+| [DART][1]          | NCAR                 | General                           |
+| [PDAF][7]          | AWI                  | General                           |
+| [JEDI][21]         | JCSDA (NOAA, NASA, ++)| General                          |
+| [OpenDA][3]        | TU Delft             | General                           |
+| [EMPIRE][4]        | Reading (Met)        | General                           |
+| [ERT][2]           | Statoil              | History matching (Petroleum DA)   |
+| [PIPT][14]         | CIPR                 | History matching (Petroleum DA)   |
+| [MIKE][9]          | DHI                  | Oceanographic                     |
+| [OAK][10]          | Liège                | Oceanographic                     |
+| [Siroco][11]       | OMP                  | Oceanographic                     |
+| [Verdandi][6]      | INRIA                | Biophysical DA                    |
+| [PyOSSE][8]        | Edinburgh, Reading   | Earth-observation DA              |
 
 Below is a list of projects with a purpose more similar to DAPPER's
 (research *in* DA, and not so much *using* DA):
 
-Name                                 | Developers                | Notes
------------------------------------- | ----------------------    | ---------------------------------
-[DAPPER][22]                         | Raanes, Chen, Grudzien    | Python
-[SANGOMA][5]                         | Conglomerate*             | Fortran, Matlab
-[hIPPYlib][25]                       | Villa, Petra, Ghattas     | Python, adjoint-based PDE methods
-[FilterPy][12]                       | R. Labbe                  | Python. Engineering oriented.
-[DASoftware][13]                     | Yue Li, Stanford          | Matlab. Large inverse probs.
-[Pomp][18]                           | U of Michigan             | R
-[EnKF-Matlab][15]                    | Sakov                     | Matlab
-[EnKF-C][17]                         | Sakov                     | C. Light-weight, off-line DA
-[pyda][16]                           | Hickman                   | Python
-[PyDA][19]                           | Shady-Ahmed               | Python
-[DasPy][20]                          | Xujun Han                 | Python
-[DataAssim.jl][23]                   | Alexander-Barth           | Julia
-[DataAssimilationBenchmarks.jl][24]  | Grudzien                  | Julia, Python
-[EnsembleKalmanProcesses.jl][26]     | Clim. Modl. Alliance      | Julia, EKI (optim)
-Datum                                | Raanes                    | Matlab
-IEnKS code                           | Bocquet                   | Python
+| Name                                 | Developers                | Notes                              |
+|--------------------------------------|---------------------------|------------------------------------|
+| [DAPPER][22]                         | Raanes, Chen, Grudzien    | Python                             |
+| [SANGOMA][5]                         | Conglomerate*             | Fortran, Matlab                    |
+| [hIPPYlib][25]                       | Villa, Petra, Ghattas     | Python, adjoint-based PDE methods  |
+| [FilterPy][12]                       | R. Labbe                  | Python. Engineering oriented.      |
+| [DASoftware][13]                     | Yue Li, Stanford          | Matlab. Large inverse probs.       |
+| [Pomp][18]                           | U of Michigan             | R                                  |
+| [EnKF-Matlab][15]                    | Sakov                     | Matlab                             |
+| [EnKF-C][17]                         | Sakov                     | C. Light-weight, off-line DA       |
+| [pyda][16]                           | Hickman                   | Python                             |
+| [PyDA][19]                           | Shady-Ahmed               | Python                             |
+| [DasPy][20]                          | Xujun Han                 | Python                             |
+| [DataAssim.jl][23]                   | Alexander-Barth           | Julia                              |
+| [DataAssimilationBenchmarks.jl][24]  | Grudzien                  | Julia, Python                      |
+| [EnsembleKalmanProcesses.jl][26]     | Clim. Modl. Alliance      | Julia, EKI (optim)                 |
+| Datum                                | Raanes                    | Matlab                             |
+| IEnKS code                           | Bocquet                   | Python                             |
 
 The `EnKF-Matlab` and `IEnKS` codes have been inspirational
 in the development of DAPPER.
@@ -352,11 +351,11 @@ and the Center for Western Weather and Water Extremes (CW3E).
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable line-length -->
-![NORCE](./docs/imgs/norce-logo.png)
-![NERSC](./docs/imgs/nansen-logo.png)
-<img src="https://github.com/nansencenter/DAPPER/blob/master/docs/imgs/UoR-logo.png?raw=true" height="120" />
-<img src="https://github.com/nansencenter/DAPPER/blob/master/docs/imgs/nceologo1000.png?raw=true" height="100">
-<img src="./docs/imgs/CW3E-Logo-Horizontal-FullColor.png?raw=true" width="400">
+![NORCE](https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/norce-logo.png)
+![NERSC](https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/nansen-logo.png)
+<img src="https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/UoR-logo.png?raw=true" alt="University of Reading logo" height="120" />
+<img src="https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/nceologo1000.png?raw=true" alt="NCEO logo" height="100">
+<img src="https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/CW3E-Logo-Horizontal-FullColor.png?raw=true" alt="CW3E logo" width="400">
 <!-- markdownlint-restore -->
 
 ## Publications

dapper-1.7.2/dapper/README.md

@@ -0,0 +1,17 @@
+## Adding your own model/method
+
+If you wish to illustrate and run benchmarks with
+your own **model** or **method**, then
+
+- If it is a complex one, you may be better off using DAPPER
+  merely as *inspiration* (but you can still
+  [cite it](../#getting-started))
+  rather than trying to squeeze everything into its templates.
+- If it is relatively simple, however, you may well want to use DAPPER.
+  In that case, read this:
+    - [`mods`](mods)
+    - [`da_methods`](da_methods)
+
+Since the generality of DAPPER is
+[limited](../#similar-projects)
+it is quite likely you will also need to make changes to the DAPPER code itself.

{dapper-1.7.0 → dapper-1.7.2}/dapper/__init__.py

@@ -1,10 +1,10 @@
 """Root package of **DAPPER**
 (Data Assimilation with Python: a Package for Experimental Research)
 
-.. include:: ./README.md
+--8<-- "dapper/README.md"
 """
 
-__version__ = "1.7.0"
+__version__ = "1.7.2"
 
 # A parsimonious list of imports used in the examples
 from .dpr_config import rc

{dapper-1.7.0 → dapper-1.7.2}/dapper/da_methods/README.md

@@ -1,6 +1,4 @@
-Also see the section on
-[DA Methods](https://github.com/nansencenter/DAPPER#DA-Methods)
-in the main README
+Also see [this section on DA Methods](../../#da-methods)
 for an overview of the methods included with DAPPER.
 
 ## Defining your own method
@@ -8,7 +6,7 @@ for an overview of the methods included with DAPPER.
 Follow the example of one of the methods within one of the
 sub-directories/packages.
 The simplest example is perhaps
-`dapper.da_methods.ensemble.EnKF`.
+[`da_methods.ensemble.EnKF`][].
 
 ## General advice for programming/debugging scientific experiments
 

{dapper-1.7.0 → dapper-1.7.2}/dapper/da_methods/__init__.py

@@ -1,6 +1,6 @@
 """Contains the data assimilation methods included with DAPPER.
 
-.. include:: ./README.md
+--8<-- "dapper/da_methods/README.md"
 """
 
 from pathlib import Path
@@ -16,7 +16,7 @@ def da_method(*default_dataclasses):
     The decorated classes are defined like a `dataclass`,
     but are decorated by `@da_method()` instead of `@dataclass`.
 
-    .. note::
+    !!! note
         The classes must define a method called `assimilate`.
         This method gets slightly enhanced by this wrapper which provides:
 
@@ -25,7 +25,8 @@ def da_method(*default_dataclasses):
         - Duration timing
         - Progressbar naming magic.
 
-    Example:
+    Examples
+    --------
     >>> @da_method()
     ... class Sleeper():
     ...     "Do nothing."
@@ -43,7 +44,6 @@ def da_method(*default_dataclasses):
     which enables defining default parameters which can be inherited,
     similar to subclassing.
 
-    Example:
     >>> class ens_defaults:
     ...     infl : float = 1.0
     ...     rot  : bool  = False
@@ -56,13 +56,13 @@ def da_method(*default_dataclasses):
     ...     def assimilate(self, HMM, xx, yy):
     ...         ...
 
-    .. note::
+    !!! note
         Apart from what's listed in the above `Note`, there is nothing special to the
         resulting `xp`.  That is, just like any Python object, it can serve as a data
         container, and you can write any number of attributes to it (at creation-time,
         or later).  For example, you can set attributes that are not used by the
         `assimilate` method, but are instead used to customize other aspects of the
-        experiments (see `dapper.xp_launch.run_experiment`).
+        experiments (see [`xp_launch.run_experiment`][]).
     """
     import dataclasses
     import functools

{dapper-1.7.0 → dapper-1.7.2}/dapper/da_methods/baseline.py

@@ -1,6 +1,6 @@
 """Unsophisticated" but robust (widely applicable) DA methods.
 
-Many are based on `bib.raanes2016thesis`.
+Many are based on [raanes2016thesis][].
 """
 
 from typing import Callable, Optional
@@ -146,10 +146,15 @@ def fit_sigmoid(Sb, L, kb):
 
     The "normalized" sigmoid, `S1`, is symmetric around 0, and `S1(-∞)=0` and `S1(∞)=1`.
 
-    The sigmoid `S(k) = S1(a*(k-kb) + b)` is fitted (see docs/snippets/sigmoid.jpg) with
+    The sigmoid `S(k) = S1(a*(k-kb) + b)` is fitted with
 
     - `a` corresponding to a given corr. length `L`.
     - `b` to match values of `S(kb)` and `Sb`
+
+    <figure markdown="span">
+        ![](../../images/snippets/sigmoid.jpg){ width="300" }
+        <figcaption>Illustration</figcaption>
+    </figure>
     """
 
     def sigmoid(k):