Source code for hetero.stimulus

from os.path import join as osjoin # an alias for convenience
from hetero.stims.maps import *
from hetero.stims.processes import *
from hetero.stims.elementary import *
from hetero.utils import get_default_args




def synthesize(name, n_timesteps, dt_scaler, **stim_params):
    """Synthesizes timeseries from the specified process.
    
    Parameters
    ----------
    name : str
        The name of the underlying process. See notes for valid names.
    n_timesteps : int
        Number of timesteps.  
    dt_scaler : float
        A scaling factor to up/down scale the integrator's timestep (only relevant for
        `processes`.)

    Returns
    -------
    ndarray
        Synthesized array 


    Notes
    -----
    All supported generative processes can be categorized into three categories:
    
    - elementary functions: simple functions of time 
    - maps: functions of previous step (without explicit notion of physical time)
    - processes: (system of) ODEs with explicit notion of time 
    
    The valid processes are listed below. Also see their respective documentation
    for potential arguments.
    
    Elementary functions 
      - sin
      - sign
      - null 
      - constant 

    Maps
      -  henon_map
      -  logistic_map
      -  narma
    
    Processes 
      - lorenz
      - lorenz96
      - mackey_glass
      - multiscroll
      - doublescroll
      - rabinovich_fabrikant
      - rossler
      - kuramoto_sivashinsky
    
    """

    func = eval(name)
    h_default = get_default_args(func).get('h', 1.)
    return func(n_timesteps = n_timesteps, 
                h = h_default*dt_scaler,
                **stim_params)





def is_constant_stim(stim_params: dict) -> bool:
    """Checks whether the stimulus configuration is a pure constant (DC) input.

    A constant (DC) input carries no characteristic timescale. Hence, its
    temporal characterization (base-lag estimation) and the subsequent time
    rescaling are irrelevant and can be bypassed.

    Parameters
    ----------
    stim_params : dict
        Stimulus parameters, e.g. ``{'constant': {'amplitude': 1.}}`` or a
        combination thereof, e.g. ``{'constant': ..., 'constant-4': ...}``.

    Returns
    -------
    bool
        True if every (compound) component is a ``constant`` input.
    """
    return bool(stim_params) and all(
        name.split('-')[0] == 'constant' for name in stim_params
    )