nstat.CIF

class nstat.CIF(beta=None, Xnames=None, stimNames=None, fitType='poisson', histCoeffs=None, historyObj=None, nst=None)[source]

Bases: object

Conditional Intensity Function for point-process modelling.

Encapsulates the regression coefficients, variable names, link function, and optional spike-history terms that define a conditional intensity function (CIF). Supports symbolic differentiation (gradient / Jacobian) for use in point-process adaptive filters and decoders.

Parameters:

beta (array_like or None) – Regression coefficients.
Xnames (sequence of str or None) – Names of the variables in the order they appear in beta.
stimNames (sequence of str or None) – Names of the subset of variables that define the stimulus.
fitType ({‘poisson’, ‘binomial’}, default 'poisson') – Link function. For Poisson: λΔ = exp(Xβ). For binomial: λΔ = exp(Xβ) / (1 + exp(Xβ)).
histCoeffs (array_like or None) – Coefficients for each history window defined in historyObj.
historyObj (History or array_like or None) – History object (or window-times vector) defining the spiking- history basis.
nst (nspikeTrain or None) – Spike train used to pre-compute history values.

See also

History, DecodingAlgorithms

__init__(beta=None, Xnames=None, stimNames=None, fitType='poisson', histCoeffs=None, historyObj=None, nst=None)[source]

Parameters:

beta (Sequence[float] | ndarray | None)
Xnames (Sequence[str] | None)
stimNames (Sequence[str] | None)
fitType (str)
histCoeffs (Sequence[float] | ndarray | None)

Return type:

None

CIFCopy()[source]: Return a deep copy of this CIF object.

setSpikeTrain(spikeTrain)[source]

Attach a spike train and pre-compute the history matrix.

Return type:: None

setHistory(histObj)[source]

Set the History object for this CIF.

Parameters:: histObj (History or array_like) – A History object, or a vector of window-times from which one will be created.
Return type:: None

evalLambdaDelta(stimVal, time_index=None, nst=None)[source]

Evaluate λΔ at the given stimulus values.

Parameters:

stimVal (array_like) – Stimulus variable values.
time_index (int or None) – 0-based time index into the pre-computed history matrix.
nst (nspikeTrain or None) – Spike train for on-the-fly history computation.

Returns:

Scalar value of λΔ.

Return type:

float

evalGradient(stimVal, time_index=None, nst=None)[source]

Gradient of λΔ with respect to the stimulus variables.

Returns:

Row vector of partial derivatives.

Return type:

ndarray, shape (1, n_stim)

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

evalGradientLog(stimVal, time_index=None, nst=None)[source]

Gradient of log(λΔ) with respect to the stimulus variables.

Returns:

Row vector of partial derivatives.

Return type:

ndarray, shape (1, n_stim)

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

evalJacobian(stimVal, time_index=None, nst=None)[source]

Hessian of λΔ with respect to the stimulus variables.

Returns:

Second-derivative matrix.

Return type:

ndarray, shape (n_stim, n_stim)

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

evalJacobianLog(stimVal, time_index=None, nst=None)[source]

Hessian of log(λΔ) with respect to the stimulus variables.

Returns:

Second-derivative matrix.

Return type:

ndarray, shape (n_stim, n_stim)

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

evalLDGamma(stimVal, time_index=None, nst=None, gamma=None)[source]

Evaluate λΔ with gamma-scaled history coefficients.

Parameters:

stimVal (array_like) – Stimulus variable values.
time_index (int or None) – 0-based time index into the history matrix.
nst (nspikeTrain or None) – Spike train for on-the-fly history computation.
gamma (array_like or None) – Scaling factors applied to the history coefficients.

Returns:

Scalar value of λΔ.

Return type:

float

evalLogLDGamma(stimVal, time_index=None, nst=None, gamma=None)[source]

Evaluate log(λΔ) with gamma-scaled history coefficients.

Returns:

Scalar value of log(λΔ).

Return type:

float

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

evalGradientLDGamma(stimVal, time_index=None, nst=None, gamma=None)[source]

Gradient of λΔ w.r.t. gamma (history-coefficient scaling).

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

evalGradientLogLDGamma(stimVal, time_index=None, nst=None, gamma=None)[source]

Gradient of log(λΔ) w.r.t. gamma (history-coefficient scaling).

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

evalJacobianLogLDGamma(stimVal, time_index=None, nst=None, gamma=None)[source]

Hessian of log(λΔ) w.r.t. gamma (history-coefficient scaling).

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

evalJacobianLDGamma(stimVal, time_index=None, nst=None, gamma=None)[source]

Hessian of λΔ w.r.t. gamma (history-coefficient scaling).

Parameters:

time_index (int | None)
nst (nspikeTrain | None)

isSymBeta()[source]

Return True if the coefficients contain symbolic expressions.

Return type:: bool

evaluate(design_matrix, *, delta=1.0, history_matrix=None)[source]

Evaluate the CIF on a full design matrix (vectorised).

Parameters:

design_matrix (ndarray, shape (n_time, n_vars)) – Design matrix with one row per time step.
delta (float, default 1.0) – Bin width (seconds). The returned rate is λΔ / Δ.
history_matrix (ndarray or None) – Pre-computed history matrix, shape (n_time, n_hist).

Returns:

Firing rate in Hz.

Return type:

ndarray, shape (n_time,)

to_covariate(time, design_matrix, *, delta=1.0, name='lambda')[source]

Evaluate the CIF and return the result as a Covariate.

Parameters:

time (Sequence[float])
design_matrix (ndarray)
delta (float)
name (str)

Return type:

Covariate

static simulateCIFByThinningFromLambda(lambda_covariate, numRealizations=1, maxTimeRes=None, *, seed=None, random_values=None, thinning_values=None, return_details=False)[source]

Simulate spike trains from a given λ(t) via thinning.

Uses the thinning (rejection) algorithm: propose spikes from a homogeneous Poisson process at the bound rate, then accept each candidate with probability λ(t) / λ_max.

Parameters:

lambda_covariate (Covariate) – Conditional intensity function time series (Hz).
numRealizations (int, default 1) – Number of independent spike-train realisations.
maxTimeRes (float or None) – Minimum inter-spike interval (seconds). Spikes closer than this are merged.
seed (int or None) – Random seed for reproducibility.
random_values (ndarray or None) – Pre-drawn uniform random values for the proposal process.
thinning_values (ndarray or None) – Pre-drawn uniform random values for thinning acceptance.
return_details (bool, default False) – If True, return (collection, details_dict) instead.

Returns:

Collection of simulated spike trains.

Return type:

SpikeTrainCollection

static simulateCIFByThinning(mu, hist, stim, ens, inputStimSignal, inputEnsSignal, numRealizations=1, simType='binomial', *, seed=None, return_lambda=False, backend='auto')[source]

Simulate a point process via the thinning algorithm.

Alias for simulateCIF(). See that method for full parameter documentation.

Parameters:

inputStimSignal (Covariate)
inputEnsSignal (Covariate)
numRealizations (int)
simType (str)
seed (int | None)
return_lambda (bool)
backend (str)

static simulateCIF(mu, hist, stim, ens, inputStimSignal, inputEnsSignal, numRealizations=1, simType='binomial', *, seed=None, return_lambda=False, random_values=None, return_details=False, backend='auto')[source]

Simulate a point process from component kernels and inputs.

Constructs λΔ from the input terms μ + stim ∗ inputStimSignal + hist ∗ spikeHistory + ens ∗ inputEnsSignal and generates spike trains via Bernoulli draws at each time step.

Parameters:

mu (float) – Baseline (mean) log-rate of the process.
hist (transfer-function-like or array_like) – History kernel convolved with the process’s own spiking.
stim (transfer-function-like or array_like) – Stimulus kernel convolved with inputStimSignal.
ens (transfer-function-like or array_like) – Ensemble kernel convolved with inputEnsSignal.
inputStimSignal (Covariate) – Stimulus time series.
inputEnsSignal (Covariate) – Ensemble activity time series.
numRealizations (int, default 1) – Number of independent realisations.
simType ({‘binomial’, ‘poisson’}, default 'binomial') – Link function for computing λΔ.
seed (int or None) – Random seed (Python backend only).
return_lambda (bool, default False) – If True, return (collection, lambda_array).
random_values (ndarray or None) – Pre-drawn uniform random values for reproducibility (Python backend only).
return_details (bool, default False) – If True, return (collection, details_dict) (Python backend only).
backend ({‘auto’, ‘matlab’, ‘python’}, default 'auto') – Simulation backend. 'auto' uses MATLAB/Simulink when available and falls back to the native Python implementation with a MatlabFallbackWarning. 'matlab' forces Simulink (raises if unavailable). 'python' forces the native implementation with no warning.

Returns:

Simulated spike trains (or tuple if return_lambda / return_details is True).

Return type:

SpikeTrainCollection

static from_linear_terms(time, intercept, coefficients, design_matrix, dt, name='lambda')[source]

Parameters:

time (ndarray)
intercept (float)
coefficients (ndarray)
design_matrix (ndarray)
dt (float)
name (str)

Return type:

Covariate