pyCLINE 0.1.7__tar.gz

pycline-0.1.7/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025, Bartosz Prokop, Nikita Frolov, Lendert Gelens
+Laboratory of Dynamics in Biological Systems (DiBS/Gelens lab)
+Department of Cellular and Mollecular Medicine, KU Leuven
+
+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.

pycline-0.1.7/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.2
+Name: pyCLINE
+Version: 0.1.7
+Summary: This package is the python implementation of the CLINE method introduced by Prokop, Billen, Frolov, Gelens (2025).
+Author-email: Bartosz Prokop <bartosz.prokop@kuleuven.be>, Nikita Frolov <nikita.frolov@kuleuven.be>, Lendert Gelens <lendert.gelens@kuleuven.be>
+Project-URL: Homepage, https://pycline-ec8369.pages.gitlab.kuleuven.be/
+Project-URL: Issues, https://gitlab.kuleuven.be/gelenslab/publications/pycline/-/issues
+Keywords: model,model identification,nullcline,data-driven,machine learning,deep learning,torch,dynamics,oscillator,nonlinear dynamics,complex systems
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.6.2
+Requires-Dist: numpy<1.25.0,>=1.24.1
+Requires-Dist: pandas~=1.5.2
+Requires-Dist: torch>=2.4.1
+Requires-Dist: tqdm>=4.66.1
+Requires-Dist: jitcdde>=1.8.1
+Requires-Dist: scipy>=1.9.3
+
+# PyCLINE - python package for CLINE
+
+The `pyCLINE` package is the python package based on the CLINE (**C**omputational **L**earning and **I**dentification of **N**ullclin**E**s).
+It can be downloaded from PyPI with pip by using
+    
+    pip install pyCLINE
+
+The package allows to recreate all data, models and results shown in XXX, and to apply CLINE to other data sets. 
+In order to generate data used in XXX, a set of different models is being provided under `pyCLINE.model`. 
+Data from these models can be generated using `pyCLINE.generate_data()`.
+For setting up the data prepartion and adjacent training a neural network, the submodule `pyCLINE.recovery_methods` is used. 
+The submodule contains the module for data_preparation `pyCLINE.recovery_methods.data_preparation` and for neural network training `pyCLINE.recovery_methods.nn_training`. 
+
+For a better understanding, `pyCLINE` also contains the module `pyCLINE.example` which provides four example also found in XXX with step by step instructions on how to setup a CLINE pipeline. 
+
+The structure of `pyCLINE` is shown here: 
+
+![PyCLINE structure](pycline_structure.png)

pycline-0.1.7/README.md

@@ -0,0 +1,18 @@
+# PyCLINE - python package for CLINE
+
+The `pyCLINE` package is the python package based on the CLINE (**C**omputational **L**earning and **I**dentification of **N**ullclin**E**s).
+It can be downloaded from PyPI with pip by using
+    
+    pip install pyCLINE
+
+The package allows to recreate all data, models and results shown in XXX, and to apply CLINE to other data sets. 
+In order to generate data used in XXX, a set of different models is being provided under `pyCLINE.model`. 
+Data from these models can be generated using `pyCLINE.generate_data()`.
+For setting up the data prepartion and adjacent training a neural network, the submodule `pyCLINE.recovery_methods` is used. 
+The submodule contains the module for data_preparation `pyCLINE.recovery_methods.data_preparation` and for neural network training `pyCLINE.recovery_methods.nn_training`. 
+
+For a better understanding, `pyCLINE` also contains the module `pyCLINE.example` which provides four example also found in XXX with step by step instructions on how to setup a CLINE pipeline. 
+
+The structure of `pyCLINE` is shown here: 
+
+![PyCLINE structure](pycline_structure.png)

pycline-0.1.7/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = [ "setuptools>=61.0",]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyCLINE"
+version = "0.1.7"
+description = "This package is the python implementation of the CLINE method introduced by Prokop, Billen, Frolov, Gelens (2025)."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [ "Development Status :: 3 - Alpha", "Programming Language :: Python :: 3", "Operating System :: OS Independent",]
+keywords = [ "model", "model identification", "nullcline", "data-driven", "machine learning", "deep learning", "torch", "dynamics", "oscillator", "nonlinear dynamics", "complex systems",]
+dependencies = [ "matplotlib>=3.6.2", "numpy>=1.24.1,<1.25.0", "pandas~=1.5.2", "torch>=2.4.1", "tqdm>=4.66.1", "jitcdde>=1.8.1", "scipy>=1.9.3",]
+[[project.authors]]
+name = "Bartosz Prokop"
+email = "bartosz.prokop@kuleuven.be"
+
+[[project.authors]]
+name = "Nikita Frolov"
+email = "nikita.frolov@kuleuven.be"
+
+[[project.authors]]
+name = "Lendert Gelens"
+email = "lendert.gelens@kuleuven.be"
+
+[project.license]
+file = "LICEN[CS]E*"
+
+[project.urls]
+Homepage = "https://pycline-ec8369.pages.gitlab.kuleuven.be/"
+Issues = "https://gitlab.kuleuven.be/gelenslab/publications/pycline/-/issues"

pycline-0.1.7/setup.cfg

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

pycline-0.1.7/src/pyCLINE/__init__.py

@@ -0,0 +1,22 @@
+"""
+pyCLINE: Python implementation of the CLINE method introduced by Prokop, Billen, Frolov and Gelens (2025).
+
+Modules:
+    recovery_methods: Methods for recovering nullclines.
+    model: Model definitions and utilities.
+    generate_data: Functions for generating synthetic data.
+    example: Example usage and demonstrations.
+"""
+
+from . import recovery_methods
+from . import model
+from . import generate_data
+from . import example
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("pyCLINE")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # Default when package is not installed
+
+__all__ = ["recovery_methods", "model", "generate_data", "example"]

pycline-0.1.7/src/pyCLINE/example.py

@@ -0,0 +1,164 @@
+import sys 
+import os
+from . import generate_data
+import pandas as pd
+import matplotlib.pyplot as plt
+from . import recovery_methods
+from . import model
+import torch.nn as nn
+import numpy
+import torch
+
+class ExampleCallable:
+    def __call__(self, example_model, plot=True):
+        example(example_model, plot)
+
+sys.modules[__name__]= ExampleCallable()
+
+def example(example_model, plot):
+    """
+    This function runs multiple examples, depending on the choice of the example model. 
+    It should be used as a guideline how to run pyCLINE for synthetic data. 
+    For using pyCLINE on real data, the user should adapt the data source accordingly.
+
+    Args:
+        example_model (str): Selection of model to run the example on. Chose from 'FHN', 'Bicubic', 'GeneExpression', 'DelayOscillator'.
+        plot (bool): If True, the function will plot the data and the predictions.
+
+    Raises:
+        ValueError: In case no example model string is provided.
+    """
+
+    #provide name of model to run example
+    if example_model is None:
+        raise ValueError("Error: example_model is None: please provide a model name (FHN, Bicubic, GeneExpression, DelayOscillator).")
+    
+    # check if data already exists
+    path='data/synthetic_data/'
+    if example_model=='FHN': 
+        fname='FHN_eps=0.3_a=0.0.csv'
+    else: 
+        fname=example_model+'.csv'
+    
+    print('Running example for model: '+example_model)
+    print('Step 1: Load or generate data')
+    # generate data if it does not exist
+    if os.path.exists(path+fname):
+        print('Data already exists: '+path+fname)
+        df = pd.read_csv(path+fname)
+
+    else:
+        print('No data saved: generating data for model: '+example_model)
+        getattr(generate_data, example_model)()
+        print('Data generated saved: '+path+fname)
+        df = pd.read_csv(path+fname)
+    
+    # extracting 1 time series and plotting
+    if example_model!='DelayOscillator':
+        df_sim = df[(df['sim']==1)].copy()
+    else:
+        df_sim=df.copy()
+    df_sim.reset_index(drop=True, inplace=True)
+
+    if example_model=='DelayOscillator':
+        tau=10 # 12,20,35
+        v_data=df_sim['u'][df_sim['time']>=tau].values
+        df_sim=df_sim[df_sim['time']<=df_sim['time'].max() - tau]
+        df_sim['v']=v_data
+
+    if plot:
+        fig,ax = plt.subplots(1,1,figsize=(5,3))
+        ax.plot(df_sim['time'], df_sim['u'], label='u')
+        ax.plot(df_sim['time'], df_sim['v'], label='v')
+        ax.set_xlabel('Time')
+        ax.set_ylabel('Amount in arbs. units')
+        plt.show()
+    
+    # prepare data for training
+    # tmin: minimum time point to consider to avoid transient behavior
+    # val_min, val_max: min and max values of the min max normalization
+    print('Step 2: Prepare data for training')
+    if example_model=='FHN':
+        tmin, val_min, val_max=3, -1.0, 1.0
+    if example_model=='Bicubic':
+        tmin, val_min, val_max=10, 0.0, 1.0 
+    if example_model=='GeneExpression':
+        tmin, val_min, val_max=10, 0.0, 1.0
+    if example_model=='DelayOscillator':
+        tmin, val_min, val_max=100,0.0,1.0
+
+
+    # normalize data and create additional derivative or delayed variables
+    df_sim, df_coef = recovery_methods.data_preparation.prepare_data(df_sim, vars=['u', 'v'], time='time', tmin=tmin, scheme='derivative', value_min=val_min, value_max=val_max)
+
+    # define input and target variables (can be changed as needed)
+    input_vars, target_vars = ['norm u', 'd normu/dt'], ['norm v']
+
+    # schuffle and split training, test and validation data
+    # optimal_thresholding: if True, the amount of samples within the phase space is evenly distributed
+    input_train, target_train, input_test, target_test, input_val, target_val = recovery_methods.data_preparation.shuffle_and_split(df_sim, input_vars = input_vars,
+                                                                                                                    target_var = target_vars,
+                                                                                                                    optimal_thresholding=False)
+    
+    # set up the model
+    # Nin: number of input variables
+    # Nout: number of output variables
+    # Nlayers: number of layers
+    # Nnodes: number of nodes per layer
+    # summary: if True, the model summary is printed
+    # lr: learning rate
+    # activation: activation function can be chosen as needed
+    print('Step 3: Set up the model')
+    nn_model,  optimizer, loss_fn = recovery_methods.nn_training.configure_FFNN_model(Nin=len(input_vars), Nout=len(target_vars),
+                                                                                   Nlayers=3, Nnodes=64, summary=True, lr=1e-4,
+                                                                                   activation=nn.SiLU)
+    
+    # train the model
+    print('Step 4: Train the model')
+    training_loss, val_loss, test_loss, predictions_evolution, lc_predictions = recovery_methods.nn_training.train_FFNN_model(model=nn_model,
+                                                                                                                            optimizer=optimizer, loss_fn=loss_fn,
+                                                                                                                            input_train=input_train,
+                                                                                                                            target_train=target_train,input_test=input_test, 
+                                                                                                                            target_test=target_test, 
+                                                                                                                            validation_data=(input_val, target_val),
+                                                                                                                            epochs=3000, batch_size=64, device='cpu',save_evolution=True, 
+                                                                                                                            method='derivative', minimal_value=val_min,maximal_value=val_max)
+
+    # save model and predictions
+    print('Step 5: Save the generated predictions and model')
+    if not os.path.exists(f'results/{example_model}'):
+        os.makedirs(f'results/{example_model}')
+
+    torch.save(nn_model.state_dict(), f'results/{example_model}/model.pth')
+    numpy.save(f'results/{example_model}/predictions.npy', predictions_evolution)
+    numpy.save(f'results/{example_model}/lc_predictions.npy', lc_predictions)
+    numpy.save(f'results/{example_model}/training_loss.npy', training_loss)
+    numpy.save(f'results/{example_model}/val_loss.npy', val_loss)
+    numpy.save(f'results/{example_model}/test_loss.npy', test_loss)
+
+    print('Example completed: model and predictions saved in results/'+example_model)
+
+    # plot the predictions
+    if plot:
+        print('Step 6: Plot the predictions')
+        fig,ax = plt.subplots(1,1,figsize=(5,3))
+        ax.scatter(df_sim['norm u'], df_sim['norm v'], label='GT LC', c='silver')
+        ax.scatter(input_train['norm u'], lc_predictions[-1,:,0],
+                c='C2', label='Pred. LC', s=2 )
+        
+        # compute nullcline
+        u = numpy.linspace(df_coef['u'].min(), df_coef['u'].max(), predictions_evolution.shape[1])
+        sim_model = getattr(model, example_model)()
+        gt_nullcline=sim_model.vnull(u)
+        
+        norm_u=recovery_methods.data_preparation.normalize_adjusted(u, df_coef,'u', 
+                                                                    min=val_min, max=val_max)
+        norm_gt_nullcline=recovery_methods.data_preparation.normalize_adjusted(gt_nullcline, df_coef,'v', 
+                                                                               min=val_min, max=val_max)
+        
+        ax.plot(norm_u,norm_gt_nullcline, label='GT NC', c='k')
+        ax.plot(norm_u,predictions_evolution[-1,:], label='Pred. NC', c='C1')
+        ax.set_xlabel('u')
+        ax.set_ylabel('v')
+        ax.legend()
+        plt.show()

pycline-0.1.7/src/pyCLINE/generate_data.py

@@ -0,0 +1,105 @@
+import numpy as np
+from . import model
+
+def FHN(dt=0.1, N=1000000, epsilons=[0.3], n_intiaL_conditions=1):
+    """
+    Generate data using the FitzHugh-Nagumo model (see src/pyCLINE/model.py)
+    with different time scale separation, as used in Prokop, Billen, Frolov, Gelens (2025).
+
+    Args:
+        dt (float): Time step. Defaults to 0.1.
+        N (int): Number of time steps. Defaults to 1000000.
+        epsilons (list): List of time scale separations. Defaults to [0.3].
+    
+    Returns:
+        None
+    """
+    if dt <= 0:
+        raise ValueError("Time step (dt) must be positive.")
+    if N <= 0:
+        raise ValueError("Number of time steps (N) must be positive.")
+    if n_intiaL_conditions <= 0:
+        raise ValueError("Number of initial conditions must be positive.")
+
+    u = np.zeros([2,N])
+    for i_eps, eps in enumerate(epsilons):
+        u[:,0] = [0.1, 0.1]
+        p = [1, 1, eps, 0.5, 0.0]
+        fhn=model.FHN(p)
+        u0, v0 = np.meshgrid(np.linspace(-1.25,1.75,n_intiaL_conditions),np.linspace(-0.75,1.75,n_intiaL_conditions))
+        x0 = np.array([u0,v0])
+        fhn.generate_data(x0, dt, N)
+    pass
+
+def Bicubic(dt=0.1, N=1000000, n_intiaL_conditions=1):
+    """
+    Generate data using the Bicubic model (see src/pyCLINE/model.py),
+    as used in Prokop, Billen, Frolov, Gelens (2025).
+
+    Args:
+        dt (float, optional): Time step. Defaults to 0.1.
+        N (int, optional): Number of time steps. Defaults to 1000000.
+    """
+    if dt <= 0:
+        raise ValueError("Time step (dt) must be positive.")
+    if N <= 0:
+        raise ValueError("Number of time steps (N) must be positive.")
+    if n_intiaL_conditions <= 0:
+        raise ValueError("Number of initial conditions must be positive.")
+
+    u = np.zeros([2,N])
+
+    u[:,0] = [0.1, 0.1]
+    p = [-0.5, 0.5, -1/3]
+
+    bicubic=model.Bicubic(p)
+    u0, v0 = np.meshgrid(np.linspace(-1.25,1.75,n_intiaL_conditions),np.linspace(-0.75,1.75,n_intiaL_conditions))
+    x0 = np.array([u0,v0])
+    bicubic.generate_data(x0, dt, 10000)
+    pass
+
+def GeneExpression(dt=0.1, N=1000000, n_intiaL_conditions=1):
+    """
+    Generate data using the Gene Expression model (see src/pyCLINE/model.py),
+    as used in Prokop, Billen, Frolov, Gelens (2025).
+
+    Args:
+        dt (float, optional): Time step. Defaults to 0.1.
+        N (int, optional): Number of time steps. Defaults to 1000000.
+    """
+    if dt <= 0:
+        raise ValueError("Time step (dt) must be positive.")
+    if N <= 0:
+        raise ValueError("Number of time steps (N) must be positive.")
+    if n_intiaL_conditions <= 0:
+        raise ValueError("Number of initial conditions must be positive.")
+
+    u = np.zeros([2,N])
+
+    u[:,0] = [0.1, 0.1]
+    p=[1, 0.05,  1, 0.05,   1, 0.05,  1,  1, 0.1,  2]
+
+    gene_expression=model.GeneExpression(p)
+    u0, v0 = np.meshgrid(np.linspace(0,1.75,n_intiaL_conditions),np.linspace(0,1.75,n_intiaL_conditions))
+    x0 = np.array([u0,v0])
+    gene_expression.generate_data(x0, dt, 10000)
+    pass
+
+def DelayOscillator(N=20000):
+    """
+    Generate data using the Delay Oscillator model (see src/pyCLINE/model.py),
+    as used in Prokop, Billen, Frolov, Gelens (2025).
+
+    Args:
+        N (int, optional): Number of time steps. Defaults to 20000.
+    """
+    if N <= 0:
+        raise ValueError("Number of time steps (N) must be positive.")
+    
+    time = np.linspace(0, 400, N-1)
+    dt=time[1]-time[0]
+    p=[4, 10, 2]
+
+    delay_osci=model.DelayOscillator(p)
+    delay_osci.generate_data( y_0=0, dt=dt, t_max=time[-1])
+    pass