Quickstart

To use stnmf, it first has to be imported. Whether in a Python script or in an IPython environment like jupyter notebooks, the procedure is identical.

Importing

All essential functionality of stnmf is encapsulated within the class STNMF class. For advanced usage, individual modules can be imported additionally.

>>> from stnmf import STNMF

Basic usage

An STNMF object performs the matrix factorization and offers an interface for results and visualization for a given ganglion cell (exemplary for a neuron of the sensory pathways).

The STNMF object is constructed from the spiking response of the ganglion cell to spatiotemporal white-noise stimulation, specifically, from the effective spike-triggered stimulus ensemble (STE). The STE is expected of a Python array_like data type, e.g. a nested list or numpy.ndarray, and has three dimensions:

x : Spatial width of the stimulus
y : Spatial height of the stimulus
s : Number of spikes

The STE should tightly enclose (x and y) the receptive field to ensure a low-dimensionality input.

Note

For aid in how to construct the STE, visit the stnmf.preprocessing module.

Additional arguments for the construction of the STNMF object are optional and may affect the factorization. These include the upper bound of expected subunits (referred to as r modules) and - crucially - a suitable sparsity regularization parameter. If not specified, these optional arguments default to general values.

Note

For optimal subunit recovery, the sparsity value should be carefully chosen. That is possible using the methods of Hyperparameter selection.

Factorization

By default, the STNMF algorithm runs immediately when creating the STNMF object. Thus, given the STE array (x, y, s), the localized subunits can be recovered with the default parameters with just one line

>>> stnmf = STNMF(ste)

Note

Different arguments can be specified when running the STNMF algorithm, such as different sparsity-regularization. For more details, view the class documentation of STNMF or consult the Examples.

Results

The object is now stored in the variable stnmf. This STNMF object exposes many properties. Among the most accessible are the following, where r is the number of modules (the defined upper bound) and l is the number of the localized subunits as defined by the sufficient spatial autocorrelation.

STNMF.subunits(l, x, y) numpy.ndarray: Recovered spatially localized subunits (normalized), where l is the number of subunits (modules considered to be localized subunits), and x and y are the spatial dimensions from the STE
STNMF.ratios(l,) numpy.ndarray: Scalar weights/contribution ratios of the subunits (\(\ell 2\)-normalized), i.e. the subset of STNMF weights averaged over the spikes, where l is the number of subunits
STNMF.outlines(l,) numpy.ndarray: Contour outlines of the localized subunits
STNMF.diameters(l,) numpy.ndarray: Diameters in micrometers (μm). Only if STNMF.pixel_size as been defined

The pixel size mentioned in the size measurement attributes can be set with

>>> stnmf.pixel_size = 30  # One stixel (stimulus pixel) is 30 μm wide and tall

Visualization

The results can be visualized conveniently in one figure that compiles the output of all plotting routines automatically (see Advanced plotting and stnmf.plot for details) with

>>> stnmf.plot()

More details

For more details on usage and concrete usage examples, see Examples.