osl_dynamics.analysis.tinda#

Temporal Interval Network Density Analysis (TINDA).

This module contains functions for calculating the density profile (i.e., fractional occupancy over) in any interval between events it is originally intended to use it on an HMM state time course to ask questions like what is the density of state j in the first and second part of the interval between visits to state i.

See also

Example script applying TINDA to simulated HMM data.

Module Contents#

Functions#

find_intervals(tc_hot)

Find intervals (periods where tc_hot is zero) in a hot vector.

split_intervals(intervals[, n_bins])

Splits each interval into nbin equally sized bins.

split_interval_duration(durations[, interval_range, ...])

Split interval durations into bins based on their duration.

compute_fo_stats(tc_sec, divided_intervals[, ...])

Compute sums and weighted averages of time courses in each interval.

collate_stats(stats, field[, all_to_all, ignore_elements])

Collate list of stats (e.g., of different states) into a single array.

tinda(tc[, density_of, n_bins, interval_mode, ...])

Compute time-in-state density and sum for each interval.

optimise_sequence(fo_density[, metric_to_use])

Optimise the sequence to maximal circularity.

plot_cycle(ordering, fo_density, edges[, new_figure, ...])

Plot state network as circular diagram with arrows.
osl_dynamics.analysis.tinda.find_intervals(tc_hot)[source]#

Find intervals (periods where tc_hot is zero) in a hot vector.

Parameters:

tc_hot (array_like) – Hot vector (i.e., binary vector) of shape (n_samples,) or (n_samples, 1). For example, a hot vector of a state time course of shape (n_samples, n_states).

Returns:

  • intervals (list) – List of tuples of start and end indices of intervals.

  • durations (array_like) – Array of durations of intervals (in samples).

osl_dynamics.analysis.tinda.split_intervals(intervals, n_bins=2)[source]#

Splits each interval into nbin equally sized bins.

Parameters:

  • intervals (list) – List of tuples of start and end indices of intervals.

  • n_bins (int, optional) – Number of bins to split each interval into.

Returns:

  • divided_intervals (list) – List the same length as intervals (minus dropped intervals, see below), with each element being a list of tuples of start and end indices of bins.

  • bin_sizes (list) – List of bin sizes (in samples), one per interval.

  • drop_mask (array_like) – Array of zeros and ones indicating whether the interval was dropped because it was smaller than n_bins.

osl_dynamics.analysis.tinda.split_interval_duration(durations, interval_range=None, mode='sample', sampling_frequency=None)[source]#

Split interval durations into bins based on their duration.

Parameters:

  • durations (array_like) – Array of durations of intervals (in samples).

  • interval_range (array_like, optional) – Array of bin edges (in samples, seconds, or percentiles) to split durations into bins are defined as [>=interval_range[i], <interval_range[i+1]). If None, all durations are in the same bin.

  • mode (str, optional) – Mode of interval_range, either "sample" (e.g., [4, 20, 100]), "perc" (e.g., range(20,100,20)), or "sec" (e.g., [0, 0.01, 0.1, 1, np.inf]). If "sec", sfreq must be provided.

  • sampling_frequency (float, optional) – Sampling frequency (in Hz) of the data, only used if mode is "sec".

Returns:

  • mask (list) – List of arrays of zeros and ones indicating whether the interval was in the bin.

  • interval_range (array_like) – Array of bin edges (in samples) used to split durations into bins.

osl_dynamics.analysis.tinda.compute_fo_stats(tc_sec, divided_intervals, interval_mask=None, return_all_intervals=False)[source]#

Compute sums and weighted averages of time courses in each interval.

Parameters:

  • tc_sec (array_like) – Time course of shape (n_samples, n_states).

  • divided_intervals (list) – List with each element corresponding to an interval, each itself being a list of tuples of start and end indices of interval bins.

  • interval_mask (array_like, optional) – Array of zeros and ones indicating whether the interval was in the bin.

  • return_all_intervals (bool, optional) – Whether to return the density/sum of all intervals in addition to the interval averages/sums.

Returns:

  • interval_weighted_avg (array_like) – Array of weighted averages of time courses in each interval of shape (n_states, n_bins, n_interval_ranges).

  • interval_sum (array_like) – Array of sums of time courses in each interval of shape (n_states, n_bins, n_interval_ranges).

  • interval_weighted_avg_all (list) – List of length n_interval_ranges with each element an array of weighted averages of time courses in each interval of shape (n_states, n_bins, n_intervals). None if return_all_intervals=False (default).

  • interval_sum_all (list) – List of length n_interval_ranges with each element an array of sums of time courses in each interval of shape (n_states, n_bins, n_intervals). None if return_all_intervals=False.

osl_dynamics.analysis.tinda.collate_stats(stats, field, all_to_all=False, ignore_elements=None)[source]#

Collate list of stats (e.g., of different states) into a single array.

Parameters:

  • stats (list) – List of stats (dict) for each state. Each element is a dictionary with keys that at least should include “field” (e.g., interval_wavg), that is the output of compute_fo_stats.

  • field (str) – Field of stats to collate, e.g., "interval_wavg", "interval_sum".

  • all_to_all (bool, optional) – Whether the density_of was used to compute the stats (in which case the first 2 dimensions are not n_states x n_states). Default is False.

  • ignore_elements (list, optional) – List of indices in stats to ignore (i.e. because they don’t contain binary events).

Returns:

collated_stat – The collated stat (n_interval_states, n_density_states, n_bins, n_interval_ranges). If all_to_all=False (default) (i.e., when the density is computed for all states using all states’ intervals), then the first two dimensions are n_states and the diagonal is np.nan.

Return type:

array_like

osl_dynamics.analysis.tinda.tinda(tc, density_of=None, n_bins=2, interval_mode=None, interval_range=None, sampling_frequency=None, return_all_intervals=False)[source]#

Compute time-in-state density and sum for each interval.

Parameters:

  • tc (array_like) – Time courses of shape (n_samples, n_states) define intervals from will use the same time courses to compute density of when density_of is None. Can be a list of time courses (e.g. state time courses for each individual).

  • density_of (array_like, optional) – Time course of shape (n_samples, n_states) to compute density of if None (default), density is computed for all columns of tc.

  • n_bins (int, optional) – Number of bins to divide each interval into (default 2).

  • interval_mode (str, optional) – Mode of interval_range, either "sample" (default), “sec” (seconds) or “perc” (percentile). To interpret the interval range as seconds, sfreq must be provided.

  • interval_range (array_like, optional) – Array of bin edges (in samples, seconds, or percentiles) used to split durations into bins (default None), e.g. np.arange(0, 1, 0.1) for 100 ms bins.

  • sampling_frequency (float, optional) – Sampling frequency of tc (in Hz), only used if interval_mode="sec".

  • return_all_intervals (bool, optional) – Whether to return the density/sum of all intervals in addition to the interval averages/sums. If True, will return a list of arrays in stats[i]['all_interval_wavg'/'all_interval_sum'], each corresponding to an interval range.

Returns:

  • fo_density (array_like) – Time-in-state densities array of shape (n_interval_states, n_density_states, n_bins, n_interval_ranges). n_interval_states is the number of states in the interval time courses (i.e., tc); n_density_states is the number of states in the density time courses (i.e., density_of). If density_of is None, n_density_states is the same as n_interval_states. If tc is a list of time courses (e.g., state time courses for multiple individuals), then an extra dimension is appended for the individuals.

  • fo_sum (array_like) – Same as fo_density, but with time-in-state sums instead of densities.

  • stats (dict) – Dictionary of stats, including

    • durations: interval durations in samples.

    • intervals: start/end samples for each interval (intervals).

    • interval_wavg: the weighted average (i.e, time-in-state density) over all interval.

    • interval_sum: the sum (i.e., time-in-state) over all intervals.

    • divided_intervals: the bin edges for each interval.

    • bin_sizes: the bin sizes for each interval.

    • interval_range: the interval range (in samples).

    • all_interval_wavg: unaveraged interval densities (only if return_all_intervals=True).

    • all_interval_sum: unaveraged interval sums (only if return_all_intervals=True).

osl_dynamics.analysis.tinda.optimise_sequence(fo_density, metric_to_use=0)[source]#

Optimise the sequence to maximal circularity.

This function reads in the mean pattern of differential fractional occupancy and computes the optimal display for a sequential circular plot visualization.

Parameters:

  • fo_density (array_like) – Time-in-state densities array of shape (n_interval_states, n_density_states, 2, n_sessions).

  • metric (int, optional) –

    Metric to use for optimisation:

    • 0: mean FO asymmetry.

    • 1: proportional FO asymmetry (i.e. asymmetry as a proportion of a baseline - which time spend in the state).

    • 2: proportional FO asymmetry using global baseline FO, rather than a individual-specific baseline.

Returns:

best_sequence – List of best sequence of states to plot (in order of counterclockwise rotation).

Return type:

list

osl_dynamics.analysis.tinda.plot_cycle(ordering, fo_density, edges, new_figure=False, color_scheme=None)[source]#

Plot state network as circular diagram with arrows.

Parameters:

  • ordering (list) – List of best sequence of states to plot (in order of counterclockwise rotation).

  • fo_density (array_like) – Time-in-state densities array of shape (n_interval_states, n_density_states, 2, (n_interval_ranges,) n_sessions).

  • edges (array_like) – Array of zeros and ones indicating whether the connection should be plotted.

  • new_figure (bool, optional) – Whether to create a new figure (default is False).

  • color_scheme (array_like, optional) – Array of size (K,3) color scheme to use for plotting (default is None). If None, will use the default color scheme from the matlab code.