API Reference

nSTAT clean-room Python toolbox.

The package preserves high-level MATLAB nSTAT structure while using Python-native implementations and interfaces.

class nstat.Analysis

Static analysis methods for point-process GLM fitting.

This class intentionally mirrors MATLAB’s class-centric access pattern, while returning plain typed Python result objects.

static compute_fit_residual(y, X, fit_result, dt=1.0)

Return Pearson-like residuals for fitted GLM observations.

Parameters:

  • y (ndarray)

  • X (ndarray)

  • fit_result (FitResult)

  • dt (float)

Return type:

ndarray

static compute_inv_gaus_trans(y, X, fit_result, dt=1.0)

Compute integrated-intensity transform surrogate used in GOF diagnostics.

Parameters:

  • y (ndarray)

  • X (ndarray)

  • fit_result (FitResult)

  • dt (float)

Return type:

ndarray

static compute_ks_stats(transformed_events)

Compute one-sample KS statistic against Uniform(0, 1) after rescaling.

Parameters:

transformed_events (ndarray)

Return type:

dict[str, float]

static fdr_bh(p_values, alpha=0.05)

Benjamini-Hochberg FDR control for one-dimensional p-value arrays.

Parameters:

  • p_values (ndarray)

  • alpha (float)

Return type:

ndarray

static fit_glm(X, y, fit_type='poisson', dt=1.0, l2_penalty=0.0)

Fit independent-bin GLM with analytical gradients.

Parameters:

  • X (ndarray) – Design matrix with shape (n_samples, n_features).

  • y (ndarray) – Observation vector with shape (n_samples,).

  • fit_type (str) – "poisson" or "binomial".

  • dt (float) – Bin width in seconds; used for Poisson expected counts.

  • l2_penalty (float) – Ridge penalty applied to coefficients (not intercept).

Return type:

FitResult

static fit_trial(trial, config, unit_index=0)

Fit Poisson/binomial GLM for a single unit within a trial.

Parameters:
Return type:

FitResult

static glm_fit(X, y, fit_type='poisson', dt=1.0, l2_penalty=0.0)

MATLAB-style alias for fit_glm().

Parameters:

  • X (ndarray)

  • y (ndarray)

  • fit_type (str)

  • dt (float)

  • l2_penalty (float)

Return type:

FitResult

static run_analysis_for_all_neurons(trial, config)

Fit one model per unit in a trial using the same configuration.

Parameters:
Return type:

list[FitResult]

static run_analysis_for_neuron(trial, config, unit_index=0)

High-level wrapper matching MATLAB naming for per-neuron analysis.

Parameters:
Return type:

FitResult

class nstat.CIFModel(coefficients, intercept=0.0, link='poisson')

Generalized linear conditional intensity model.

Parameters:

  • coefficients (numpy.ndarray) – Model coefficients, one per feature.

  • intercept (float) – Scalar intercept term.

  • link (str) – poisson (log link) or binomial (logit link).

compute_plot_params(X)

Return compact summary stats useful for help/notebook plots.

Parameters:

X (ndarray)

Return type:

dict[str, float]

eval_lambda_delta(X, dt=1.0)

Evaluate lambda * dt for Poisson, or Bernoulli probability for binomial.

Parameters:

  • X (ndarray)

  • dt (float)

Return type:

ndarray

evaluate(X)

Evaluate point-wise intensity (Poisson) or probability (binomial).

Parameters:

X (ndarray)

Return type:

ndarray

static from_structure(payload)

Deserialize from to_structure() payload.

Parameters:

payload (dict[str, ndarray | float | str])

Return type:

CIFModel

linear_predictor(X)

Compute linear predictor eta = intercept + X @ coefficients.

Parameters:

X (ndarray)

Return type:

ndarray

log_likelihood(y, X, dt=1.0)

Return independent-bin log-likelihood under the configured link.

Parameters:

  • y (ndarray) – Observation vector. - Poisson: non-negative integer counts per bin. - Binomial: Bernoulli outcomes in {0, 1}.

  • X (ndarray) – Design matrix with shape (n_samples, n_features).

  • dt (float) – Bin width in seconds. Poisson intensity is interpreted in Hz, so expected counts are lambda * dt.

Return type:

float

simulate_by_thinning(time, X, rng=None)

Simulate spike times on a fixed grid.

Notes

For Poisson models this performs exact simulation under a piecewise-constant intensity assumption over each time bin. For binomial models this performs one Bernoulli draw per bin.

Parameters:

  • time (ndarray)

  • X (ndarray)

  • rng (Generator | None)

Return type:

ndarray

static simulate_cif_by_thinning_from_lambda(time, lambda_values, num_realizations=1, rng=None)

Simulate spike times from explicit lambda(t) traces.

This is a Python-native counterpart to MATLAB’s CIF.simulateCIFByThinningFromLambda workflow.

Parameters:

  • time (ndarray)

  • lambda_values (ndarray)

  • num_realizations (int)

  • rng (Generator | None)

Return type:

list[ndarray]

to_structure()

Serialize model parameters to a plain structure.

Return type:

dict[str, ndarray | float | str]

class nstat.ConfidenceInterval(time, lower, upper, level=0.95)

Lower/upper confidence envelope over time.

Parameters:

  • time (numpy.ndarray) – Monotonic time grid.

  • lower (numpy.ndarray) – Lower confidence bound values.

  • upper (numpy.ndarray) – Upper confidence bound values.

  • level (float) – Confidence level in (0,1), defaults to 0.95.

contains(values)

Return boolean mask indicating whether values are inside the interval.

Parameters:

values (ndarray)

Return type:

ndarray

width()

Return point-wise interval width.

Return type:

ndarray

class nstat.ConfigCollection(configs)

Collection of trial configurations.

Parameters:

configs (list[TrialConfig])

class nstat.Covariate(time, data, name='signal', units=None, x_label=None, y_label=None, x_units=None, y_units=None, plot_props=<factory>, labels=<factory>, conf_interval=None)

Named design covariate with optional per-column labels.

Parameters:

  • labels (list[str]) – Optional labels for each covariate column. For vector covariates, one label is expected.

  • time (ndarray)

  • data (ndarray)

  • name (str)

  • units (str | None)

  • x_label (str | None)

  • y_label (str | None)

  • x_units (str | None)

  • y_units (str | None)

  • plot_props (dict[str, Any])

  • conf_interval (Any | None)

Notes

This class is intentionally lightweight; higher-level composition and selection live in nstat.trial.

compute_mean_plus_ci(axis=1, level=0.95)

Compute mean and Gaussian CI for multi-channel/trial covariate data.

Parameters:

  • axis (int)

  • level (float)

Return type:

tuple[ndarray, ndarray, ndarray]

filtfilt(b, a)

Zero-phase filter each covariate channel.

Parameters:

  • b (ndarray)

  • a (ndarray)

Return type:

Covariate

static from_structure(payload)

Deserialize from to_structure() payload.

Parameters:

payload (dict[str, Any])

Return type:

Covariate

get_sub_signal(selector)

Return selected covariate channels by index or label.

Parameters:

selector (Any)

Return type:

Covariate

to_structure()

Serialize to plain python structure.

Return type:

dict[str, Any]

class nstat.CovariateCollection(covariates)

Grouped covariates with aligned time grids.

Parameters:

covariates (list[Covariate])

add_to_coll(covariate)

Append one covariate after validating time-grid alignment.

Parameters:

covariate (Covariate)

Return type:

CovariateCollection

copy()

Return a deep copy preserving covariate order.

Return type:

CovariateCollection

data_to_matrix()

Alias for design-matrix export.

Return type:

tuple[ndarray, list[str]]

data_to_matrix_from_names(names)

Build design matrix using selected covariate names.

Parameters:

names (list[str])

Return type:

tuple[ndarray, list[str]]

data_to_matrix_from_sel(selectors)

Build design matrix using selected covariate indices.

Parameters:

selectors (list[int])

Return type:

tuple[ndarray, list[str]]

design_matrix()

Return (X, labels) where X has shape (n_time, n_features).

Return type:

tuple[ndarray, list[str]]

get_all_cov_labels()

Flatten all covariate labels into one list.

Return type:

list[str]

get_cov(selector)

Return covariate by index or by name.

Parameters:

selector (int | str)

Return type:

Covariate

get_cov_dimension()

Total number of covariate columns across all entries.

Return type:

int

get_cov_ind_from_name(name)

Return first index matching covariate name.

Parameters:

name (str)

Return type:

int

get_cov_indices_from_names(names)

Return indices for a list of covariate names.

Parameters:

names (list[str])

Return type:

list[int]

is_cov_present(name)

Return whether a covariate name exists in the collection.

Parameters:

name (str)

Return type:

bool

n_act_covar()

MATLAB-style active covariate count helper.

Return type:

int

num_act_cov()

Alias for n_act_covar.

Return type:

int

sum_dimensions()

Alias for total feature dimension.

Return type:

int

class nstat.DecodingAlgorithms

Collection of static decoding methods.

static compute_spike_rate_cis(spike_matrix, alpha=0.05)

Compute trial rates, pairwise p-values, and FDR-controlled differences.

Parameters:

  • spike_matrix (ndarray) – Binary/count matrix shaped (n_trials, n_time_bins).

  • alpha (float) – Significance threshold for pairwise trial differences.

Returns:

  • spike_rate – Trial-wise average event rate per bin.

  • prob_mat – Pairwise two-sided p-value matrix.

  • sig_mat – Binary significance matrix after Benjamini-Hochberg FDR control.

Return type:

tuple[ndarray, ndarray, ndarray]

static compute_spike_rate_diff_cis(spike_matrix_a, spike_matrix_b, alpha=0.05)

Compute trial-wise rate differences and Wald-style confidence intervals.

Parameters:

  • spike_matrix_a (ndarray) – First trial matrix, shape (n_trials, n_time_bins).

  • spike_matrix_b (ndarray) – Second trial matrix, shape (n_trials, n_time_bins).

  • alpha (float) – Two-sided confidence level parameter.

Return type:

tuple[ndarray, ndarray, ndarray]

static compute_stimulus_cis(posterior, state_values, alpha=0.05)

Approximate posterior mean and confidence intervals of a decoded stimulus.

Parameters:

  • posterior (ndarray)

  • state_values (ndarray)

  • alpha (float)

Return type:

tuple[ndarray, ndarray, ndarray]

static decode_state_posterior(spike_counts, tuning_rates, transition=None, prior=None)

Decode discrete latent state by point-process Bayes filtering.

Parameters:

  • spike_counts (ndarray) – Non-negative count matrix with shape (n_units, n_time).

  • tuning_rates (ndarray) – Expected spike counts per bin with shape (n_units, n_states).

  • transition (ndarray | None) – Optional Markov transition matrix (n_states, n_states) where columns index next-state probabilities.

  • prior (ndarray | None) – Optional initial state prior. Defaults to a uniform distribution.

Return type:

tuple[ndarray, ndarray]

static decode_weighted_center(spike_counts, tuning_curves)

Decode latent state via weighted center-of-mass estimator.

Parameters:

  • spike_counts (ndarray) – Shape (n_units, n_time).

  • tuning_curves (ndarray) – Shape (n_units, n_states).

Return type:

ndarray

static kalman_filter(y, a, h, q, r, x0, p0)

Run Kalman filtering over all time points.

Parameters:

  • y (ndarray)

  • a (ndarray)

  • h (ndarray)

  • q (ndarray)

  • r (ndarray)

  • x0 (ndarray)

  • p0 (ndarray)

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

static kalman_fixed_interval_smoother(xf, pf, xp, pp, a)

Rauch-Tung-Striebel fixed-interval smoother.

Parameters:

  • xf (ndarray)

  • pf (ndarray)

  • xp (ndarray)

  • pp (ndarray)

  • a (ndarray)

Return type:

tuple[ndarray, ndarray]

static kalman_predict(x_prev, p_prev, a, q)

Linear-Gaussian Kalman prediction step.

Parameters:

  • x_prev (ndarray)

  • p_prev (ndarray)

  • a (ndarray)

  • q (ndarray)

Return type:

tuple[ndarray, ndarray]

static kalman_update(x_pred, p_pred, y_t, h, r)

Linear-Gaussian Kalman update step.

Parameters:

  • x_pred (ndarray)

  • p_pred (ndarray)

  • y_t (ndarray)

  • h (ndarray)

  • r (ndarray)

Return type:

tuple[ndarray, ndarray]

class nstat.Events(times, labels=<factory>)

Discrete event times with labels.

Parameters:

  • times (numpy.ndarray) – Event times in seconds.

  • labels (list[str]) – Optional event labels; defaults to empty strings.

subset(start_s, end_s)

Return events within inclusive time interval.

Parameters:

  • start_s (float)

  • end_s (float)

Return type:

Events

class nstat.FigureTracker(*, topic, expected_count, output_root=None, default_figsize=(7.0, 5.0), dpi=180)

Track notebook figure creation/saving with strict ordinals.

Parameters:

  • topic (str)

  • expected_count (int)

  • output_root (str | Path | None)

  • default_figsize (tuple[float, float])

  • dpi (int)

add_placeholder_plot(fig, *, seed, title)

Add deterministic placeholder content so saved figures are never blank.

Parameters:

  • seed (int)

  • title (str)

Return type:

None

add_reference_plot(fig, *, image_path, title)

Render a MATLAB reference image onto a matplotlib figure.

Parameters:

  • image_path (str | Path)

  • title (str)

Return type:

bool

class nstat.FitResult(coefficients, intercept, fit_type, log_likelihood, n_samples, n_parameters, parameter_labels=<factory>, ks_stats=<factory>, fit_residual=None, inv_gaus_stats=<factory>, neuron_name='', plot_params=<factory>, xval_data=<factory>, xval_time=<factory>)

Result container for one fitted model.

Parameters:

  • coefficients (ndarray)

  • intercept (float)

  • fit_type (str)

  • log_likelihood (float)

  • n_samples (int)

  • n_parameters (int)

  • parameter_labels (list[str])

  • ks_stats (dict[str, ndarray | float])

  • fit_residual (ndarray | None)

  • inv_gaus_stats (dict[str, ndarray | float])

  • neuron_name (str)

  • plot_params (dict[str, Any])

  • xval_data (list[ndarray])

  • xval_time (list[ndarray])

add_params_to_fit(payload)

Update optional FitResult metadata in-place.

Parameters:

payload (dict[str, Any])

Return type:

None

aic()

Akaike information criterion.

Return type:

float

as_cif_model()

Return a nstat.cif.CIFModel view of this fitted model.

Return type:

CIFModel

bic()

Bayesian information criterion.

Return type:

float

static cell_array_to_structure(results)

Serialize a list of fit results into structure list form.

Parameters:

results (list[FitResult])

Return type:

list[dict[str, Any]]

compute_plot_params()

Compute MATLAB-style coefficient plotting payload.

Return type:

dict[str, Any]

compute_val_lambda(X)

MATLAB-style alias for evaluating predicted intensity/probability.

Parameters:

X (ndarray)

Return type:

ndarray

classmethod from_structure(payload)

Build a FitResult from a serialized structure.

Parameters:

payload (dict[str, Any])

Return type:

FitResult

get_coeff_index(label)

Return index of a parameter label.

Parameters:

label (str)

Return type:

int

get_coeffs()

Return non-intercept coefficients.

Return type:

ndarray

get_param(key)

Access a parameter/statistic by canonical key.

Parameters:

key (str)

Return type:

float | ndarray | str | int

get_plot_params()

Return cached plot parameters, computing if necessary.

Return type:

dict[str, Any]

get_unique_labels()

Return unique parameter labels preserving order.

Return type:

list[str]

map_cov_labels_to_unique_labels()

Return unique covariate labels for MATLAB parity call sites.

Return type:

list[str]

predict(X)

Predict mean response from feature matrix X.

Parameters:

X (ndarray)

Return type:

ndarray

set_fit_residual(residual)

Attach residual vector used by MATLAB diagnostics.

Parameters:

residual (ndarray)

Return type:

None

set_inv_gaus_stats(payload)

Attach inverse-Gaussian transform stats if available.

Parameters:

payload (dict[str, Any])

Return type:

None

set_ks_stats(ks_stat, p_value=None, within_conf_int=None)

Store KS statistics in MATLAB-compatible key layout.

Parameters:

  • ks_stat (ndarray | float | dict[str, Any])

  • p_value (ndarray | float | None)

  • within_conf_int (ndarray | float | None)

Return type:

None

set_neuron_name(name)

Assign a stable neuron identifier.

Parameters:

name (str)

Return type:

None

to_structure()

Serialize this fit result to a MATLAB-like plain structure.

Return type:

dict[str, Any]

class nstat.FitSummary(results)

Summary statistics across multiple fitted models.

Parameters:

results (list[FitResult])

bin_coeffs(min_val, max_val, bin_size=0.1)

Histogram coefficients and estimate percent-significant per bin.

Parameters:

  • min_val (float)

  • max_val (float)

  • bin_size (float)

Return type:

tuple[ndarray, ndarray, ndarray]

box_plot(X=None, diff_index=1)

Return box-plot summary statistics for compatibility workflows.

Parameters:

  • X (ndarray | None)

  • diff_index (int)

Return type:

dict[str, ndarray]

compute_diff_mat(metric='aic')

Compute pairwise absolute difference matrix for selected metric.

Parameters:

metric (str)

Return type:

ndarray

classmethod from_structure(payload)

Deserialize a summary from structure form.

Parameters:

payload (dict[str, Any])

Return type:

FitSummary

get_coeff_index(fit_num=1, sort_by_epoch=False)

Return coefficient row indices and epoch metadata for a fit index.

Parameters:

  • fit_num (int)

  • sort_by_epoch (bool)

Return type:

tuple[ndarray, ndarray, int]

get_coeffs(fit_num=1)

Return coefficient and SE matrices aligned by unique labels.

Parameters:

fit_num (int)

Return type:

tuple[ndarray, list[str], ndarray]

get_diff_aic()

Return AIC differences relative to best model.

Return type:

ndarray

get_diff_bic()

Return BIC differences relative to best model.

Return type:

ndarray

get_diff_log_likelihood()

Return log-likelihood differences relative to best model.

Return type:

ndarray

get_unique_labels()

Return union of parameter labels across all fit results.

Return type:

list[str]

to_structure()

Serialize summary and nested fit results into plain structures.

Return type:

dict[str, Any]

class nstat.HistoryBasis(bin_edges_s)

Piecewise-constant history basis.

Parameters:

bin_edges_s (numpy.ndarray) – Increasing edges (seconds) defining history windows. Example: [0.0, 0.01, 0.05, 0.1].

design_matrix(spike_times_s, time_grid_s)

Build history design matrix for a binned point-process model.

Notes

For each time point and basis window, the entry counts spikes in the lag interval (t - edge_hi, t - edge_lo]. This mirrors common GLM history encoding while remaining explicit and testable.

Parameters:

  • spike_times_s (ndarray)

  • time_grid_s (ndarray)

Return type:

ndarray

class nstat.InstallReport(cache_dir, python_version, package='nstat')

Structured output from nstat_install().

Parameters:

  • cache_dir (Path)

  • python_version (str)

  • package (str)

class nstat.Signal(time, data, name='signal', units=None, x_label=None, y_label=None, x_units=None, y_units=None, plot_props=<factory>)

Continuous signal sampled on a 1D time grid.

Parameters:

  • time (numpy.ndarray) – Strictly increasing time samples (seconds by convention).

  • data (numpy.ndarray) – Signal values. Can be 1D (n_time) or 2D (n_time, n_channels).

  • name (str) – Human-readable signal name.

  • units (str | None) – Optional unit label.

  • x_label (str | None)

  • y_label (str | None)

  • x_units (str | None)

  • y_units (str | None)

  • plot_props (dict[str, Any])

Notes

MATLAB SignalObj supports broad plotting and metadata utilities. This base class keeps the core numerical contract minimal and explicit, then downstream classes layer workflow-specific behavior.

align_time(new_zero_time=0.0)

Shift time so that current first sample equals new_zero_time.

Parameters:

new_zero_time (float)

Return type:

Signal

copy()

Return a deep copy.

Return type:

Signal

copy_signal()

MATLAB-style alias for copy().

Return type:

Signal

data_to_matrix()

Return data in 2D matrix form (n_time, n_channels).

Return type:

ndarray

derivative()

Numerical first derivative over time.

Return type:

Signal

property duration_s: float

Signal duration in seconds.

get_sub_signal(selector)

Select one or more channels by index.

Parameters:

selector (int | list[int] | ndarray)

Return type:

Signal

integral()

Cumulative trapezoidal integral of each channel over time.

Return type:

ndarray

merge(other)

Merge channels from two signals that share the same time grid.

Parameters:

other (Signal)

Return type:

Signal

property n_channels: int

Number of channels (1 for a vector signal).

property n_samples: int

Number of time samples.

resample(sample_rate_hz)

Resample signal by linear interpolation to a new sample rate.

Parameters:

sample_rate_hz (float)

Return type:

Signal

property sample_rate_hz: float

Estimated sample rate in Hertz using median time delta.

class nstat.SpikeTrain(spike_times, t_start=0.0, t_end=None, name='unit')

Single-neuron spike-time sequence.

Parameters:

  • spike_times (ndarray)

  • t_start (float)

  • t_end (float | None)

  • name (str)

bin_counts(bin_size_s)

Return bin centers and integer spike-count vector.

Parameters:

bin_size_s (float)

Return type:

tuple[ndarray, ndarray]

binarize(bin_size_s)

Return bin centers and binary spike-presence vector.

Parameters:

bin_size_s (float)

Return type:

tuple[ndarray, ndarray]

copy()

Return a deep copy of the spike train.

Return type:

SpikeTrain

get_spike_times()

Return spike times (MATLAB-style helper).

Return type:

ndarray

set_max_time(t_max)

Set upper support bound and drop spikes after that bound.

Parameters:

t_max (float)

Return type:

SpikeTrain

set_min_time(t_min)

Set lower support bound and drop spikes before that bound.

Parameters:

t_min (float)

Return type:

SpikeTrain

shift_time(offset_s)

Shift spike times and support interval by a constant offset.

Parameters:

offset_s (float)

Return type:

SpikeTrain

class nstat.SpikeTrainCollection(trains=<factory>)

Collection of spike trains.

Parameters:

trains (list[SpikeTrain])

add_single_spike_to_coll(unit_index, spike_time_s, sort_times=True)

Add one spike event to a selected unit.

Parameters:

  • unit_index (int)

  • spike_time_s (float)

  • sort_times (bool)

Return type:

SpikeTrainCollection

add_to_coll(train)

Append a spike train in-place and return self.

Parameters:

train (SpikeTrain)

Return type:

SpikeTrainCollection

copy()

Return a deep copy of the collection.

Return type:

SpikeTrainCollection

data_to_matrix(bin_size_s, mode='binary')

Return only the binned matrix.

Parameters:

  • bin_size_s (float)

  • mode (Literal['binary', 'count'])

Return type:

ndarray

get_first_spike_time()

Minimum spike time across all units.

Return type:

float

get_last_spike_time()

Maximum spike time across all units.

Return type:

float

get_nst(index)

Return train by zero-based index.

Parameters:

index (int)

Return type:

SpikeTrain

get_nst_from_name(name, first_only=True)

Return train(s) matching name.

Parameters:

  • name (str)

  • first_only (bool)

Return type:

SpikeTrain | list[SpikeTrain]

get_nst_indices_from_name(name)

Return all indices matching a train name.

Parameters:

name (str)

Return type:

list[int]

get_nst_name_from_ind(index)

Return train name from index.

Parameters:

index (int)

Return type:

str

get_nst_names()

Return all train names.

Return type:

list[str]

get_spike_times()

Return all spike-time vectors as copies.

Return type:

list[ndarray]

get_unique_nst_names()

Return unique train names preserving first occurrence order.

Return type:

list[str]

merge(other)

Return a new collection containing trains from both inputs.

Parameters:

other (SpikeTrainCollection)

Return type:

SpikeTrainCollection

set_max_time(t_max)

Apply upper bound to all trains.

Parameters:

t_max (float)

Return type:

SpikeTrainCollection

set_min_time(t_min)

Apply lower bound to all trains.

Parameters:

t_min (float)

Return type:

SpikeTrainCollection

shift_time(offset_s)

Shift all trains by a constant temporal offset.

Parameters:

offset_s (float)

Return type:

SpikeTrainCollection

to_binned_matrix(bin_size_s, mode='binary')

Convert collection to (n_units, n_bins) matrix.

Parameters:

  • bin_size_s (float) – Width of each time bin in seconds.

  • mode (Literal['binary', 'count']) – "binary" for per-bin event indicators or "count" for integer spike counts per bin.

Return type:

tuple[ndarray, ndarray]

to_spike_train(name='merged')

Merge all spikes into one spike train.

Parameters:

name (str)

Return type:

SpikeTrain

class nstat.Trial(spikes, covariates)

Container binding spike observations to covariates.

Parameters:
aligned_binned_observation(bin_size_s, unit_index=0, mode='binary')

Return aligned (time, y, X) for one unit.

X is covariate matrix sampled to nearest available covariate time index. mode controls whether y contains binary indicators or integer spike counts per bin.

Parameters:

  • bin_size_s (float)

  • unit_index (int)

  • mode (Literal['binary', 'count'])

Return type:

tuple[ndarray, ndarray, ndarray]

get_cov(selector)

Return trial covariate by index or name.

Parameters:

selector (int | str)

Return type:

Covariate

get_design_matrix()

Return full-trial design matrix and labels.

Return type:

tuple[ndarray, list[str]]

get_neuron(unit_index=0)

Return a single-neuron collection preserving collection API.

Parameters:

unit_index (int)

Return type:

SpikeTrainCollection

get_spike_vector(bin_size_s, unit_index=0, mode='binary')

Return binned spike vector (time, y) for one unit.

Parameters:

  • bin_size_s (float)

  • unit_index (int)

  • mode (Literal['binary', 'count'])

Return type:

tuple[ndarray, ndarray]

is_sample_rate_consistent(rtol=1e-06)

Check whether covariates share effectively identical sample rates.

Parameters:

rtol (float)

Return type:

bool

class nstat.TrialConfig(covariate_labels=<factory>, sample_rate_hz=1000.0, fit_type='poisson', name='config')

Model specification for one fit configuration.

Parameters:

  • covariate_labels (list[str])

  • sample_rate_hz (float)

  • fit_type (str)

  • name (str)

nstat.data_is_present(data_dir)

Return True when data dir has expected structure + sentinel.

Parameters:

data_dir (Path)

Return type:

bool

nstat.ensure_example_data(download=True)

Ensure example data are available and return data root.

Parameters:

download (bool) – When True (default), download + extract from DOI if missing. When False, raise FileNotFoundError if data are absent.

Return type:

Path

nstat.fetch_matlab_gold_file(relative_path, version=None)

Fetch one file from mirrored MATLAB data via the datasets API.

Parameters:

  • relative_path (str) – File path relative to MATLAB data/ root, for example "PlaceCellAnimal1Results.mat".

  • version (str | None) – Optional mirror version (default: latest available).

Return type:

Path

nstat.get_data_dir()

Return the resolved example-data root.

Resolution order: 1. NSTAT_DATA_DIR environment variable. 2. <repo_root>/data_cache/nstat_data.

Return type:

Path

nstat.latest_matlab_gold_version()

Return latest mirrored MATLAB version known by datasets manifest.

Return type:

str | None

nstat.list_matlab_gold_files(version=None)

List mirrored MATLAB files available in datasets manifest.

Parameters:

version (str | None) – Optional mirror version label (for example "20260302"). When omitted, rows across all mirrored versions are returned.

Return type:

list[str]

nstat.nstat_install(cache_dir=None)

Run lightweight post-install setup for nSTAT-python.

Parameters:

cache_dir (str | Path | None) – Optional custom data-cache location.

Returns:

Report containing resolved cache directory and runtime metadata.

Return type:

InstallReport

Core modules

  • nstat.signal

  • nstat.confidence

  • nstat.events

  • nstat.history

  • nstat.spikes

  • nstat.trial

  • nstat.cif

  • nstat.analysis

  • nstat.fit

  • nstat.decoding

  • nstat.datasets

  • nstat.install

  • nstat.compat.matlab