bayesloop 1.3__tar.gz → 2.0.0__tar.gz

bayesloop-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Christoph Mark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bayesloop-2.0.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: bayesloop
+Version: 2.0.0
+Summary: Grid-based Bayesian modeling for time series with time-varying parameters.
+Author-email: Christoph Mark <christoph.mark@fau.de>
+License-Expression: MIT
+Project-URL: Homepage, http://bayesloop.com
+Project-URL: Repository, https://github.com/christophmark/bayesloop
+Project-URL: Documentation, http://docs.bayesloop.com
+Keywords: bayes,inference,model selection,time series,time-varying,marginal likelihood
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cloudpickle>=2.2
+Requires-Dist: joblib>=1.4
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: sympy>=1.11
+Requires-Dist: tqdm>=4.64
+Provides-Extra: docs
+Requires-Dist: ipykernel; extra == "docs"
+Requires-Dist: ipywidgets; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: pypandoc-binary; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Provides-Extra: speed
+Requires-Dist: numba>=0.65; extra == "speed"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Dynamic: license-file
+
+[![bayesloop](https://raw.githubusercontent.com/christophmark/bayesloop/master/docs/images/logo_400x100px.png)](http://bayesloop.com)
+
+[![Build status](https://github.com/christophmark/bayesloop/workflows/Tests/badge.svg?branch=master)](https://github.com/christophmark/bayesloop/actions/workflows/test.yml)
+[![Documentation status](https://readthedocs.org/projects/bayesloop/badge/?version=latest)](http://docs.bayesloop.com) 
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/41474112.svg)](https://zenodo.org/badge/latestdoi/41474112)
+
+Time series analysis today is an important cornerstone of quantitative science in many disciplines, including natural and life sciences as well as economics and social sciences. Regarding diverse phenomena like tumor cell migration, brain activity and stock trading, a similarity of these complex systems becomes apparent: the observable data we measure – cell migration paths, neuron spike rates and stock prices – are the result of a multitude of underlying processes that act over a broad range of spatial and temporal scales. It is thus to expect that the statistical properties of these systems are not constant, but themselves show stochastic or deterministic dynamics of their own. Time series models used to understand the dynamics of complex systems therefore have to account for temporal changes of the models' parameters.
+
+*bayesloop* is a python module that focuses on fitting time series models with time-varying parameters and model selection based on [Bayesian inference](https://cocosci.berkeley.edu/tom/papers/tutorial.pdf). Instead of relying on [MCMC methods](http://www.cs.ubc.ca/~arnaud/andrieu_defreitas_doucet_jordan_intromontecarlomachinelearning.pdf), *bayesloop* uses a grid-based approach to evaluate probability distributions, allowing for an efficient approximation of the [marginal likelihood (evidence)](http://alumni.media.mit.edu/~tpminka/statlearn/demo/). The marginal likelihood represents a powerful tool to objectively compare different models and/or optimize the hyper-parameters of hierarchical models. To avoid the [curse of dimensionality](https://en.wikipedia.org/wiki/Curse_of_dimensionality) when analyzing time series models with time-varying parameters, *bayesloop* employs a sequential inference algorithm that is based on the [forward-backward-algorithm](https://en.wikipedia.org/wiki/Forward%E2%80%93backward_algorithm) used in [Hidden Markov models](http://www.cs.sjsu.edu/~stamp/RUA/HMM.pdf). Here, the relevant parameter spaces are kept low-dimensional by processing time series data step by step. The module covers a large class of time series models and is easily extensible.
+
+*bayesloop* has been successfully employed in cancer research (studying the migration paths of invasive tumor cells), financial risk assessment, climate research and accident analysis. For a detailed description of these applications, see the following articles:
+
+**Bayesian model selection for complex dynamic systems**<br>
+Mark C., Metzner C., Lautscham L., Strissel P.L., Strick R. and Fabry B.<br>
+[*Nature Communications 9:1803 (2018)*](https://www.nature.com/articles/s41467-018-04241-5)
+
+**Superstatistical analysis and modelling of heterogeneous random walks**<br>
+Metzner C., Mark C., Steinwachs J., Lautscham L., Stadler F. and Fabry B.<br>
+[*Nature Communications 6:7516 (2015)*](https://www.nature.com/articles/ncomms8516)
+
+## Features
+* infer time-varying parameters from time series data 
+* compare hypotheses about parameter dynamics (model evidence)
+* create custom models based on SymPy and SciPy
+* straight-forward handling of missing data points
+* predict future parameter values
+* detect change-points and structural breaks in time series data
+* employ model selection to online data streams
+
+## Getting started
+For a comprehensive introduction and overview of the main features that *bayesloop* provides, see the [documentation](http://docs.bayesloop.com).
+
+The following code provides a minimal example of an analysis carried out using *bayesloop*. The data here consists of the number of coal mining disasters in the UK per year from 1851 to 1962 (see this [article](http://www.dima.unige.it/~riccomag/Teaching/ProcessiStocastici/coal-mining-disaster-original%20paper.pdf) for further information).
+```python
+import bayesloop as bl
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+S = bl.HyperStudy()  # start new data study
+S.load_example_data()  # load data array
+
+# observed number of disasters is modeled by Poisson distribution
+L = bl.om.Poisson('rate')
+
+# disaster rate itself may change gradually over time
+T = bl.tm.GaussianRandomWalk('sigma', bl.cint(0, 1.0, 20), target='rate')
+
+S.set(L, T)
+S.fit()  # inference
+
+# plot data together with inferred parameter evolution
+plt.figure(figsize=(8, 3))
+
+plt.subplot2grid((1, 3), (0, 0), colspan=2)
+plt.xlim([1852, 1961])
+plt.bar(S.raw_timestamps, S.raw_data, align='center', facecolor='r', alpha=.5)
+S.plot('rate')
+plt.xlabel('year')
+
+# plot hyper-parameter distribution
+plt.subplot2grid((1, 3), (0, 2))
+plt.xlim([0, 1])
+S.plot('sigma', facecolor='g', alpha=0.7, lw=1, edgecolor='k')
+plt.tight_layout()
+plt.show()
+```
+
+![Analysis plot](https://raw.githubusercontent.com/christophmark/bayesloop/master/docs/images/example.png)
+
+This analysis indicates a significant improvement of safety conditions between 1880 and 1900. Check out the [documentation](http://docs.bayesloop.com) for further insights!
+
+## Backwards compatibility with bayesloop 1.x
+
+*bayesloop* 2.0 renames the entire API from camelCase to snake_case (e.g. `S.loadData(...)` becomes `S.load_data(...)`). Existing 1.x scripts can still be run without modification by importing the opt-in compatibility layer once, right after importing *bayesloop*:
+
+```python
+import bayesloop as bl
+import bayesloop.v1compat  # activates the 1.x API
+
+S = bl.HyperStudy()
+S.loadExampleData()  # 1.x method names work again
+```
+
+The compatibility layer restores:
+- all camelCase method, attribute and property names (`loadData`, `getParameterDistribution`, `logEvidence`, ...), including the 1.x shorthand aliases (`setOM`, `setTM`, `getPD`, ...)
+- camelCase keyword arguments (`forwardOnly`, `nJobs`, `storeHistory`, ...)
+- the 1.x module names `bayesloop.observationModels`, `bayesloop.transitionModels` and `bayesloop.fileIO`
+- custom observation/transition models that implement 1.x hooks (`computeForwardPrior`, `estimateParameterValues`, ...)
+- loading study files saved with *bayesloop* 1.x via `bl.load(...)` (attribute names are migrated on load)
+
+Every use of a 1.x name emits a `DeprecationWarning` that points to its snake_case replacement, so the layer doubles as a migration guide. Two things are **not** covered: the probability `Parser` and `Study.eval()` were removed in 2.0, and the default parameter names of some transition models changed (`'tChange'` → `'t_change'`, `'tBreak'` → `'t_break'`, `'log10pMin'` → `'log10p_min'`) — scripts that rely on these default names should pass the names explicitly.
+
+## Installation
+The easiest way to install the latest release version of *bayesloop* is via `pip`:
+```
+pip install bayesloop
+```
+Alternatively, a zipped version can be downloaded [here](https://github.com/christophmark/bayesloop/releases). The module is installed by calling `python -m pip install .` from the project root.
+
+### Development version
+The latest development version of *bayesloop* can be installed from the `v2` branch using pip (requires git):
+```
+pip install git+https://github.com/christophmark/bayesloop@v2
+```
+Alternatively, clone the repository and install it in editable mode:
+```
+python -m pip install -e ".[test]"
+```
+
+## Dependencies
+*bayesloop* v2 supports Python 3.10 and newer. It depends on NumPy, SciPy, SymPy, matplotlib, tqdm, cloudpickle and joblib. Parallel computation for expensive `HyperStudy` and `ChangepointStudy` analyses is available with a normal install via `fit(n_jobs=...)`.
+
+## License
+[The MIT License (MIT)](https://github.com/christophmark/bayesloop/blob/master/LICENSE)
+
+If you have any further questions, suggestions or comments, do not hesitate to contact me: &#098;&#097;&#121;&#101;&#115;&#108;&#111;&#111;&#112;&#064;&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109;

bayesloop-2.0.0/README.md

@@ -0,0 +1,117 @@
+[![bayesloop](https://raw.githubusercontent.com/christophmark/bayesloop/master/docs/images/logo_400x100px.png)](http://bayesloop.com)
+
+[![Build status](https://github.com/christophmark/bayesloop/workflows/Tests/badge.svg?branch=master)](https://github.com/christophmark/bayesloop/actions/workflows/test.yml)
+[![Documentation status](https://readthedocs.org/projects/bayesloop/badge/?version=latest)](http://docs.bayesloop.com) 
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/41474112.svg)](https://zenodo.org/badge/latestdoi/41474112)
+
+Time series analysis today is an important cornerstone of quantitative science in many disciplines, including natural and life sciences as well as economics and social sciences. Regarding diverse phenomena like tumor cell migration, brain activity and stock trading, a similarity of these complex systems becomes apparent: the observable data we measure – cell migration paths, neuron spike rates and stock prices – are the result of a multitude of underlying processes that act over a broad range of spatial and temporal scales. It is thus to expect that the statistical properties of these systems are not constant, but themselves show stochastic or deterministic dynamics of their own. Time series models used to understand the dynamics of complex systems therefore have to account for temporal changes of the models' parameters.
+
+*bayesloop* is a python module that focuses on fitting time series models with time-varying parameters and model selection based on [Bayesian inference](https://cocosci.berkeley.edu/tom/papers/tutorial.pdf). Instead of relying on [MCMC methods](http://www.cs.ubc.ca/~arnaud/andrieu_defreitas_doucet_jordan_intromontecarlomachinelearning.pdf), *bayesloop* uses a grid-based approach to evaluate probability distributions, allowing for an efficient approximation of the [marginal likelihood (evidence)](http://alumni.media.mit.edu/~tpminka/statlearn/demo/). The marginal likelihood represents a powerful tool to objectively compare different models and/or optimize the hyper-parameters of hierarchical models. To avoid the [curse of dimensionality](https://en.wikipedia.org/wiki/Curse_of_dimensionality) when analyzing time series models with time-varying parameters, *bayesloop* employs a sequential inference algorithm that is based on the [forward-backward-algorithm](https://en.wikipedia.org/wiki/Forward%E2%80%93backward_algorithm) used in [Hidden Markov models](http://www.cs.sjsu.edu/~stamp/RUA/HMM.pdf). Here, the relevant parameter spaces are kept low-dimensional by processing time series data step by step. The module covers a large class of time series models and is easily extensible.
+
+*bayesloop* has been successfully employed in cancer research (studying the migration paths of invasive tumor cells), financial risk assessment, climate research and accident analysis. For a detailed description of these applications, see the following articles:
+
+**Bayesian model selection for complex dynamic systems**<br>
+Mark C., Metzner C., Lautscham L., Strissel P.L., Strick R. and Fabry B.<br>
+[*Nature Communications 9:1803 (2018)*](https://www.nature.com/articles/s41467-018-04241-5)
+
+**Superstatistical analysis and modelling of heterogeneous random walks**<br>
+Metzner C., Mark C., Steinwachs J., Lautscham L., Stadler F. and Fabry B.<br>
+[*Nature Communications 6:7516 (2015)*](https://www.nature.com/articles/ncomms8516)
+
+## Features
+* infer time-varying parameters from time series data 
+* compare hypotheses about parameter dynamics (model evidence)
+* create custom models based on SymPy and SciPy
+* straight-forward handling of missing data points
+* predict future parameter values
+* detect change-points and structural breaks in time series data
+* employ model selection to online data streams
+
+## Getting started
+For a comprehensive introduction and overview of the main features that *bayesloop* provides, see the [documentation](http://docs.bayesloop.com).
+
+The following code provides a minimal example of an analysis carried out using *bayesloop*. The data here consists of the number of coal mining disasters in the UK per year from 1851 to 1962 (see this [article](http://www.dima.unige.it/~riccomag/Teaching/ProcessiStocastici/coal-mining-disaster-original%20paper.pdf) for further information).
+```python
+import bayesloop as bl
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+S = bl.HyperStudy()  # start new data study
+S.load_example_data()  # load data array
+
+# observed number of disasters is modeled by Poisson distribution
+L = bl.om.Poisson('rate')
+
+# disaster rate itself may change gradually over time
+T = bl.tm.GaussianRandomWalk('sigma', bl.cint(0, 1.0, 20), target='rate')
+
+S.set(L, T)
+S.fit()  # inference
+
+# plot data together with inferred parameter evolution
+plt.figure(figsize=(8, 3))
+
+plt.subplot2grid((1, 3), (0, 0), colspan=2)
+plt.xlim([1852, 1961])
+plt.bar(S.raw_timestamps, S.raw_data, align='center', facecolor='r', alpha=.5)
+S.plot('rate')
+plt.xlabel('year')
+
+# plot hyper-parameter distribution
+plt.subplot2grid((1, 3), (0, 2))
+plt.xlim([0, 1])
+S.plot('sigma', facecolor='g', alpha=0.7, lw=1, edgecolor='k')
+plt.tight_layout()
+plt.show()
+```
+
+![Analysis plot](https://raw.githubusercontent.com/christophmark/bayesloop/master/docs/images/example.png)
+
+This analysis indicates a significant improvement of safety conditions between 1880 and 1900. Check out the [documentation](http://docs.bayesloop.com) for further insights!
+
+## Backwards compatibility with bayesloop 1.x
+
+*bayesloop* 2.0 renames the entire API from camelCase to snake_case (e.g. `S.loadData(...)` becomes `S.load_data(...)`). Existing 1.x scripts can still be run without modification by importing the opt-in compatibility layer once, right after importing *bayesloop*:
+
+```python
+import bayesloop as bl
+import bayesloop.v1compat  # activates the 1.x API
+
+S = bl.HyperStudy()
+S.loadExampleData()  # 1.x method names work again
+```
+
+The compatibility layer restores:
+- all camelCase method, attribute and property names (`loadData`, `getParameterDistribution`, `logEvidence`, ...), including the 1.x shorthand aliases (`setOM`, `setTM`, `getPD`, ...)
+- camelCase keyword arguments (`forwardOnly`, `nJobs`, `storeHistory`, ...)
+- the 1.x module names `bayesloop.observationModels`, `bayesloop.transitionModels` and `bayesloop.fileIO`
+- custom observation/transition models that implement 1.x hooks (`computeForwardPrior`, `estimateParameterValues`, ...)
+- loading study files saved with *bayesloop* 1.x via `bl.load(...)` (attribute names are migrated on load)
+
+Every use of a 1.x name emits a `DeprecationWarning` that points to its snake_case replacement, so the layer doubles as a migration guide. Two things are **not** covered: the probability `Parser` and `Study.eval()` were removed in 2.0, and the default parameter names of some transition models changed (`'tChange'` → `'t_change'`, `'tBreak'` → `'t_break'`, `'log10pMin'` → `'log10p_min'`) — scripts that rely on these default names should pass the names explicitly.
+
+## Installation
+The easiest way to install the latest release version of *bayesloop* is via `pip`:
+```
+pip install bayesloop
+```
+Alternatively, a zipped version can be downloaded [here](https://github.com/christophmark/bayesloop/releases). The module is installed by calling `python -m pip install .` from the project root.
+
+### Development version
+The latest development version of *bayesloop* can be installed from the `v2` branch using pip (requires git):
+```
+pip install git+https://github.com/christophmark/bayesloop@v2
+```
+Alternatively, clone the repository and install it in editable mode:
+```
+python -m pip install -e ".[test]"
+```
+
+## Dependencies
+*bayesloop* v2 supports Python 3.10 and newer. It depends on NumPy, SciPy, SymPy, matplotlib, tqdm, cloudpickle and joblib. Parallel computation for expensive `HyperStudy` and `ChangepointStudy` analyses is available with a normal install via `fit(n_jobs=...)`.
+
+## License
+[The MIT License (MIT)](https://github.com/christophmark/bayesloop/blob/master/LICENSE)
+
+If you have any further questions, suggestions or comments, do not hesitate to contact me: &#098;&#097;&#121;&#101;&#115;&#108;&#111;&#111;&#112;&#064;&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109;

bayesloop-2.0.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bayesloop"
+version = "2.0.0"
+description = "Grid-based Bayesian modeling for time series with time-varying parameters."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Christoph Mark", email = "christoph.mark@fau.de" },
+]
+keywords = [
+    "bayes",
+    "inference",
+    "model selection",
+    "time series",
+    "time-varying",
+    "marginal likelihood",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "cloudpickle>=2.2",
+    "joblib>=1.4",
+    "matplotlib>=3.7",
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "sympy>=1.11",
+    "tqdm>=4.64",
+]
+
+[project.optional-dependencies]
+docs = [
+    "ipykernel",
+    "ipywidgets",
+    "nbsphinx",
+    "pypandoc-binary",
+    "sphinx",
+    "sphinx-rtd-theme",
+]
+speed = [
+    "numba>=0.65",
+]
+test = [
+    "pytest>=8",
+    "pytest-cov>=5",
+]
+
+[project.urls]
+Homepage = "http://bayesloop.com"
+Repository = "https://github.com/christophmark/bayesloop"
+Documentation = "http://docs.bayesloop.com"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.coverage.run]
+source = ["bayesloop"]

bayesloop-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bayesloop-2.0.0/src/bayesloop/__init__.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python
+
+# import study types
+from .core import Study, HyperStudy, ChangepointStudy, OnlineStudy
+
+# observation models and transition models need to be distinguishable
+from . import observation_models
+from . import observation_models as om  # short form
+from . import transition_models
+from . import transition_models as tm  # short form
+
+# misc
+from .helper import cint, oint
+from .jeffreys import get_jeffreys_prior, compute_jeffreys_prior_ar1
+from .file_io import save, load
+
+__all__ = [
+    "Study",
+    "HyperStudy",
+    "ChangepointStudy",
+    "OnlineStudy",
+    "observation_models",
+    "transition_models",
+    "om",
+    "tm",
+    "cint",
+    "oint",
+    "get_jeffreys_prior",
+    "compute_jeffreys_prior_ar1",
+    "save",
+    "load",
+]