RateData

The RateData class represents instantaneous firing rates for one or more units. It stores a 2-D array of shape (num_units, num_bins) along with bin size and time axis metadata. RateData objects are typically created from a SpikeData object via binning and optional smoothing.

class spikelab.spikedata.ratedata.RateData(inst_Frate_data, times, neuron_attributes=None, rate_unit=None)[source]

Bases: object

A 2D instantaneous firing rate matrix with unit-to-unit correlation capabilities.

Parameters:

  • inst_Frate_data (array) – 2D array of shape (U, T). Each value is the instantaneous firing rate. U is the number of units/neurons and T is the number of time bins.

  • times (list) – List of time values that each column index in inst_Frate_data represents. For example, times = [5, 10, 15] so inst_Frate_data column 0 is 5 ms, column 1 is 10 ms, and column 2 is 15 ms.

  • neuron_attributes (list or None) – List of dicts, one per unit, containing arbitrary metadata about each neuron. None if not provided.

inst_Frate_data

2D array of shape (U, T). Each value is the instantaneous firing rate. U is the number of units/neurons and T is the number of time bins.

Type:

array

times

List of time values that each column index in inst_Frate_data represents. For example, times = [5, 10, 15] so inst_Frate_data column 0 is 5 ms, column 1 is 10 ms, and column 2 is 15 ms.

Type:

list

neuron_attributes

List of dicts, one per unit, containing arbitrary metadata about each neuron. None if not provided.

Type:

list or None

N

Number of units in inst_Frate_data.

Type:

int

Notes

  • times may contain negative values when the RateData represents an event-aligned window (e.g., times from -200 to +500 ms around a stimulus).

  • subtime always treats start/end as literal time values. Use subtime_by_index for index-based slicing with negative indexing.

__init__(inst_Frate_data, times, neuron_attributes=None, rate_unit=None)[source]

Initialize a RateData object.

Parameters:

  • inst_Frate_data (numpy.ndarray) – Firing rate data, shape (N, T).

  • times (numpy.ndarray or list) – Time points, length T.

  • neuron_attributes (list or None) – Per-unit attribute dicts.

  • rate_unit (str or None) – Unit of the rate values. Typically "Hz" (spikes/s) for resampled_isi or "kHz" (spikes/ms) for sliding_rate. When None, the unit is unspecified.

subset(units, by=None)[source]

Extract a subset of units/neurons from the rate data.

Parameters:

  • units (list or array) – Unit indices to extract. If by is None, this should always be a list of ints. If by is not None, the list can contain ints or strings.

  • by (str or None) – Neuron attribute key to match against. Only use this if you initialized the object with neuron_attributes. Set to the key that contains neuron_id values. None selects by index (default).

Returns:

New RateData object containing only the

specified units.

Return type:

result (RateData)

subtime(start, end)[source]

Extract a subset of time points from the rate data using time values.

Original time values are preserved in the output.

Parameters:

  • start (int or float) – Starting time value (inclusive).

  • end (int or float) – Ending time value (exclusive).

Returns:

New RateData object containing only the

specified time range.

Return type:

result (RateData)

Notes

  • Start and end are always treated as literal time values (not offsets from the end). To slice by array index with negative indexing support, use subtime_by_index(start_idx, end_idx).

subtime_by_index(start_idx, end_idx)[source]

Extract a subset of time points from the rate data using time index values.

Original time values are preserved in the output.

Parameters:

  • start_idx (int) – Starting time index (inclusive).

  • end_idx (int) – Ending time index (exclusive).

Returns:

New RateData object containing only the

specified time range.

Return type:

result (RateData)

Notes

  • Supports negative indexing (e.g., -5 selects 5 from the end).

  • To slice by time values instead of array indices, use subtime(start, end).

frames(length, overlap=0)[source]

Split the rate data into a RateSliceStack of fixed-length windows.

Parameters:

  • length (float) – Length of each window in milliseconds.

  • overlap (float) – Overlap between consecutive windows in milliseconds. Default 0.

Returns:

Stack of rate data windows, one per frame.

Return type:

stack (RateSliceStack)

Notes

  • Windows that would extend past the end of the recording are excluded.

  • overlap must be strictly less than length.

get_pairwise_fr_corr(compare_func=<function compute_cross_correlation_with_lag>, max_lag=10, n_jobs=-1)[source]

Compute unit-to-unit similarity from the firing rate matrix (U, T).

Parameters:

  • compare_func (callable) – Comparison function from utils. Specify cross-correlation or cosine similarity. The default is cross correlation. See utils.py for details.

  • max_lag (int) – Max number of lag steps around 0 to consider for finding the max correlation. If None, lag is set to 0.

  • n_jobs (int) – Number of threads for parallel computation. -1 uses all cores (default), 1 disables parallelism, None is serial.

Returns:

Maximum correlation coefficients

between all unit/neuron pairs. matrix[i, j] is the max correlation between unit i and unit j. Values range from -1 to 1. Diagonal is always 1 (self-correlation).

lag_matrix (PairwiseCompMatrix): Time lags (in time bins) at which

maximum correlation occurs. lag_matrix[i, j] is the lag where correlation between i and j is maximal. Positive lag means unit j leads unit i (j fires earlier). Negative lag means unit i leads unit j (i fires earlier). Diagonal is always 0.

Return type:

corr_matrix (PairwiseCompMatrix)

get_manifold(method='PCA', n_components=2, **kwargs)[source]

Project the firing-rate data into a low-dimensional manifold using PCA or UMAP.

Parameters:

  • method (str) – Which dimensionality reduction method to use. Either "PCA" (default) or "UMAP".

  • n_components (int) – Number of output dimensions to return (default 2).

  • **kwargs – Additional options for UMAP. If method is "UMAP", you can specify use_graph_communities (bool), return_labels (bool), and other UMAP-specific keyword arguments such as n_neighbors, min_dist, metric, or resolution.

Returns:

Depends on method and options:

If method is "PCA": (embedding, explained_variance_ratio, components) where embedding has shape (T, n_components), explained_variance_ratio has shape (n_components,), and components has shape (n_components, U). If method is "UMAP": (embedding, trustworthiness) where embedding has shape (T, n_components) and trustworthiness is a float from 0 to 1. If method is "UMAP" with use_graph_communities=True and return_labels=True: (embedding, labels, trustworthiness).

Return type:

result (tuple)

Notes

  • To visualise the resulting embedding, use plot_manifold(). It accepts the embedding array directly and supports background masks, continuous colour values, and discrete group colouring.