Merge remote-tracking branch 'origin/master' into joss-paper

Author: lizliz

.github/workflows/publish_to_pypi.yml

@@ -31,7 +31,7 @@ jobs:
           build
           --user
       - name: Install package for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
       - name: Build a binary wheel and a source tarball

.github/workflows/publish_to_test_pypi.yml

@@ -15,6 +15,7 @@ jobs:
     name: Build and publish python distributions to TestPyPI
     runs-on: ubuntu-latest
     concurrency: release
+    if: ${{ github.event.workflow_run.head_branch == 'test_release' }}  # Only run if the first workflow was on the 'test_release' branch
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
       - uses: actions/checkout@master
@@ -31,7 +32,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
       - name: Build a binary wheel and a source tarball

.github/workflows/test_installs.yml

@@ -33,7 +33,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-39-mac:
@@ -55,7 +55,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-39-windows:
@@ -77,7 +77,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-310-ubuntu:
@@ -99,7 +99,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-310-mac:
@@ -121,7 +121,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-310-windows:
@@ -143,7 +143,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-311-ubuntu:
@@ -165,7 +165,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-311-mac:
@@ -187,7 +187,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-311-windows:
@@ -209,7 +209,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-312-ubuntu:
@@ -231,7 +231,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-312-mac:
@@ -253,7 +253,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
   build-312-windows:
@@ -275,7 +275,7 @@ jobs:
           build
           --user
       - name: Install teaspoon for testing
-        run: pip install .
+        run: pip install ".[full]"
       - name: Run tests
         run: make tests
 

MANIFEST.in

@@ -0,0 +1 @@
+include teaspoon/teaspoon/MakeData/DynSysLib/Data/EEG/*.txt

README.md

@@ -21,24 +21,38 @@ The code is a compilation of work done by [Elizabeth Munch](http://www.elizabeth
 
 We gratefully acknowledge the support of the National Science Foundation, which has helped make this work possible.
 
+About TSP
+=========
+
+![The basic pipeline of a TSP project aligned with the modules of teaspoon.](doc_source/figures/tspPipeline.png)
+
+Many topological signal processing projects can be fit into the pipeline shown above; and this pipeline aligns with the five submodules of `teaspoon`. 
+We start with input time series data. In `teaspoon`, the [`MakeData`](https://teaspoontda.github.io/teaspoon/modules/MakeData/index.html) module provides methods for creating synthetic data sets for testing purposes, including the [`DynSysLib`](https://teaspoontda.github.io/teaspoon/modules/MakeData/DynSysLib/index.html) submodule with an extensive array of dynamical systems. 
+The [`ParameterSelection`](https://teaspoontda.github.io/teaspoon/modules/ParamSelection/index.html) modules provides tools for determining best parameters for transforming the time series into a delay coordinate (sometimes called Takens') embedding. This includes standard tools such as false nearest neighbors and mutual information function as well as newly developed tools. The [Signal Processing `SP`](https://teaspoontda.github.io/teaspoon/modules/SP/index.html) module does the conversion from a time series to a topological input. This includes the standard delay coordinate embedding, as well as network representations of time series. This topological input can be converted to a topological signature, in most cases a persistence diagram, using the [Topological Data Analysis `TDA` ](https://teaspoontda.github.io/teaspoon/modules/TDA/index.html) module. Finally, these persistence diagrams can be used in a machine learning pipeline using the vectorization tools from the [Machine Learning `ML`](https://teaspoontda.github.io/teaspoon/modules/ML/index.html) module. 
+
+
 Installation
 =============
 To install this package, both boost and CMake must be installed as system dependencies.  For boost see for [unix](https://www.boost.org/doc/libs/1_66_0/more/getting_started/unix-variants.html) and [windows](https://www.boost.org/doc/libs/1_62_0/more/getting_started/windows.html).  For mac, you can run ``brew install boost`` if using homebrew as a package manager.  For CMake see [here](https://cmake.org/install/).
 
 The teaspoon package is available through pip install with version details found [here](https://pypi.org/project/teaspoon/).
 The package can be installed using the following pip installation:
 
-	``pip install teaspoon``
+```bash
+pip install teaspoon
+```
 
-To install the most up-to-date version of the code, you can clone the repo and then run::
+To install the most up-to-date version of the code, you can clone the repo and then run
 
-  ``pip install .``
+```bash
+pip install .
+```
 
 from the main directory.  Note that the master branch will correspond to the version available in pypi, and the test_release branch may have new features.
 
 Please reference the requirements page in the [documentation](https://teaspoontda.github.io/teaspoon/) for more details on other required installations.
 
 Contacts
 =============
-* Liz Munch: [[email protected]](mailto:[email protected]).
-* Firas Khasawneh: [[email protected]](mailto:[email protected]).
+* Liz Munch: [[email protected]](mailto:[email protected])
+* Firas Khasawneh: [[email protected]](mailto:[email protected])

doc_source/figures/LR_forecast_example.png

@@ -14,8 +14,9 @@ All code is open source with up to date documentation, making the code easy to u
 Table of Contents
 *******************
 
+
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
    :numbered:
 
    Getting Started <installation/index.rst>
@@ -25,6 +26,24 @@ Table of Contents
    License <license.rst>
    Citing <citing.rst>
 
+Modules
+*******
+
+
+.. image:: figures/tspPipeline.png
+   :alt: The basic pipeline of a TSP project aligned with the modules of teaspoon.
+
+Many topological signal processing projects can be fit into the pipeline shown above; and this pipeline aligns with the five submodules of ``teaspoon``. 
+We start with input time series data. In ``teaspoon``, the `MakeData`_ module provides methods for creating synthetic data sets for testing purposes, including the `DynSysLib`_ submodule with an extensive array of dynamical systems. 
+The `ParameterSelection`_ modules provides tools for determining best parameters for transforming the time series into a delay coordinate (sometimes called Takens') embedding. This includes standard tools such as false nearest neighbors and mutual information function as well as newly developed tools. The Signal Processing (`SP`_) module does the conversion from a time series to a topological input. This includes the standard delay coordinate embedding, as well as network representations of time series. This topological input can be converted to a topological signature, in most cases a persistence diagram, using the `TDA`_ module. These persistence diagrams can then be used in a machine learning pipeline using the vectorization tools from the `ML`_ module. Our newest module, Data Assimilation and Forecasting (`DAF`_),provides tools for generating data driven models for dynamical systems and optimally updating the models using persistent homology. 
+
+.. _MakeData: https://teaspoontda.github.io/teaspoon/modules/MakeData/index.html
+.. _DynSysLib: https://teaspoontda.github.io/teaspoon/modules/MakeData/DynSysLib/index.html
+.. _ParameterSelection: https://teaspoontda.github.io/teaspoon/modules/ParamSelection/index.html
+.. _SP: https://teaspoontda.github.io/teaspoon/modules/SP/index.html
+.. _TDA: https://teaspoontda.github.io/teaspoon/modules/TDA/index.html
+.. _ML: https://teaspoontda.github.io/teaspoon/modules/ML/index.html
+.. _DAF: https://teaspoontda.github.io/teaspoon/modules/DAF/index.html
 
 
 Collaborators

doc_source/index.rst

@@ -0,0 +1,81 @@
+
+
+Data Assimilation
+=========================================================
+
+This page gives a summary of the functions available in the data assimilation library. Differentiation of persistence diagrams is exploited to optimize data driven model coefficients by minimizing topological differences between model the model forecast and measurements. More information on the details of the TADA algorithm can be found in,  "`Topological Approach for Data Assimilation <https://arxiv.org/abs/2411.18627>`_." We plan to implement more data assimilation tools here in the future. 
+
+.. warning:: 
+    `TADA` requires `tensorflow <https://www.tensorflow.org>`_ for optimization features. Please install teaspoon using the command: `pip install "teaspoon[full]"` to install the necessary packages. 
+    
+.. automodule:: teaspoon.DAF.data_assimilation
+    :members: 
+
+
+**Example**::
+
+    import numpy as np
+    from teaspoon.MakeData.DynSysLib.autonomous_dissipative_flows import lorenz
+    from teaspoon.DAF.data_assimilation import TADA
+    from teaspoon.DAF.forecasting import forecast_time
+    from teaspoon.DAF.forecasting import random_feature_map_model
+    from teaspoon.DAF.forecasting import get_forecast
+
+    # Set random seed
+    r_seed = 48824
+    np.random.seed(r_seed)
+
+    # Set TADA parameters
+    snr = 60.0
+    lr = 1e-5
+    train_len = 4000
+    forecast_len = 2000
+    window_size = 50
+    max_window_number = 10
+
+    # Get training and validation data at random initial condition
+    ICs = list(np.random.normal(size=(3,1)).reshape(-1,))
+    t, ts = lorenz(L=500, fs=50, SampleSize=6001, parameters=[28,10.0,8.0/3.0],InitialConditions=ICs)
+    ts = np.array(ts) 
+
+    # Get signal and noise amplitudes using signal-to-noise ratio
+    a_sig = np.sqrt(np.mean(np.square(ts),axis=1))
+    a_noise = a_sig * 10**(-snr/20)
+
+    # Add noise to the signal
+    Gamma = np.diag(a_noise)
+    noise = np.random.normal(size=np.shape(ts[:,0:train_len+forecast_len]))
+    u_obs = ts[:,0:train_len+forecast_len] + Gamma@noise
+
+    # Train model
+    W_LR, W_in, b_in = random_feature_map_model(u_obs[:,0:train_len],Dr=300, seed=r_seed)
+
+    # Set optimization parameters
+    d_rate = 0.99
+    opt_params = [lr, d_rate]
+    W_opt = W_LR 
+
+    # TADA optimization loop
+    for window_number in range(1,max_window_number):
+        model_parameters = [W_opt, W_LR, W_in, b_in]  
+        W_opt = TADA(u_obs, window_size, model_parameters, train_len=train_len, n_epochs=1, opt_params=opt_params, window_number=window_number)
+
+    # Set forecast parameters
+    window_number = 200
+    start = train_len
+    end = train_len + window_number + 1
+
+    # Forecast TADA and LR models and get measurements
+    X_model_tada = get_forecast(u_obs[:,train_len], W_opt, W_in, b_in,forecast_len=end-train_len)
+    X_model_lr =get_forecast(u_obs[:,train_len], W_LR, W_in, b_in,forecast_len=end-train_len)
+    X_meas = u_obs[:,start:end]
+
+    # Compute and print forecast times
+    tada_time = forecast_time(X_model_tada, X_meas, dt=0.02, lambda_max=0.91, threshold=0.05)
+    lr_time = forecast_time(X_model_lr, X_meas, dt=0.02, lambda_max=0.91, threshold=0.05)
+
+    print(f"TADA Forecast Time: {tada_time}")
+    print(f"LR Forecast Time: {lr_time}")
+
+.. note:: 
+    Resulting forecast times may vary depending on the operating system.  

doc_source/modules/DAF/DataAssimilation.rst

@@ -0,0 +1,91 @@
+
+
+Forecasting
+=========================================================
+
+This page outlines the available time series forecasting functions. 
+
+
+.. automodule:: teaspoon.DAF.forecasting
+    :members: 
+
+**Example**::
+
+    import numpy as np
+    from matplotlib import rc
+    import matplotlib.pyplot as plt
+    from matplotlib.gridspec import GridSpec
+    from teaspoon.MakeData.DynSysLib.autonomous_dissipative_flows import lorenz
+    from teaspoon.DAF.forecasting import random_feature_map_model
+    from teaspoon.DAF.forecasting import get_forecast
+
+    # Set font
+    rc('font', **{'family': 'sans-serif', 'sans-serif': ['Helvetica']})
+    rc('text', usetex=True)
+    plt.rc('text', usetex=True)
+    plt.rc('font', family='serif')
+    plt.rcParams.update({'font.size': 16})
+
+    # Set model parameters
+    Dr=300
+    train_len = 4000
+    forecast_len = 2000
+
+    r_seed = 48824
+    np.random.seed(r_seed)
+
+    # Get training and tesing data at random initial condition
+    ICs = list(np.random.normal(size=(3,1)).reshape(-1,))
+    t, ts = lorenz(L=500, fs=50, SampleSize=6001, parameters=[28,10.0,8.0/3.0],InitialConditions=ICs)
+    ts = np.array(ts) 
+
+    # Add noise to signals
+    noise = np.random.normal(scale=0.01, size=np.shape(ts[:,0:train_len+forecast_len]))
+    u_obs = ts[:,0:train_len+forecast_len] + noise
+
+    # Train model
+    W_LR, W_in, b_in = random_feature_map_model(u_obs[:,0:train_len],Dr, seed=r_seed)
+
+    # Generate forecast
+    forecast_len = 500
+    X_model= get_forecast(u_obs[:,train_len], W_LR, W_in, b_in,forecast_len=forecast_len)
+    X_meas = u_obs[:,train_len:train_len+forecast_len]
+
+    # Plot measurements and forecast
+    fig = plt.figure(figsize=(15, 5))
+    gs = GridSpec(1, 3)
+    ax1 = fig.add_subplot(gs[0, 0])
+    ax1.plot(X_model[0,:],'r', label="Forecast")  
+    ax1.plot(X_meas[0,:], '.b', label="Measurement")
+    ax1.plot([],[])
+    ax1.set_title('x', fontsize='x-large')
+    ax1.tick_params(axis='both', which='major', labelsize='x-large')
+    ax1.set_ylim((-30,30))
+
+
+    ax2 = fig.add_subplot(gs[0, 1])
+    ax2.plot(X_model[1,:],'r', label="Forecast")  
+    ax2.plot(X_meas[1,:], '.b', label="Measurement")
+    ax2.plot([],[])
+    ax2.set_title('x', fontsize='x-large')
+    ax2.tick_params(axis='both', which='major', labelsize='x-large')
+    ax2.set_ylim((-30,30))
+
+    ax3 = fig.add_subplot(gs[0, 2])
+    ax3.plot(X_model[2,:],'r', label="Forecast")  
+    ax3.plot(X_meas[2,:], '.b', label="Measurement")
+    ax3.plot([],[])
+    ax3.legend(fontsize='large', loc='upper left')
+    ax3.set_title('x', fontsize='x-large')
+    ax3.tick_params(axis='both', which='major', labelsize='x-large')
+    ax3.set_ylim((0,60))
+
+    plt.tight_layout()
+    plt.show()
+
+Output of example
+
+.. figure:: ../../figures/LR_forecast_example.png
+
+.. note::
+    Forecast may vary depending on the operating system.