dapper 1.3.0__tar.gz → 1.5.0__tar.gz

{dapper-1.3.0 → dapper-1.5.0}/PKG-INFO

@@ -1,33 +1,29 @@
 Metadata-Version: 2.1
 Name: dapper
-Version: 1.3.0
+Version: 1.5.0
 Summary: DAPPER benchmarks the performance of data assimilation (DA) methods.
-Home-page: UNKNOWN
 Author: Patrick N. Raanes
 Author-email: patrick.n.raanes@gmail.com
-License: UNKNOWN
 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
-Platform: UNKNOWN
 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.7
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Provides-Extra: Qt
-Provides-Extra: dev
+Provides-Extra: debug
 Provides-Extra: test
 Provides-Extra: lint
 Provides-Extra: build
+Provides-Extra: dev
 License-File: LICENCE.txt
 
 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.3.0 → dapper-1.5.0}/README.md

@@ -20,7 +20,7 @@ and use these to generate a synthetic truth (multivariate time series),
 and then estimate that truth given the models and noisy observations.
 
 <!-- Badges / shields -->
-[![Github CI](https://img.shields.io/github/workflow/status/nansencenter/DAPPER/superintendent?logo=github&style=for-the-badge)](https://github.com/nansencenter/DAPPER/actions)
+[![Github CI](https://img.shields.io/github/actions/workflow/status/nansencenter/DAPPER/tests.yml?branch=master&logo=github&style=for-the-badge)](https://github.com/nansencenter/DAPPER/actions)
 [![Coveralls](https://img.shields.io/coveralls/github/nansencenter/DAPPER?style=for-the-badge&logo=coveralls)](https://coveralls.io/github/nansencenter/DAPPER?branch=master)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?style=for-the-badge&logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
 [![PyPI - Version](https://img.shields.io/pypi/v/dapper.svg?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.python.org/pypi/dapper/)
@@ -28,7 +28,7 @@ and then estimate that truth given the models and noisy observations.
 
 ## Getting started
 
-[Install](#Installation), then
+[Install](#installation), then
 read, run and try to understand `examples/basic_{1,2,3}.py`.
 Some of the examples can also be opened in Jupyter, and thereby run in the cloud
 (i.e. *without installation*, but requiring Google login): [![Open In Collab](https://colab.research.google.com/assets/colab-badge.svg)](http://colab.research.google.com/github/nansencenter/DAPPER).
@@ -46,35 +46,52 @@ see these [tutorials](https://github.com/nansencenter/DA-tutorials).
 
 ## Highlights
 
-DAPPER enables the numerical investigation of [DA methods](#DA-methods)
-through a variety of typical [test cases](#Test-cases-models) and statistics. It
+DAPPER enables the numerical investigation of [DA methods](#da-methods)
+through a variety of typical [test cases](#test-cases-models) and statistics. It
 (a) reproduces numerical benchmarks results reported in the literature, and
 (b) facilitates comparative studies, thus promoting the
 (a) reliability and
 (b) relevance of the results.
-For example, this figure is generated by `examples/basic_3.py` and is a
-reproduction of figure 5.7 of [these lecture notes](http://cerea.enpc.fr/HomePages/bocquet/teaching/assim-mb-en.pdf).
+For example, this figure is generated by `examples/basic_3.py`,
+making use of built-in tools for experiment and result management,
+reproduces figure 5.7 of [these lecture notes](http://cerea.enpc.fr/HomePages/bocquet/teaching/assim-mb-en.pdf).
 
 ![Comparative benchmarks with Lorenz'96 plotted as a function of the ensemble size (N)](./docs/imgs/ex3.svg)
 
 DAPPER is (c) open source, written in Python, and (d) focuses on readability;
 this promotes the (c) reproduction and (d) dissemination of the underlying science,
 and makes it easy to adapt and extend.
-It also comes with a battery of diagnostics and statistics,
-and live plotting (on-line with the assimilation) facilities,
-including pause/inspect options, as illustrated below
+
+It also illustrates 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`).
+It comes with a battery of diagnostics and statistics.
+These all get averaged over subdomains (e..g "ocean" and "land") and then in time.
+Confidence intervals are computed, including correction for auto-correlations,
+and used for uncertainty quantification, and significant digits printing.
+Several diagnostics are included in the on-line "liveplotting" illustrated below,
+which may be paused for further interactive inspection.
 
 ![EnKF - Lorenz'63](./docs/imgs/ex1.jpg)
 
-In summary, it is well suited for teaching and fundamental DA research.
+<!-- Non-highlighted features:
+- Time sequences use via `tools.chronos.Chronology` and `tools.chronos.Ticker`.
+- Random variables via `tools.randvars.RV`: Gaussian, Student-t, Laplace, Uniform,
+  ..., as well as support for custom sampling functions.
+- Covariance matrices via `tools.matrices.CovMat`:
+  provides input flexibility/overloading,
+  lazy eval that facilitates the use of non-diagonal
+  covariance matrices (whether sparse or full).
+-->
+
+In summary, DAPPER is well suited for teaching and fundamental DA research.
 Also see its [drawbacks](#similar-projects).
 
 
 ## Installation
 
-Works on Linux/Windows/Mac.
+Successfully tested on Linux/Mac/Windows.
 
-### Prerequisite: Python>=3.7
+### Prerequisite: Python>=3.9
 
 If you're an expert, setup a python environment however you like.
 Otherwise:
@@ -83,12 +100,12 @@ open the [Anaconda terminal](https://docs.conda.io/projects/conda/en/latest/user
 and run the following commands:
 
 ```sh
-conda create --yes --name dapper-env python=3.8
+conda create --yes --name dapper-env python=3.9
 conda activate dapper-env
 python --version
 ```
 
-Ensure the printed version is 3.7 or more.  
+Ensure the printed version is 3.9 or more.  
 *Keep using the same terminal for the commands below.*
 
 ### Install
@@ -101,7 +118,7 @@ Ensure the printed version is 3.7 or more.
 - Move the resulting folder wherever you like,  
   and `cd` into it
   *(ensure you're in the folder with a `setup.py` file)*.
-- `pip install -e .[dev]`  
+- `pip install -e '.[dev]'`  
   You can omit `[dev]` if you don't need to do serious development.
 
 #### *Or*: Install as library
@@ -170,6 +187,7 @@ grep -r "xp.*iEnKS" dapper/mods
 
 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
@@ -205,7 +223,7 @@ Some files contain settings used by several papers.
 Moreover, at the bottom of each such file should be (in comments)
 a list of suitable, tuned settings for various DA methods,
 along with their expected, average `rmse.a` score for that experiment.
-As mentioned [above](#DA-methods), DAPPER reproduces literature results.
+As mentioned [above](#da-methods), DAPPER reproduces literature results.
 You will also find results that were not reproduced by DAPPER.
 
 
@@ -216,7 +234,7 @@ Example of limitations:
 
 - It is not suited for very big models (>60k unknowns).
 - Time-dependent error covariances and changes in lengths of state/obs
-  (although the Dyn and Obs models may otherwise be time-dependent).
+  (although the `Dyn` and `Obs` models may otherwise be time-dependent).
 - Non-uniform time sequences not fully supported.
 
 The scope of DAPPER is restricted because
@@ -251,23 +269,24 @@ Name               | Developers            | Purpose (approximately)
 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
-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.
@@ -294,11 +313,12 @@ in the development of DAPPER.
 [18]: https://github.com/kingaa/pomp
 [19]: https://github.com/Shady-Ahmed/PyDA
 [20]: https://github.com/daspy/daspy
-[21]: https://www.jcsda.noaa.gov/index.php
+[21]: https://jointcenterforsatellitedataassimilation-jedi-docs.readthedocs-hosted.com/en/latest/
 [22]: https://github.com/nansencenter/DAPPER
 [23]: https://juliahub.com/docs/DataAssim/qCDwD/0.3.2/
 [24]: https://github.com/cgrudz/DataAssimilationBenchmarks.jl
 [25]: https://hippylib.github.io/
+[26]: https://github.com/CliMA/EnsembleKalmanProcesses.jl
 
 
 ## Contributors
@@ -314,24 +334,24 @@ NORCE (Norwegian Research Institute)
 and the Nansen Environmental and Remote Sensing Center (NERSC),
 in collaboration with the University of Reading,
 the UK National Centre for Earth Observation (NCEO),
-and the University of Nevada, Reno.
+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="140" />
-<img src="https://github.com/nansencenter/DAPPER/blob/master/docs/imgs/nceologo1000.png?raw=true" width="400">
-<img src="./docs/imgs/UNR_logo.png?raw=true" width="400">
+<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">
 <!-- markdownlint-restore -->
 
 ## Publication list
 
-- <https://www.geosci-model-dev-discuss.net/gmd-2019-136/>
-- <https://rmets.onlinelibrary.wiley.com/doi/abs/10.1002/qj.3386>
-- <https://www.nonlin-processes-geophys-discuss.net/npg-2019-10>
-- <https://link.springer.com/article/10.1007/s11004-021-09937-x>
-- <https://arxiv.org/abs/2010.07063>
+- [Combining data assimilation and machine learning to emulate a dynamical model from sparse and noisy observations: A case study with the Lorenz 96 model](https://doi.org/10.1016/j.jocs.2020.101171)
+- [Adaptive covariance inflation in the ensemble Kalman filter by Gaussian scale mixtures](https://doi.org/10.1002/qj.3386)
+- [Revising the stochastic iterative ensemble smoother](https://doi.org/10.5194/npg-26-325-2019)
+- [p-Kernel Stein Variational Gradient Descent for Data Assimilation and History Matching](https://doi.org/10.1007/s11004-021-09937-x)
+- [Springer book chapter: Data Assimilation for Chaotic Dynamics](https://doi.org/10.1007/978-3-030-77722-7_1)
 
 
 <!-- markdownlint-configure-file

dapper-1.5.0/dapper/README.md

@@ -0,0 +1,43 @@
+## API reference
+
+Click the links in the navigation menu to view
+the docs for the various modules.
+
+## Installation
+
+See [README/Installation](https://github.com/nansencenter/DAPPER#Installation)
+
+## Usage
+
+See [README/Getting-started](https://github.com/nansencenter/DAPPER#Getting-started)
+
+##### Examples
+
+See [examples/README](https://github.com/nansencenter/DAPPER/tree/master/examples)
+
+##### 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](https://github.com/nansencenter/DAPPER#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`
+    - `da_methods`
+
+Since the generality of DAPPER is
+[limited](https://github.com/nansencenter/DAPPER#similar-projects)
+it is quite likely you will also need to make changes to the DAPPER code itself.
+
+## Developer guide
+
+If you are making a pull request, please read the [developer guide](dev_guide).
+
+## Bibliography
+
+Click the various citations/references (e.g. `bib.anderson2010non`)
+to access the [bibliography](bib).

dapper-1.5.0/dapper/__init__.py

@@ -0,0 +1,15 @@
+"""Root package of **DAPPER**
+(Data Assimilation with Python: a Package for Experimental Research)
+
+.. include:: ./README.md
+"""
+
+__version__ = "1.5.0"
+
+# A parsimonious list of imports used in the examples
+from .dpr_config import rc
+from .tools.datafiles import find_latest_run, load_xps
+from .tools.rounding import round2sigfig
+from .tools.seeding import set_seed
+from .xp_launch import combinator, seed_and_simulate, xpList
+from .xp_process import xpSpace

{dapper-1.3.0 → dapper-1.5.0}/dapper/da_methods/__init__.py

@@ -2,15 +2,7 @@
 
 .. include:: ./README.md
 """
-import dataclasses
-import functools
-import inspect
-import sys
-import time
-import traceback
-from dataclasses import dataclass
-
-import dapper.stats
+from pathlib import Path
 
 
 def da_method(*default_dataclasses):
@@ -63,7 +55,7 @@ def da_method(*default_dataclasses):
     ...     def assimilate(self, HMM, xx, yy):
     ...         ...
 
-    .. hint::
+    .. 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,
@@ -71,6 +63,12 @@ def da_method(*default_dataclasses):
         `assimilate` method, but are instead used to customize other aspects of the
         experiments (see `dapper.xp_launch.run_experiment`).
     """
+    import dataclasses
+    import functools
+    import time
+    from dataclasses import dataclass
+
+    import dapper.stats
 
     def dataclass_with_defaults(cls):
         """Like `dataclass`, but add some DAPPER-specific things.
@@ -147,6 +145,9 @@ def da_method(*default_dataclasses):
 
 
 def _print_cropped_traceback(ERR):
+    import inspect
+    import sys
+    import traceback
 
     # A more "standard" (robust) way:
     # https://stackoverflow.com/a/32999522
@@ -181,7 +182,16 @@ def _print_cropped_traceback(ERR):
     print(msg, file=sys.stderr)
 
 
-from .baseline import Climatology, OptInterp, Var3D
+# Import all da_methods
+# for _mod in Path(__file__).parent.glob("*.py"):
+#     if _mod != Path(__file__) and not _mod.stem.startswith("_"):
+#         _mod = __import__(__package__ + "." + _mod.stem, fromlist=['*'])
+#         del globals()[_mod.__name__.split(".")[-1]]  # rm module itself
+#         globals().update({k: v for k, v in vars(_mod).items()
+#                           if isinstance(v, type) and hasattr(v, "da_method")})
+
+# The above does not allow for go-to-definition, so
+from .baseline import Climatology, OptInterp, Persistence, PreProg, Var3D
 from .ensemble import LETKF, SL_EAKF, EnKF, EnKF_N, EnKS, EnRTS
 from .extended import ExtKF, ExtRTS
 from .other import LNETF, RHF

{dapper-1.3.0 → dapper-1.5.0}/dapper/da_methods/baseline.py

@@ -2,7 +2,7 @@
 
 Many are based on `bib.raanes2016thesis`.
 """
-from typing import Optional
+from typing import Callable, Optional
 
 import numpy as np
 
@@ -138,17 +138,17 @@ def fit_sigmoid(Sb, L, kb):
     """Return a sigmoid [function S(k)] for approximating error dynamics.
 
     We use the logistic function for the sigmoid; it's the solution of the
-    "population growth" ODE: dS/dt = a*S*(1-S/S(∞)).
+    "population growth" ODE: `dS/dt = a*S*(1-S/S(∞))`.
     NB: It might be better to use the "error growth ODE" of Lorenz/Dalcher/Kalnay,
     but this has a significantly more complicated closed-form solution,
     and reduces to the above ODE when there's no model error (ODE source term).
 
-    The "normalized" sigmoid, S1, is symmetric around 0, and S1(-∞)=0 and S1(∞)=1.
+    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 (see docs/snippets/sigmoid.jpg) with
 
-    - a corresponding to a given corr. length L.
-    - b to match values of S(kb) and Sb
+    - `a` corresponding to a given corr. length `L`.
+    - `b` to match values of `S(kb)` and `Sb`
     """
 
     def sigmoid(k): return 1/(1+np.exp(-k))  # normalized sigmoid
@@ -164,10 +164,38 @@ def fit_sigmoid(Sb, L, kb):
 
 
 @da_method()
-class EnCheat:
-    """A baseline/reference method.
+class Persistence:
+    """Sets estimate to the **true state** at the previous time index.
+
+    The analysis (`.a`) stat uses the previous obs. time.
+    The forecast and universal (`.f` and `.u`) stats use previous integration time
+    index.
+    """
+
+    def assimilate(self, HMM, xx, yy):
+        prev = xx[0]
+        self.stats.assess(0, mu=prev)
+        for k, ko, _t, _dt in progbar(HMM.tseq.ticker):
+            self.stats.assess(k, ko, 'fu', mu=xx[k-1])
+            if ko is not None:
+                self.stats.assess(k, ko, 'a', mu=prev)
+                prev = xx[k]
 
-    Should be implemented as part of Stats instead.
+
+@da_method()
+class PreProg:
+    """Simply look-up the estimates in user-specified function (`schedule`).
+
+    For example, with `schedule` given by `lambda k, xx, yy: xx[k]`
+    the error (`err.rms, err.ma, ...`) should be 0.
     """
 
-    def assimilate(self, HMM, xx, yy): pass
+    schedule: Callable
+    tag: str = None
+
+    def assimilate(self, HMM, xx, yy):
+        self.stats.assess(0, mu=self.schedule(0, xx, yy))
+        for k, ko, _t, _dt in progbar(HMM.tseq.ticker):
+            self.stats.assess(k, ko, 'fu', mu=self.schedule(k, xx, yy))
+            if ko is not None:
+                self.stats.assess(k, ko, 'a', mu=self.schedule(k, xx, yy))