nstat.CovariateCollection

class nstat.CovariateCollection(covariates=None, *more_covariates)[source]

Bases: object

Ordered collection of Covariate objects (Matlab CovColl).

Provides collection-level masking, time alignment, sample-rate enforcement, and covariate shifting. Individual covariates are accessed via 0-based indexing (getCov(1)) to match Matlab.

Parameters:

covariates (Covariate, sequence of Covariate, or None) – Initial covariate(s) to add.
more_covariates (Covariate)

See also

Covariate: Scalar or multi-dimensional signal with CIs.
Trial: Combines a CovariateCollection with spike data.

property covariates: list[Covariate]: List of all covariates (copies with collection state applied).

property names: list[str]: List of covariate names in insertion order.

setMinTime(minTime=None)[source]

Set the collection-level minimum time (applies shift if set).

Parameters:: minTime (float | None)
Return type:: None

setMaxTime(maxTime=None)[source]

Set the collection-level maximum time (applies shift if set).

Parameters:: maxTime (float | None)
Return type:: None

setSampleRate(sampleRate)[source]

Set the collection sample rate and enforce it on all covariates.

Parameters:: sampleRate (float)
Return type:: None

setMask(cellInput)[source]

Set the covariate mask from a selector or 'all' to reset.

Accepts the same formats as generateSelectorCell().

Return type:: None

getCovDataMask(identifier)[source]

Return the binary dimension mask for a single covariate.

Parameters:: identifier (int | str)
Return type:: ndarray

isCovMaskSet()[source]

Return True if any covariate dimension is currently masked out.

Return type:: bool

nActCovar()[source]

Return the number of covariates with at least one active dimension.

Return type:: int

maskAwayCov(identifier)[source]

Zero-out the mask for the specified covariate(s).

Parameters:: identifier (int | str | Sequence[int] | Sequence[str])
Return type:: None

copy()[source]

Return a deep copy of this collection.

Return type:: CovariateCollection

maskAwayOnlyCov(identifier)[source]

Reset all masks then mask away only the specified covariate(s).

Parameters:: identifier (int | str | Sequence[int] | Sequence[str])
Return type:: None

maskAwayAllExcept(identifier)[source]

Mask away every covariate except the ones specified.

Matches MATLAB CovColl.m:202-208 (maskAwayOnlyCov → resetMask first, then maskAwayCov). Before the reset the kept covariates’ masks were preserved as-is, which silently dropped any covariate whose stored mask was already all-zero — e.g. the per-neighbor masks inside Trial.ensCovColl, which are initialised for neuron 1’s view and contain zeros for the other neuron’s row. Without resetting, getEnsCovMatrix(n=2) returned an empty matrix and the NetworkTutorial fit silently dropped the inter-neuron coupling term.

Parameters:: identifier (int | str | Sequence[int] | Sequence[str])
Return type:: None

getCov(identifier)[source]

Return a covariate copy with collection state (shift, mask, rate) applied.

Parameters:: identifier (int, str, or sequence) – 0-based index, covariate name, or sequence of either.

get(name)[source]

Retrieve a covariate by name (convenience alias for getCov()).

Parameters:: name (str)
Return type:: Covariate

getCovIndFromName(name)[source]

Return the 0-based index of a covariate by name.

Parameters:: name (str)
Return type:: int

getCovIndicesFromNames(name)[source]

Return 0-based index(es) for one or more covariate names.

Parameters:: name (Sequence[str] | str)

getCovDimension(identifier=None)[source]

Return the dimension of each covariate selected by identifier.

Matlab signature: dim = getCovDimension(ccObj, identifier)

Returns a 1-D int array whose i-th element is covs{i}.dimension.

Return type:: ndarray

getAllCovLabels()[source]

Return the data-labels of every covariate dimension (no mask filtering).

Return type:: list[str]

getCovLabelsFromMask()[source]

Return data-labels only for dimensions that are currently unmasked.

Return type:: list[str]

toStructure()[source]

Serialize to a plain dict (Matlab CovColl.toStructure).

Return type:: dict[str, Any]

findMinTime()[source]

Return the earliest minTime across all stored covariates.

Return type:: float

findMaxTime()[source]

Return the latest maxTime across all stored covariates.

Note: MATLAB CovColl.m:371-380 applies covShift twice here (once inside the per-covariate max(...) and once after the loop) — see AUDIT_REPORT M7 / nSTAT issue #18. Python adds the shift exactly once, in _refresh_summary and setMaxTime. Do not “fix” this to match MATLAB’s behavior.

Return type:: float

findMaxSampleRate()[source]

Return the highest sample rate across all stored covariates.

Return type:: float

addToColl(covariates)[source]

Parameters:: covariates (Sequence[Covariate] | Covariate | 'CovariateCollection' | None)
Return type:: None

add(covariate)[source]

Alias for addToColl().

Parameters:: covariate (Covariate)
Return type:: None

addCovariate(covariate)[source]

Alias for addToColl().

Parameters:: covariate (Covariate)
Return type:: None

addCovCollection(covariates)[source]

Merge all covariates from another collection into this one.

Parameters:: covariates (CovariateCollection)
Return type:: None

isCovPresent(cov)[source]

Return 1 if a covariate is in this collection, 0 otherwise.

Return type:: int

resample(sampleRate)[source]

Alias for setSampleRate().

Parameters:: sampleRate (float)
Return type:: None

restoreToOriginal()[source]

Restore original sample rate, time bounds, shift, and masks.

Return type:: None

restrictToTimeWindow(wMin, wMax)[source]

Set both min and max time to restrict the visible window.

Parameters:

wMin (float)
wMax (float)

Return type:

None

removeCovariate(identifier)[source]

Remove a covariate by 0-based index or name.

Parameters:: identifier (int | str)
Return type:: None

resetMask()[source]

Enable all covariate dimensions (clear any masking).

Return type:: None

enforceSampleRate()[source]

Resample every stored covariate to match self.sampleRate.

Matches MATLAB CovColl.m:491-502 which iterates each covariate and calls resampleMe whenever its rate differs from the collection’s rate. The previous Python implementation only validated that self.sampleRate was finite; it did NOT actually resample stored covariates. Net effect: a collection built by sequentially adding covariates at increasing rates would report self.sampleRate at the highest rate but leave earlier covariates at their original (lower) rates. Closes audit finding H3.

Return type:: None

setCovShift(deltaT, identifier=None)[source]

Apply a temporal shift deltaT to the collection’s time axis.

Matches MATLAB CovColl.m:504-520 which calls resetCovShift first (zeroing any previously-applied shift and recomputing base bounds) and then sets the new shift. The previous Python implementation accumulated shifts: calling setCovShift(0.2) twice produced base + 0.4 instead of the intended base + 0.2. Closes audit finding L1.

Parameters:: deltaT (float)
Return type:: CovariateCollection

resetCovShift()[source]

Remove the temporal shift and recompute time bounds.

Return type:: None

flattenCovMask()[source]

Concatenate all per-covariate masks into a single 1-D binary array.

Return type:: ndarray

getSelectorFromMasks(covMask=None)[source]

Convert per-covariate binary masks to lists of active 0-based indices.

Parameters:: covMask (list[ndarray] | None)
Return type:: list[list[int]]

generateSelectorCell(dataSelector)[source]

Parse a heterogeneous dataSelector into per-covariate index lists.

Accepts name-based ([['covName', 'label1', ...], ...]) or numeric ([[1,2], [3], ...]) selectors.

Return type:: list[list[int]]

setMasksFromSelector(selectorCell)[source]

Set covariate masks from a list of 0-based index lists.

Parameters:: selectorCell (list[list[int]])
Return type:: None

dataToMatrix(repType='standard', dataSelector=None, *_)[source]

Return the covariate data matrix (no time column) for active dimensions.

Parameters:: repType (str | Sequence[str] | None)
Return type:: ndarray

matrixWithTime(repType='standard', dataSelector=None)[source]

Return (time, data_matrix, labels) for active covariate dimensions.

Parameters:

repType ({'standard', 'zero-mean'}) – Signal representation type.
dataSelector (optional) – Name-based or numeric selector; None uses the current mask.

Return type:

tuple[ndarray, ndarray, list[str]]

dataToMatrixFromNames(repType='standard', dataSelector=None, *args)[source]

Return the data matrix for a name-based dataSelector.

Thin wrapper that resolves the name-based selector through generateSelectorCell() and dispatches to dataToMatrixFromSel(). Mirrors MATLAB CovColl.dataToMatrixFromNames (CovColl.m:563).

Parameters:: repType (str)
Return type:: ndarray

dataToMatrixFromSel(repType='standard', selectorCell=None, *_args)[source]

Return the data matrix for an explicit per-covariate selectorCell.

Each entry of selectorCell is a list of 0-based dimension indices for the corresponding covariate. Mirrors MATLAB CovColl.dataToMatrixFromSel (CovColl.m:567).

Parameters:: repType (str)
Return type:: ndarray

dataToStructure(selectorCell=None, binwidth=None, minTime=None, maxTime=None)[source]

Serialize active covariate data to a {'time': ..., 'signals': ...} dict.

Parameters:

binwidth (float | None)
minTime (float | None)
maxTime (float | None)

Return type:

dict[str, Any]

plot(*_, handle=None, **__)[source]

Plot each covariate in a vertically stacked panel layout.

Parameters:: handle (matplotlib Figure, Axes, list of Axes, or None) – If a Figure, new subplots are created. If a single Axes or a list of Axes, plot into those directly. If None, a new figure is created.

static fromStructure(structure)[source]

Reconstruct from a dict produced by toStructure().

Return type:: ‘CovariateCollection’ | list[‘CovariateCollection’]