brainbox.modeling.design_matrix

Functions

convbasis

denseconv

Classes

DesignMatrix

Design matrix constructor that will take in information about the temporal structure of a trial and allow the generation of a design matrix with specified regressors
class DesignMatrix(trialsdf, vartypes, binwidth=0.02)[source]

Bases: object

Design matrix constructor that will take in information about the temporal structure of a trial and allow the generation of a design matrix with specified regressors

binf(t)[source]

Function to bin time t into binwidth of DM

Parameters

t (float) – time, in seconds

Returns

number of time bins

Return type

int

add_covariate_timing(covlabel, eventname, bases, offset=0, deltaval=None, cond=None, desc='')[source]

Convenience wrapper for adding timing event regressors to the design matrix.

Timing events are regressed against using basis functions, such as those generated by the functions in this module, which are convolved with a kronecker delta at the time where the event occurred. This operation is effectively a copy/paste of the basis functions, each of which have their own column in the design matrix. This means that when we fit weights, a single weight can govern the prediction of the model over a longer time period.

Can be offset, such that the bases functions are applied before or after the timing.

The height of the bases can be modified by a column in the design matrix, which will then multiply the delta function which is convolved with the bases.

Parameters

  • covlabel (str) – Label which the covariate will use. Can be accessed via dot syntax of the instance usually.

  • eventname (str) – Label of the column in trialsdf which has the event timing for each trial.

  • bases (numpy.array) – nTB x nB array, i.e. number of time bins for the bases functions by number of bases. Each column in the array is used together to describe the response of a unit to that timing event.

  • offset (float, seconds) – Offset of bases functions relative to timing event. Negative values mean bases will be applied before the timing event by that amount.

  • deltaval (None, str, or pandas series, optional) – Values of the kronecker delta function peak used to encode the event. If a string, the column in trialsdf with that label will be used. If a pandas series with indexes matching trialsdf, corresponding elements of the series will be the delta funtion val. If None (default) height is 1.

  • cond (None, list, or fun, optional) – Condition which to apply this covariate. Can either be a list of trial indices, or a function which takes in rows of the trialsdf and returns booleans.

  • desc (str, optional) – Additional information about the covariate, if desired. by default ‘’

add_covariate_boxcar(covlabel, boxstart, boxend, cond=None, height=None, desc='')[source]

Convenience wrapped on add_covariate to add a boxcar covariate on the given start and end variables, such that the covariate is a step function with non-zero value between those values.

Note: This has not been tested yet and is not guaranteed to work, or work correctly.

Parameters

  • covlabel (str) – Name of the covariate for accessing later. Can be accessed via dot syntax of the instance usually.

  • boxstart (str) – Column name in trialsdf which will be used to define the start of the boxcar

  • boxend (str) – Column name in trialsdf which defines the end of boxcar variable

  • cond (None, list, or func, optional) – Condition in which to apply this covariate. Can either be a list of trial indices, or a function which takes in a row of the trialsdf and returns a boolen on inclusion, by default None

  • height (None, str, or pandas series, optional) – Values for the height of the boxcar during the period defined per trial. Can be a reference to a column in trialsdf or a separate series, by default None

  • desc (str, optional) – Additional information about the covariate to store as a string, by default ‘’

add_covariate_raw(covlabel, raw, cond=None, desc='')[source]

Convenience wrapper to add a ‘raw’ covariate, that is to say a covariate which is a continuous value that changes with time during the course of a trial.

Note: This has not been tested and is not guaranteed to work or to work correctly.

Parameters

  • covlabel (str) – String used to reference covariate, can usually be accessed by instance’s dot syntax

  • raw (str, func, or pandas series) – The covariate to add to the design matrix. Can be a str reference to a column in trialsdf, a function which takes in rows of trialsdf and produces a vector for each row of the appropriate size given binwidth and trial duration, or a pandas series of vectors of said appropriate type.

  • cond (None, list, or func, optional) – Trials in which to apply the given covariate. Can be a list of trial numbers, or a function which accepts rows of the trialsdf and returns a boolean, by default None

  • desc (str, optional) – Additional information about the covariate for access later, by default ‘’

add_covariate(covlabel, regressor, bases, offset=0, cond=None, desc='')[source]

Parent function to add covariates to model object. Takes a regressor in the form of a pandas Series object, a T x M array of M bases, and stores them for use in the design matrix generation.

Parameters

  • covlabel (str) – Label for the covariate being added. Will be exposed, if possible, through (instance).(covlabel) attribute.

  • regressor (pandas.Series) – Series in which each element is the value(s) of a regressor for a trial at that index. These will be convolved with the bases functions (if provided) to produce the components of the design matrix. Regressor must be (T / dt) x 1 array for each trial

  • bases (numpy.array or None) – T x M array of M basis functions over T timesteps. Columns will be convolved with the elements of regressor to produce elements of the design matrix. If None, it is assumed a raw regressor is being used.

  • offset (int, optional) – Offset of the regressor from the bases during convolution. Negative values indicate that the firing of the unit will be , by default 0

  • cond (list or func, optional) – Condition for which to apply covariate. Either a list of trials which the covariate applies to, or a function of the form f(dataframerow) which returns a boolean, by default None

  • desc (str, optional) – Description of the covariate for reference purposes, by default ‘’ (empty)

compile_design_matrix(dense=True)[source]

Compiles design matrix for the current experiment based on the covariates which were added with the various NeuralGLM.add_covariate methods available. Can optionally compile a sparse design matrix using the scipy.sparse package, however that method may take longer depending on the degree of sparseness.

Parameters

dense (bool, optional) – Whether or not to compute a dense design matrix or a sparse one, by default True

denseconv(X, bases)[source]
convbasis(stim, bases, offset=0)[source]