synapticonn.core.connections.SynaptiConn¶

class synapticonn.core.connections.SynaptiConn(spike_times: dict | None = None, time_unit: str = 'ms', bin_size_t: float = 1, max_lag_t: float = 100, method: str = 'cross-correlation', recording_length_t: float | None = None, srate: float | None = None, spike_id_type: type = <class 'int'>)[source]¶

Bases: SpikeManager

Base class for quantifying monosynaptic connections between neurons.

This class builds upon the SpikeManager to provide functionality for computing, analyzing, and visualizing monosynaptic connections between pairs of neurons based on their spike trains. Key features include cross-correlogram computation, synaptic strength estimation, and connection classification.

Parameters:

spike_times (dict) – Dictionary containing spike times for each unit, indexed by unit ID. Spike times should be a NumPy array of floats.
time_unit (str) – Unit of time for the spike times. Options are ‘ms’ (milliseconds) or ‘s’ (seconds).
bin_size_t (float) – Bin size for computing cross-correlograms.
max_lag_t (float) – Maximum lag to consider when computing cross-correlograms.
method (str, optional) – Method for computing synaptic strength. Default is ‘cross-correlation’. Currently, only this method is implemented, but future versions may include additional methods.
recording_length_t (float) – Duration of the recording, in the same time unit as time_unit.
srate (float) – Sampling rate of the recording in Hz.
spike_id_type (type) – Data type of spike unit identifiers. Typically int or str.

bin_size_t¶

Bin size used for cross-correlogram computations.

Type:: float

max_lag_t¶

Maximum lag used for cross-correlogram computations.

Type:: float

method¶

The method used for synaptic strength computation.

Type:: str

recording_length_t¶

Total duration of the recording, in the specified time unit.

Type:: float

srate¶

Sampling rate of the spike data, in Hz.

Type:: float

spike_id_type¶

Type of spike unit identifiers (e.g., int or str).

Type:: type

time_unit¶

Unit of time used for computations and spike data.

Type:: str

pair_synaptic_strength¶

Dictionary containing synaptic strength data for each spike pair. This is populated after running the fit or synaptic_strength methods.

Type:: dict

Notes

The SynaptiConn class is designed to process and analyze spike train data for determining monosynaptic connections.
If the spike times are provided in seconds, they are converted to milliseconds internally to maintain consistency.
The class assumes that the recording duration (recording_length_t) and time unit (time_unit) are accurately specified.

Examples

Initialize the SynaptiConn object and compute synaptic strength:

>>> synapti_conn = SynaptiConn(
...     spike_times=spike_data,
...     time_unit='ms',
...     bin_size_t=1.0,
...     max_lag_t=50.0,
...     method='cross-correlation',
...     recording_length_t=60000,
...     srate=20000
... )
>>> synapti_conn.fit(spike_pairs=[(1, 2), (3, 4)])
>>> print(synapti_conn.pair_synaptic_strength)

__init__(spike_times: dict | None = None, time_unit: str = 'ms', bin_size_t: float = 1, max_lag_t: float = 100, method: str = 'cross-correlation', recording_length_t: float | None = None, srate: float | None = None, spike_id_type: type = <class 'int'>)[source]¶: Initialize the SynaptiConn object.

Methods

`__init__`([spike_times, time_unit, ...])	Initialize the SynaptiConn object.
`add_spike_time_data`([spike_times, ...])	Add spike time data to the SpikeManager object.
`filter_connections`(connections_df[, query, ...])	Filter connections based on a query string.
`filter_spike_units`(quality_metrics[, query, ...])	Filter spike units based on quality metrics.
`fit`(**kwargs)
`get_spike_times_for_units`([...])	Retrieve spike times for the selected units.
`monosynaptic_connection_features`([n_bootstraps])	Extract connection features from synaptic strength data.
`monosynaptic_connection_types`([...])	Categorize monosynaptic connection types based on synaptic strength data output.
`plot_autocorrelogram`([spike_units])	Plot the autocorrelogram.
`plot_crosscorrelogram`([spike_pairs])	Plot the cross-correlogram for valid spike pairs.
`plot_spike_train`([spike_units])	Plot the spike train for the given spike units.
`plot_synaptic_strength`([spike_pair])	Plot the synaptic strength for the given spike pair.
`print_connection_results`([connection_types, ...])	Print the results of the synaptic strength and connection types.
`report`([spike_pairs, ...])	Compute the synaptic strength and connection types, and display a report.
`report_correlogram_settings`()	Report the bin settings.
`report_spike_units`()	Report the spike units.
`reset_pair_synaptic_strength`()	Reset the synaptic strength data.
`return_crosscorrelogram_data`([spike_pairs])	Compute and return the cross-correlogram data for valid spike pairs.
`set_bin_settings`(**kwargs)
`set_time_unit`(**kwargs)
`spike_unit_ids`()	Return the spike unit labels.
`spike_unit_labels`()	Retrieve the spike unit labels.
`spike_unit_quality`([isi_threshold_ms, ...])	Compute spike isolation quality metrics.
`synaptic_strength`(**kwargs)

Attributes

`connections_filtering`
`spike_unit_filtering`

add_spike_time_data(spike_times: dict | None = None, recording_length_t: float | None = None, time_unit: str = 'ms', srate: float | None = None, spike_id_type: type = <class 'int'>)¶

Add spike time data to the SpikeManager object.

Parameters:

spike_times (dict) – Dictionary containing spike times for each unit. Indexed by unit ID.
recording_length_t (float) – Length of the recording in time units.
time_unit (str) – Unit of time for the spike times. Default is ‘ms’. Options include ‘s’, ‘ms’.
srate (float) – Sampling rate of the recording in Hz.
spike_id_type (type) – Type of the spike unit ID. Default is int or str.

connections_filtering = False¶

filter_connections(connections_df: DataFrame, query: str | None = None, log: bool = False, overwrite: bool = False) → DataFrame[source]¶

Filter connections based on a query string.

Parameters:

connections_df (pd.DataFrame) – DataFrame containing the connection data. This DataFrame should contain the synaptic strength data for all select pairs of spike trains.
query (str) – Query string to filter the DataFrame.
log (bool) – If True, print the query string used for filtering.
overwrite (bool) – If True, overwrite the DataFrame with the filtered data.

Returns:

connections_df_filtered (pd.DataFrame) – DataFrame containing the filtered connection data.
Log
—
The log parameter is used to track the removed spike pairs with
detected monosynaptic connections. This is useful for tracking
the removed spike pairs from the original DataFrame.
The output is saved in a log file in the
’removed_spikepair_connections’ folder. The file is named
’low_quality_connections_removed.log’.

filter_spike_units(quality_metrics: DataFrame, query: str | None = None, log: bool = False, overwrite: bool = False) → DataFrame¶

Filter spike units based on quality metrics.

Parameters:

quality_metrics (pd.DataFrame) – DataFrame containing the quality metrics for each spike unit. This is the dataframe outputted from the spike_unit_quality method and will be used to filter spike units.
query (str) – Query to filter spike units based on the quality metrics. This query should be a valid pandas query
log (bool) – Whether to log the filtered spike units. Default is False.
overwrite (bool) – Whether to overwrite the existing spike_times dictionary with the filtered units. Default is False.

Returns:

filtered_units_df (pd.DataFrame) – DataFrame containing the filtered spike units based on the query.
Log
—
If log is True, the method will log the removed spike units
based on the query. The log will contain the unit ID and the
query used to filter the units.
The log file will be saved in the ‘removed_spike_units’ folder
in the current working directory. The log file will be named
’low_quality_units_removed.log’.

fit(**kwargs)¶

get_spike_times_for_units(spike_units_to_collect: list | None = None) → dict¶

Retrieve spike times for the selected units.

Parameters:: spike_units_to_collect (list) – List of spike units to collect.
Returns:: filtered_spike_times – Filtered dictionary containing spike times for the selected units.
Return type:: dict

Notes

By default, this method returns all spike times if no units are specified. If specific units are specified, then the method will return the spike times for those units only.

monosynaptic_connection_features(n_bootstraps: int = 1000) → dict[source]¶

Extract connection features from synaptic strength data.

Parameters:: n_bootstraps (int) – Number of bootstraps to compute the confidence intervals.
Returns:: connection_features – Dictionary containing connection features for all pairs of spike trains.
Return type:: dict

monosynaptic_connection_types(synaptic_strength_threshold: float | None = None) → dict[source]¶

Categorize monosynaptic connection types based on synaptic strength data output.

Parameters:

synaptic_strength_threshold (float) – Threshold value for categorizing connection types. Default is None. This is used to categorize the connection types based on the synaptic strength values.

Returns:

connection_types (dict) – Dictionary containing connection types for all pairs of spike trains.
Cross-correlation method notes
——————————
Based on [1], for excitatory connections, a threshold of 5 is recommended.
For inhibitory connections, a threshold of -5 is recommended. Thresholds
can be adjusted based on the synaptic strength data.
Please see [1] for more details.

Notes

Currently, connection types are based on the synaptic strength values. This is computed using the cross-correlation method. In future versions, this will be expanded to include other types of correlation methods.

References

[1] STAR Protoc. 2024 Jun 21;5(2):103035. doi: 10.1016/j.xpro.2024.103035. Epub 2024 Apr 27.

plot_autocorrelogram(spike_units: list | None = None, **kwargs)[source]¶

Plot the autocorrelogram.

Parameters:

spike_units (list) – List of spike units to plot.
**kwargs – Additional keyword arguments passed to plot_acg.

Notes

Autocorrelograms are computed for each spike unit and plotted. The bin size and maximum lag are set by the object parameters.

plot_crosscorrelogram(spike_pairs: List[Tuple] | None = None, **kwargs: Any)[source]¶

Plot the cross-correlogram for valid spike pairs.

Parameters:

spike_pairs (List[Tuple]) – List of spike pairs to plot.
ax (Any) – Axis to plot on.
show_axes (bool) – Whether to add axis labels. Default is True.
**kwargs (Any) – Additional keyword arguments passed to plot_ccg.

plot_spike_train(spike_units: list | None = None, **kwargs: Any)[source]¶

Plot the spike train for the given spike units.

Parameters:

spike_units (list) – List of spike units to plot. If None, all spike units are plotted.
**kwargs (Any) – Additional keyword arguments passed to plot_spike_train for customizing the plot using matplotlib.

plot_synaptic_strength(spike_pair: tuple | None = None, **kwargs)[source]¶

Plot the synaptic strength for the given spike pair.

Note, this method requires the synaptic strength data to be computed first. It only plots the synaptic strength for a single pair of spike trains.

Parameters:

spike_pair (tuple) – Spike pair to plot the synaptic strength.
**kwargs – Additional keyword arguments passed to plot_ccg_synaptic_strength.

Raises:

DataError – If no synaptic strength data is found.
SpikePairError – If spike pair is not provided.
NotImplementedError – If the method is not implemented in the current package version.

print_connection_results(connection_types: dict | None = None, concise: bool = False, params: dict | None = None)[source]¶

Print the results of the synaptic strength and connection types.

Parameters:

connection_types (dict) – Dictionary containing connection types for all pairs of spike trains. This is computed using the ‘fit’ method.
concise (bool) – If True, print a concise summary of the results. If False, print a detailed summary of the results.
params (dict) – Additional parameters used for computing the model.

report(spike_pairs: List[Tuple] | None = None, synaptic_strength_threshold: float = 5, concise: bool = False, **kwargs)[source]¶

Compute the synaptic strength and connection types, and display a report.

Parameters:

spike_pairs (List[Tuple]) – List of spike pairs to compute the synaptic strength. These are tuples of pre- and post-synaptic neuron IDs. Pre-synaptic neuron ID is the first element and post-synaptic neuron ID is the second element.
synaptic_strength_threshold (float) – Threshold value for categorizing connection types. Default is 5. This is used to categorize the connection types based on the synaptic strength values.
concise (bool) – If True, print a concise summary of the results. This excludes blank lines.
**kwargs (dict, optional) –
Additional parameters for customizing the computation. Includes: - num_iterations : int

Number of iterations for computing synaptic strength (default: 1000).
- max_lag_tfloat
  Maximum lag to compute the synaptic strength (in ms, default: 25.0).
- bin_size_tfloat
  Bin size for computing the synaptic strength (in ms, default: 0.5).
- jitter_range_tfloat
  Jitter range for synaptic strength computation (in ms, default: 10.0).
- half_window_tfloat
  Half window size for synaptic strength computation (in ms, default: 5).
- n_jobsint
  Number of parallel jobs to use (default: -1, all cores).

Notes

Data is computed and displayed in a report format.

report_correlogram_settings()[source]¶: Report the bin settings.

report_spike_units()¶

Report the spike units.

Returns:: spk_unit_summary – Dictionary containing the spike unit summary. Includes the unit ID, number of spikes, and firing rate in Hz.
Return type:: dict

Notes

The spike unit summary is computed for each unit in the spike_times dictionary. Firing rates are calculated based on the total number of spikes and the recording length. If the time unit is in seconds, the firing rate is converted to Hz.

reset_pair_synaptic_strength()[source]¶: Reset the synaptic strength data.

return_crosscorrelogram_data(spike_pairs: List[Tuple] | None = None) → dict[source]¶

Compute and return the cross-correlogram data for valid spike pairs.

Parameters:: spike_pairs (List[Tuple]) – List of spike pairs to compute the cross-correlogram data.
Returns:: crosscorrelogram_data – Dictionary containing cross-correlograms and bins for all pairs of spike trains.
Return type:: dict

set_bin_settings(**kwargs)¶

set_time_unit(**kwargs)¶

spike_unit_filtering = False¶

spike_unit_ids()[source]¶: Return the spike unit labels.

spike_unit_labels()¶: Retrieve the spike unit labels.

spike_unit_quality(isi_threshold_ms=1.5, min_isi_ms=0, presence_ratio_bin_duration_sec=60, presence_ratio_mean_fr_ratio_thresh=0.0) → DataFrame¶

Compute spike isolation quality metrics.

Parameters:

isi_threshold_ms (float) – Threshold for the interspike interval (ISI) violations, in milliseconds.
min_isi_ms (float) – Minimum ISI value, in milliseconds.
presence_ratio_bin_duration_sec (float) – Duration of each bin for the presence ratio, in seconds.
presence_ratio_mean_fr_ratio_thresh (float) – Minimum mean firing rate ratio threshold for the presence ratio. This is the minimum mean firing rate that must be present in a bin for the unit to be considered “present” in that bin. By default, this is set to 0.0. This means that the unit must have at least one spike in each bin to be considered “present.”
time_unit (str) – Unit of time for the spike times. Default is ‘ms’. This is used to compute the features in the quality metrics.

Returns:

quality_metrics – DataFrame containing the quality metrics for each spike unit.

Return type:

pd.DataFrame

Notes

Quality metrics include: - isi_violations_ratio: Fraction of ISIs that violate the threshold. - isi_violations_count: Number of ISIs that violate the threshold. - isi_violations_of_total_spikes: Fraction of ISIs that violate the threshold out of total spikes. - presence_ratio: Fraction of time during a session in which a unit is spiking. - mean_firing_rate: Mean firing rate of the unit. - recording_length_sec: Length of the recording in seconds. - n_spikes: Number of spikes for the unit.

These are computed for each spike unit in the spike_times dictionary.

For further information on the quality metric calculations, see the respective functions in the quality_metrics module.

synaptic_strength(**kwargs)¶