STNMF (`stnmf.STNMF`)

Spike-triggered non-negative matrix factorization class

class stnmf.STNMF(*args, **kwargs)

Bases: MF

Spike-triggered non-negative matrix factorization (STNMF)

An object of the class exposes the following attributes and methods. For details, see the documentation of the individual items below.

Spatial modules and weights

`modules`	Recovered spatial modules
`weights`	Recovered weights for all modules and all spikes
`subunits`	Localized subunits, i.e. subset of STNMF modules (normalized).
`ratios`	Scalar weights/contribution ratios of each localized subunit, i.e. subset of STNMF weights (averaged and normalized).
`num_subunits`	Number of localized subunits as determined by their Moran's I autocorrelation

Subunit attributes

`outlines`	Contour outlines of the localized subunits at contour level equivalent to 1.22 standard deviations
`diameters`	Diameters of the localized subunits as defined by the effective diameter of a two-sigma elliptical Gaussian fit in micrometers (μm).
`distances`	Euclidean distances of localized subunits from STA center in micrometers (μm).
`polarities`	Signs of the localized subunits at maximum intensity (positive +1 or negative -1)
`moransi`	Moran's I autocorrelation of all modules.
`localized`	Indices of localized subunits among all modules as determined by their Moran's I autocorrelation and moransi_threshold

Object methods

`plot`([full, colors, cmap])	Visualize STNMF results in a figure
`factorize`(args, *kwargs)
`flipsign`()	Flip sign of modules for their average weights to be positive
`sort`()	Sort modules by their absolute average weight, localized first

Parameter attributes

`pixel_size`	Pixel size in micrometers (μm) for calculation of spatial diameter and distance
`moransi_threshold`	Threshold of Morans'I to distinguish localized subunits

Further attributes

`sta`	Spatial profile of the spike-triggered average (STA)
`sta_outline`	Contour outline of the STA at contour level equivalent to 1.22 standard deviations.
`sta_diameter`	Diameter of the STA as defined by the effective diameter of a two-sigma elliptical Gaussian fit in micrometers (μm).
`coverage`	Fraction of spatial coverage of localized subunits on the STA
`modules_info`	Collection of all module properties for all modules for easy dot- and multi-indexing
`res`	Reconstruction error (residual) based on Frobenius norm

See also

stnmf.mf: Matrix factorization classes

Examples

>>> from stnmf import STNMF
>>> stnmf = STNMF(ste)

The created STNMF object exposes further attributes and functions; for example, to visualize the resulting decomposition.

>>> stnmf.plot()

Notes

Find more information in the documentation of the __init__ method below.

__init__(ste, r=20, init='nnsvdlrc', flipsign=True, sort=True, factorize=True, *args, **kwargs)

Spike-triggered non-negative matrix factorization using AF-HALS

Parameters:

ste ((x,y,m) array_like) – Spike-triggered stimulus ensemble with x*y pixels and m spikes
r (int, optional) – Number of modules to recover. Default is 20
init ((r,x,y) array_like or {'random', 'nnsvdlrc'}, optional) – Initial modules. If array_like, serves as the initial modules directly. If ‘random’ or ‘nnsvdlrc’, calls the functions from stnmf.init. If None, no automatic initialization will be performed, and has to be done manually by calling init. Default is ‘nnsvdlrc’
flipsign (bool, optional) – Flip the sign of the modules to make their mean weights positive. Default is True
sort (bool, optional) – Sort modules by mean weights. Default is True
factorize (bool, optional) – Factorize on initialization. Default is True

Keyword Arguments:

method (str or class, optional) – Matrix factorization class. Default is ‘SparseSemiNMF’
sparsity (float, optional) – Sparsity regularization weight if method is ‘SparseSemiNMF’; otherwise invalid parameter. Default is 1.7
seed (int, optional) – Random seed for reproducibility. Default is 0
dtype (str, type or numpy.dtype, optional) – Number format with which to calculate. Default is ‘float32’
pixel_size (float, optional) – Size of a stixel (stimulus pixel) in micrometers (μm) for calculation of spatial diameter and distance. If not set, these calculations yield zero. Default is 0
moransi_threshold (float, optional) – Moran’s I (autocorrelation) by which to distinguish localized from non-localized modules. Default is 0.25

Factorization Args:

kwargs – See STNMF.factorize()

Raises:

ValueError – If ste has incorrect dimensions.

Notes

If factorize is True (default), the decomposition into subunits is performed immediately with the provided Factorization Args. If set to False, the factors are initialized. The factorization is then started manually by calling factorize with applicable arguments. In that case, any Factorization Args meant for the factorization that are passed to the initialization are invalid and will raise an error.

The ste may contain masked or NaN values to speed up the decomposition.

Warning

To obtain appropriate diameters and distances, it is essential to provide a value for pixel_size or to assign the attribute later.

See also

stnmf.mf: Matrix factorization classes with additional keyword arguments
factorize: For more keyword arguments

plot(full=True, colors='hsv', cmap=None, **kwargs)

Visualize STNMF results in a figure

Parameters:

full (bool, optional) – Display the full figure. If False, omit weights and autocorrelation plots (bottom row). Default is True
colors (color, iterable, matplotlib.colors.Colormap, optional) – Single color or color sequence to differentiate localized modules. If single color, the same color is used on the plots of all localized subunits. If iterable or colormap, colors are iterated over plots of localized subunits. Default is ‘hsv’
cmap (str or matplotlib.colors.Colormap, optional) – Override colormaps for both STA and modules. By default the modules and STA plots have two different colormaps. If specified, the colormap is used for all subplots. Recommended are ‘rwb’ for convenient view (red-white-black with masked values lightseagreen) and ‘filter’ for conventional spatial contrast filter colors (black-gray-white with masked values magenta). If None, modules are visualized with ‘rwb’ and STA with ‘filter’. Default is None

Keyword Arguments:

kwargs – Further arguments may be passed to the plotting routines

Returns:

fig (matplotlib.figure.Figure) – Created figure

Warns:

PixelSizeWarning – If no scale bar will be drawn due to missing pixel size

See also

stnmf.plot.all: Create figure combining all STNMF results

flipsign(): Flip sign of modules for their average weights to be positive

sort(): Sort modules by their absolute average weight, localized first

property modules

Recovered spatial modules

Type:: numpy.ndarray

Notes

This array is a reshaped view of the matrix factorization features stnmf.mf.MF.w.

However, if the STE contains NaNs or is otherwise masked (i.e. masked is True), this array is an immutable copy that can only be modified by direct assignment.

See also

subunits: Localized subunits only
stnmf.mf.MF.w: Matrix factorization modules (features)

property weights

Recovered weights for all modules and all spikes

Type:: numpy.ndarray

Notes

This array is a view of the matrix factorization encodings stnmf.mf.MF.h.

See also

ratios: Scalar weight per subunit
stnmf.mf.MF.h: Matrix factorization weights (encodings)

property subunits

Localized subunits, i.e. subset of STNMF modules (normalized)

Type:: numpy.ndarray

property ratios

Scalar weights/contribution ratios of each localized subunit, i.e. subset of STNMF weights (averaged and normalized)

Type:: numpy.ndarray

property num_subunits

Number of localized subunits as determined by their Moran’s I autocorrelation

Type:: int

property outlines

Contour outlines of the localized subunits at contour level equivalent to 1.22 standard deviations

Type:: numpy.ndarray

See also

stnmf.spatial.contour: Fit a contour to an image array

property diameters

Diameters of the localized subunits as defined by the effective diameter of a two-sigma elliptical Gaussian fit in micrometers (μm). Only if pixel_size is set

Type:: numpy.ndarray
Warns:: PixelSizeWarning – If pixel_size is not set

See also

stnmf.spatial.ellipse: Fit a Gaussian ellipse
pixel_size: Conversion factor to micrometers (μm)

property distances

Euclidean distances of localized subunits from STA center in micrometers (μm). Only if pixel_size is set

Distances are measured from the outline centroids

Type:: numpy.ndarray
Warns:: PixelSizeWarning – If pixel_size is not set

See also

outlines: Contour outlines of the localized subunits
pixel_size: Conversion factor to micrometers (μm)

property polarities

Signs of the localized subunits at maximum intensity (positive +1 or negative -1)

Type:: numpy.ndarray

See also

flipsign: Flip sign of modules to make weights positive

property moransi

Moran’s I autocorrelation of all modules. To obtain the Moran’s I of the localized subunits only, index the attribute with localized

Type:: numpy.ndarray

property localized

Indices of localized subunits among all modules as determined by their Moran’s I autocorrelation and moransi_threshold

Type:: numpy.ndarray

desc = 'Matrix factorization'

Readable analysis name

Type:: str

init(w0='nnsvdlrc', lrc_kwargs=None)

Initialize features w

Parameters:

w0 ((n,r) array_like or {'random', 'nnsvdlrc'}, optional) – Initial features w. If array_like, serves as the initial w directly. If ‘random’ or ‘nnsvdlrd’, calls the functions from stnmf.init. Default is ‘nnsvdlrc’
lrc_kwargs (dict, optional) – Keyword arguments for low-rank correction. Ignored if w0 is not ‘nnsvdlrc’. Default is None

Raises:

ValueError – If array sizes mismatch.

property pixel_size

Pixel size in micrometers (μm) for calculation of spatial diameter and distance

Type:: float

property res

Reconstruction error (residual) based on Frobenius norm

Type:: float

reseed(seed=None)

Re-seed the random number generator (RNG)

Parameters:: seed (int or None, optional) – Random number generator (RNG) seed. If None, the RNG is initialized without a seed based on OS context. Default is None

Notes

The RNG in this class is only used if initialization is random. Calling this method will overwrite the attribute rng. It is not compatible with using a custom rng.

See also

stnmf.util.create_rng: Create an RNG instance

residual()

Re-compute reconstruction error

See also

res: Reconstruction error (residual)

property moransi_threshold

Threshold of Morans’I to distinguish localized subunits

Type:: float

See also

stnmf.spatial.moransi: Calculate the autocorrelation

property sta

Spatial profile of the spike-triggered average (STA)

Type:: numpy.ndarray

property sta_outline

Contour outline of the STA at contour level equivalent to 1.22 standard deviations.

Type:: numpy.ndarray

See also

stnmf.spatial.contour: Fit a contour to an image array

property sta_diameter

Diameter of the STA as defined by the effective diameter of a two-sigma elliptical Gaussian fit in micrometers (μm). Only if pixel_size is set

Type:: float
Warns:: PixelSizeWarning – If pixel_size is not set

See also

stnmf.spatial.ellipse: Fit a Gaussian ellipse
pixel_size: Conversion factor to micrometers (μm)

property coverage

Fraction of spatial coverage of localized subunits on the STA

Coverage is determined from the subunit and STA outlines

To avoid effects of poorly reconstructed subunits that each cover the entire area of the STA, only the non-overlapping portions across the subunits are considered. The fraction of this non-overlapping subunit area covering the STA area is the coverage factor. This measures the intersection while encouraging non-overlapping tiling of the subunits.

Type:: float

property modules_info

Collection of all module properties for all modules for easy dot- and multi-indexing

The attribute is a numpy.recarray of size r and of the following fields. It collects all properties in one combined array. This allows to multi-index properties of all or several modules at a time, structured in a numpy array.

Type:: numpy.recarray

`index`	Module index
`module`	Spatial module (not normalized)
`weight`	Average contribution weight (not normalized)
`moransi`	Moran’s I autocorrelation
`localized`	Whether the modules is considered a subunit
`polarity`	Sign of the modules
`contour`	Countour outline (for localized only)
`diameter`	Diameter (for localized only)
`distance`	Distance from STA center (for localized only)

STNMF (stnmf.STNMF)

Spatial modules and weights

Subunit attributes

Object methods

Parameter attributes

Further attributes

STNMF (`stnmf.STNMF`)