nsim.analysesN package¶

Submodules¶

nsim.analysesN.epochs module¶

Functions to identify pseudo-stationary epochs, where a timeseries has low ‘variability’. There is flexibility to give your own function to define ‘variability’ in the way you want, or you can use the default.

An example of a ‘variability’ function is given based on Blenkinsop2012, using centroid frequency and height of spectral peak to define ‘variability’.

functions:: epochs Find pseudo-stationary epochs, based on any defn of ‘variability’. epochs_distributed Same as above, but compute all channels in parallel. epochs_joint Find epochs where x% of channels are simultaneously stationary. variability_fp Example 2D variability function, extending Blenkinsop2012.
See also: Blenkinsop et al. (2012) The dynamic evolution of focal-onset: epilepsies - combining theoretical and clinical observations

nsim.analysesN.epochs.epochs(ts, variability=None, threshold=0.0, minlength=1.0, plot=True)¶

Identify “stationary” epochs within a time series, based on a continuous measure of variability. Epochs are defined to contain the points of minimal variability, and to extend as wide as possible with variability not exceeding the threshold.

Parameters:

Timeseries of m variables, shape (n, m). (ts) –
(optional) Timeseries of shape (n, m, q), giving q scalar (variability) – measures of the variability of timeseries ts near each point in time. (if None, we will use variability_fp()) Epochs require the mean of these to be below the threshold.
The maximum variability permitted in stationary epochs. (threshold) –
Shortest acceptable epoch length (in seconds) (minlength) –
bool Whether to display the output (plot) –

Returns: (variability, allchannels_epochs): variability: as above allchannels_epochs: (list of) list of tuples For each variable, a list of tuples (start, end) that give the starting and ending indices of stationary epochs. (epochs are inclusive of start point but not the end point)

nsim.analysesN.epochs.epochs_distributed(ts, variability=None, threshold=0.0, minlength=1.0, plot=True)¶

Same as epochs(), but computes channels in parallel for speed.

(Note: This requires an IPython cluster to be started first,: e.g. on a workstation type ‘ipcluster start’)

Identify “stationary” epochs within a time series, based on a continuous measure of variability. Epochs are defined to contain the points of minimal variability, and to extend as wide as possible with variability not exceeding the threshold.

Parameters:

Timeseries of m variables, shape (n, m). (ts) –
(optional) Timeseries of shape (n, m, q), giving q scalar (variability) – measures of the variability of timeseries ts near each point in time. (if None, we will use variability_fp()) Epochs require the mean of these to be below the threshold.
The maximum variability permitted in stationary epochs. (threshold) –
Shortest acceptable epoch length (in seconds) (minlength) –
bool Whether to display the output (plot) –

Returns: (variability, allchannels_epochs): variability: as above allchannels_epochs: (list of) list of tuples For each variable, a list of tuples (start, end) that give the starting and ending indices of stationary epochs. (epochs are inclusive of start point but not the end point)

nsim.analysesN.epochs.epochs_joint(ts, variability=None, threshold=0.0, minlength=1.0, proportion=0.75, plot=True)¶

Identify epochs within a multivariate time series where at least a certain proportion of channels are “stationary”, based on a previously computed variability measure.

(Note: This requires an IPython cluster to be started first,: e.g. on a workstation type ‘ipcluster start’)

Parameters:

Timeseries of m variables, shape (n, m). (ts) –
(optional) Timeseries of shape (n, m), giving a scalar (variability) – measure of the variability of timeseries ts near each point in time. (if None, we will use variability_fp())
The maximum variability permitted in stationary epochs. (threshold) –
Shortest acceptable epoch length (in seconds) (minlength) –
Require at least this fraction of channels to be "stationary" (proportion) –
bool Whether to display the output (plot) –

Returns: (variability, joint_epochs): joint_epochs: list of tuples A list of tuples (start, end) that give the starting and ending indices of time epochs that are stationary for at least proportion of channels. (epochs are inclusive of start point but not the end point)

nsim.analysesN.epochs.variability_fp(ts, freqs=None, ncycles=6, plot=True)¶

Example variability function. Gives two continuous, time-resolved measures of the variability of a time series, ranging between -1 and 1. The two measures are based on variance of the centroid frequency and variance of the height of the spectral peak, respectively. (Centroid frequency meaning the power-weighted average frequency) These measures are calculated over sliding time windows of variable size. See also: Blenkinsop et al. (2012) The dynamic evolution of focal-onset

epilepsies - combining theoretical and clinical observations

Parameters:	Timeseries of m variables, shape (n, m). Assumed constant timestep. (ts) – (optional) List of frequencies to examine. If None, defaults to (freqs) – 50 frequency bands ranging 1Hz to 60Hz, logarithmically spaced. Window size, in number of cycles of the centroid frequency. (ncycles) – bool Whether to display the output (plot) –
Returns:	variability Timeseries of shape (n, m, 2) variability[:, :, 0] gives a measure of variability between -1 and 1 based on variance of centroid frequency. variability[:, :, 1] gives a measure of variability between -1 and 1 based on variance of maximum power.

nsim.analysesN.misc module¶

Miscelaneous analyses that apply to an ensemble of many time series

nsim.analysesN.misc.first_return_times(dts, c=None, d=0.0)¶

For an ensemble of time series, return the set of all time intervals between successive returns to value c for all instances in the ensemble. If c is not given, the default is the mean across all times and across all time series in the ensemble.

Parameters:	(DistTimeseries) (dts) – c (float) – Optional target value (default is the ensemble mean value) d (float) – Optional min distance from c to be attained between returns
Returns:	array of time intervals (Can take the mean of these to estimate the expected first return time for the whole ensemble)

nsim.analysesN.phase module¶

Various phase analyses that apply to an ensemble of many oscillators

nsim.analysesN.phase.circmean(dts, axis=2)¶: Circular mean phase

nsim.analysesN.phase.circstd(dts, axis=2)¶: Circular standard deviation

nsim.analysesN.phase.periods(dts, phi=0.0)¶

For an ensemble of oscillators, return the set of periods lengths of all successive oscillations of all oscillators.

An individual oscillation is defined to start and end when the phase passes phi (by default zero) after completing a full cycle.

If the timeseries of an oscillator phase begins (or ends) exactly at phi, then the first (or last) oscillation will be included.

Parameters:	dts (DistTimeseries) – where dts.shape[1] is 1 (single output variable representing phase) and axis 2 ranges over multiple realizations of the oscillator. phi=0.0 – float A single oscillation starts and ends at phase phi (by default zero).

nsim.analysesN.plots module¶

Various plotting functions for a distributed timeseries

nsim.analysesN.plots.phase_histogram(dts, times, nbins=30, colormap=<matplotlib.colors.LinearSegmentedColormap object>)¶

Plot a polar histogram of a phase variable’s probability distribution :param dts: DistTimeseries with axis 2 ranging over separate instances of an

oscillator (time series values are assumed to represent an angle)

Parameters:	times (float or sequence of floats) – The target times at which to plot the distribution nbins (int) – number of histogram bins colormap –

nsim.analysesN.plots.plot(dts, title=None, points=None, show=True)¶

Plot a distributed timeseries :param dts (DistTimeseries): :param title (str, optional): :param points: Limit the number of time points plotted.

If specified, will downsample to use this total number of time points, and only fetch back the necessary points to the client for plotting.

Returns:	fig

Module contents¶

nsim.analysesN.plot(dts, title=None, points=None, show=True)¶

Plot a distributed timeseries :param dts (DistTimeseries): :param title (str, optional): :param points: Limit the number of time points plotted.

If specified, will downsample to use this total number of time points, and only fetch back the necessary points to the client for plotting.

Returns:	fig

nsim.analysesN.phase_histogram(dts, times, nbins=30, colormap=<matplotlib.colors.LinearSegmentedColormap object>)¶

Plot a polar histogram of a phase variable’s probability distribution :param dts: DistTimeseries with axis 2 ranging over separate instances of an

oscillator (time series values are assumed to represent an angle)

Parameters:	times (float or sequence of floats) – The target times at which to plot the distribution nbins (int) – number of histogram bins colormap –

nsim.analysesN.periods(dts, phi=0.0)¶

For an ensemble of oscillators, return the set of periods lengths of all successive oscillations of all oscillators.

An individual oscillation is defined to start and end when the phase passes phi (by default zero) after completing a full cycle.

If the timeseries of an oscillator phase begins (or ends) exactly at phi, then the first (or last) oscillation will be included.

Parameters:	dts (DistTimeseries) – where dts.shape[1] is 1 (single output variable representing phase) and axis 2 ranges over multiple realizations of the oscillator. phi=0.0 – float A single oscillation starts and ends at phase phi (by default zero).

nsim.analysesN.circmean(dts, axis=2)¶: Circular mean phase

nsim.analysesN.circstd(dts, axis=2)¶: Circular standard deviation

nsim.analysesN.variability_fp(ts, freqs=None, ncycles=6, plot=True)¶

Example variability function. Gives two continuous, time-resolved measures of the variability of a time series, ranging between -1 and 1. The two measures are based on variance of the centroid frequency and variance of the height of the spectral peak, respectively. (Centroid frequency meaning the power-weighted average frequency) These measures are calculated over sliding time windows of variable size. See also: Blenkinsop et al. (2012) The dynamic evolution of focal-onset

epilepsies - combining theoretical and clinical observations

Parameters:	Timeseries of m variables, shape (n, m). Assumed constant timestep. (ts) – (optional) List of frequencies to examine. If None, defaults to (freqs) – 50 frequency bands ranging 1Hz to 60Hz, logarithmically spaced. Window size, in number of cycles of the centroid frequency. (ncycles) – bool Whether to display the output (plot) –
Returns:	variability Timeseries of shape (n, m, 2) variability[:, :, 0] gives a measure of variability between -1 and 1 based on variance of centroid frequency. variability[:, :, 1] gives a measure of variability between -1 and 1 based on variance of maximum power.

nsim.analysesN.epochs(ts, variability=None, threshold=0.0, minlength=1.0, plot=True)¶

Identify “stationary” epochs within a time series, based on a continuous measure of variability. Epochs are defined to contain the points of minimal variability, and to extend as wide as possible with variability not exceeding the threshold.

Parameters:

Timeseries of m variables, shape (n, m). (ts) –
(optional) Timeseries of shape (n, m, q), giving q scalar (variability) – measures of the variability of timeseries ts near each point in time. (if None, we will use variability_fp()) Epochs require the mean of these to be below the threshold.
The maximum variability permitted in stationary epochs. (threshold) –
Shortest acceptable epoch length (in seconds) (minlength) –
bool Whether to display the output (plot) –

Returns: (variability, allchannels_epochs): variability: as above allchannels_epochs: (list of) list of tuples For each variable, a list of tuples (start, end) that give the starting and ending indices of stationary epochs. (epochs are inclusive of start point but not the end point)

nsim.analysesN.epochs_distributed(ts, variability=None, threshold=0.0, minlength=1.0, plot=True)¶

Same as epochs(), but computes channels in parallel for speed.

(Note: This requires an IPython cluster to be started first,: e.g. on a workstation type ‘ipcluster start’)

Identify “stationary” epochs within a time series, based on a continuous measure of variability. Epochs are defined to contain the points of minimal variability, and to extend as wide as possible with variability not exceeding the threshold.

Parameters:

Timeseries of m variables, shape (n, m). (ts) –
(optional) Timeseries of shape (n, m, q), giving q scalar (variability) – measures of the variability of timeseries ts near each point in time. (if None, we will use variability_fp()) Epochs require the mean of these to be below the threshold.
The maximum variability permitted in stationary epochs. (threshold) –
Shortest acceptable epoch length (in seconds) (minlength) –
bool Whether to display the output (plot) –

Returns: (variability, allchannels_epochs): variability: as above allchannels_epochs: (list of) list of tuples For each variable, a list of tuples (start, end) that give the starting and ending indices of stationary epochs. (epochs are inclusive of start point but not the end point)

nsim.analysesN.epochs_joint(ts, variability=None, threshold=0.0, minlength=1.0, proportion=0.75, plot=True)¶

Identify epochs within a multivariate time series where at least a certain proportion of channels are “stationary”, based on a previously computed variability measure.

(Note: This requires an IPython cluster to be started first,: e.g. on a workstation type ‘ipcluster start’)

Parameters:

Timeseries of m variables, shape (n, m). (ts) –
(optional) Timeseries of shape (n, m), giving a scalar (variability) – measure of the variability of timeseries ts near each point in time. (if None, we will use variability_fp())
The maximum variability permitted in stationary epochs. (threshold) –
Shortest acceptable epoch length (in seconds) (minlength) –
Require at least this fraction of channels to be "stationary" (proportion) –
bool Whether to display the output (plot) –

Returns: (variability, joint_epochs): joint_epochs: list of tuples A list of tuples (start, end) that give the starting and ending indices of time epochs that are stationary for at least proportion of channels. (epochs are inclusive of start point but not the end point)

nsim.analysesN.first_return_times(dts, c=None, d=0.0)¶

For an ensemble of time series, return the set of all time intervals between successive returns to value c for all instances in the ensemble. If c is not given, the default is the mean across all times and across all time series in the ensemble.

Parameters:	(DistTimeseries) (dts) – c (float) – Optional target value (default is the ensemble mean value) d (float) – Optional min distance from c to be attained between returns
Returns:	array of time intervals (Can take the mean of these to estimate the expected first return time for the whole ensemble)