crantpy.queries.connections module

crantpy.queries.connections module#

This module provides functions for querying synaptic connectivity in the CRANTb dataset. Adapted from fafbseg-py (Philipp Schlegel) and the-BANC-fly-connectome (Jasper Phelps).

Function Overview#

This module contains four main functions for connectivity analysis, each serving different use cases:

get_synapses()

Returns individual synaptic connections as a detailed DataFrame.

Use when you need: - Raw synapse-level data with all available columns (coordinates, scores, etc.) - Fine-grained analysis of individual synaptic connections - Custom aggregation or filtering of synapses - Access to synapse metadata (synapse_size, coordinates, quality scores)

Returns: DataFrame with one row per synapse

get_adjacency()

Returns a structured adjacency matrix showing connection strengths.

Use when you need: - Matrix-based connectivity analysis - Network analysis with standard matrix operations - Symmetric connectivity matrices for undirected analysis - Integration with graph theory libraries (NetworkX, igraph) - Direct input for clustering or community detection algorithms

Returns: DataFrame adjacency matrix (neurons x neurons)

get_connectivity()

Returns aggregated connectivity as a simple edge list.

Use when you need: - High-level connectivity overview between neurons - Partner analysis (finding strongest connections) - Simple edge lists for network visualization - Quick connectivity summaries without detailed synapse info - Input for graph visualization tools (Cytoscape, Gephi)

Returns: DataFrame with columns [pre, post, weight]

get_synapse_counts()

Returns summary statistics of synaptic connections per neuron.

Use when you need: - Quick overview of neuron connectivity profiles - Total incoming and outgoing connection counts - Comparative analysis of neuron connectivity levels - Filtering neurons by connectivity thresholds - Summary statistics for large neuron populations

Returns: DataFrame with columns [pre, post] indexed by neuron ID

crantpy.queries.connections.attach_synapses(neurons, pre=True, post=True, threshold=1, min_size=None, materialization='latest', clean=True, max_distance=10000.0, update_ids=True, dataset=None)[source]#

Attach synapses as connectors to skeleton neurons.

This function fetches synapses for the given neuron(s) and maps them to the closest node on each skeleton using a KD-tree. The synapses are attached as a .connectors table with columns for connector_id, x, y, z, type (pre/post), partner_id, and node_id.

Adapted from fafbseg-py (Philipp Schlegel) to work with CRANTb data.

Parameters:

  • neurons (navis.TreeNeuron or navis.NeuronList) – Skeleton neuron(s) to attach synapses to. Must be TreeNeuron objects with node coordinates.

  • pre (bool, default True) – Whether to fetch and attach presynapses (outputs) for the given neurons.

  • post (bool, default True) – Whether to fetch and attach postsynapses (inputs) for the given neurons.

  • threshold (int, default 1) – Minimum number of synapses required between neuron pairs to be included.

  • min_size (int, optional) – Minimum synapse size for filtering.

  • materialization (str, default 'latest') – Materialization version to use. Either ‘latest’ or ‘live’.

  • clean (bool, default True) – Whether to perform cleanup of synapse data: - Remove autapses (self-connections) - Remove connections involving neuron ID 0 (background) - Remove synapses that are too far from skeleton nodes (see max_distance)

  • max_distance (float, default 10000.0) – Maximum distance (in nanometers) between a synapse and its nearest skeleton node. Synapses further than this are removed if clean=True. The default of 10um helps filter out spurious synapse annotations far from the actual neuron.

  • update_ids (bool, default True) – Whether to automatically update outdated root IDs to their latest versions before querying. This ensures accurate results even after segmentation edits. Uses efficient per-ID caching to minimize overhead for repeated queries. Set to False only if you’re certain all IDs are current (faster but risky).

  • dataset (str, optional) – Dataset to use for queries.

Returns:

The same neuron(s) with .connectors table attached. The connectors table includes columns: - connector_id: Unique ID for each synapse (sequential) - x, y, z: Synapse coordinates in nanometers - type: ‘pre’ for presynapses, ‘post’ for postsynapses - partner_id: Root ID of the partner neuron - node_id: ID of the skeleton node closest to this synapse

Note: The input neurons are modified in place and also returned.

Return type:

navis.TreeNeuron or navis.NeuronList

Raises:

  • TypeError – If neurons is not a TreeNeuron or NeuronList of TreeNeurons.

  • ValueError – If both pre and post are False.

Examples

>>> import crantpy as cp
>>> # Get a skeleton neuron
>>> skeleton = cp.get_l2_skeleton(576460752664524086)
>>>
>>> # Attach synapses to it
>>> skeleton = cp.attach_synapses(skeleton)
>>>
>>> # View the connectors table
>>> print(skeleton.connectors.head())
>>>
>>> # Get only presynapses
>>> skeleton = cp.attach_synapses(skeleton, post=False)
>>>
>>> # Filter distant synapses more aggressively
>>> skeleton = cp.attach_synapses(skeleton, max_distance=5000)
>>>
>>> # Skip ID updates for faster queries (use only if IDs are known to be current)
>>> skeleton = cp.attach_synapses(skeleton, update_ids=False)

See also

get_synapses

Fetch synapse data without attaching to neurons.

Notes

  • This function modifies the input neurons in place by adding/updating the .connectors attribute.

  • Synapses are mapped to skeleton nodes using scipy’s KDTree for efficient nearest neighbor search.

  • The connector_id is a sequential integer starting from 0, not the original synapse ID from the database.

  • If a neuron already has a .connectors table, it will be overwritten.

  • Synapse coordinates are automatically converted from pixels to nanometers to match skeleton coordinate system (using SCALE_X=8, SCALE_Y=8, SCALE_Z=42).

  • When update_ids=True (default), IDs are automatically updated with efficient caching

crantpy.queries.connections.get_adjacency(pre_ids=None, post_ids=None, threshold=1, min_size=None, materialization='latest', symmetric=False, clean=True, update_ids=True, dataset=None)[source]#

Construct an adjacency matrix from synaptic connections between neurons.

This function queries the synapses table to get connections between specified pre- and post-synaptic neurons, then constructs an adjacency matrix showing the number of synapses between each pair.

Parameters:

  • pre_ids (int, str, list, NeuronCriteria, optional) – Pre-synaptic neuron root IDs or criteria. If None, all pre-synaptic neurons in the dataset will be included.

  • post_ids (int, str, list, NeuronCriteria, optional) – Post-synaptic neuron root IDs or criteria. If None, all post-synaptic neurons in the dataset will be included.

  • threshold (int, default 1) – Minimum number of synapses required between a pair to be included in the adjacency matrix.

  • min_size (int, optional) – Minimum size for filtering synapses before constructing adjacency matrix.

  • materialization (str, default 'latest') – Materialization version to use. ‘latest’ (default) or ‘live’ for live table.

  • symmetric (bool, default False) – If True, return a symmetric adjacency matrix with the same set of IDs on both rows and columns. The neuron set includes all neurons that appear in the filtered synapses data (union of all pre- and post-synaptic neurons). This provides a complete view of connectivity among all neurons involved in the queried connections. If False (default), rows represent pre-synaptic neurons and columns represent post-synaptic neurons from the actual synapses data.

  • clean (bool, default True) – Whether to perform cleanup of the underlying synapse data: - Remove autapses (self-connections) - Remove connections involving neuron ID 0 (background) This parameter is passed to get_synapses().

  • update_ids (bool, default True) – Whether to automatically update outdated root IDs to their latest versions before querying. This ensures accurate results even after segmentation edits. Uses efficient per-ID caching to minimize overhead for repeated queries. Set to False only if you’re certain all IDs are current (faster but risky).

  • dataset (str, optional) – Dataset to use for the query.

Returns:

An adjacency matrix where each entry [i, j] represents the number of synapses from neuron i (pre-synaptic) to neuron j (post-synaptic). Rows are pre-synaptic neurons, columns are post-synaptic neurons.

Return type:

pd.DataFrame

Examples

>>> import crantpy as cp
>>> # Get adjacency between specific neurons
>>> adj = cp.get_adjacency(pre_ids=[576460752641833774], post_ids=[576460752777916050])
>>>
>>> # Get adjacency with minimum threshold
>>> adj = cp.get_adjacency(pre_ids=[576460752641833774], post_ids=[576460752777916050], threshold=3)
>>>
>>> # Get symmetric adjacency matrix
>>> adj = cp.get_adjacency(pre_ids=[576460752641833774], post_ids=[576460752777916050], symmetric=True)
>>>
>>> # Get adjacency matrix with autapses included
>>> adj = cp.get_adjacency(pre_ids=[576460752641833774], post_ids=[576460752777916050], clean=False)
>>>
>>> # Skip ID updates for faster queries (use only if IDs are known to be current)
>>> adj = cp.get_adjacency(pre_ids=[576460752641833774], post_ids=[576460752777916050], update_ids=False)

Notes

  • This function uses get_synapses() internally to retrieve synaptic connections

  • If both pre_ids and post_ids are None, this will query all synapses in the dataset

  • The threshold parameter filters connection pairs, not individual synapses

  • When symmetric=True, the resulting matrix includes all neurons that appear in the filtered synapses data, ensuring complete connectivity visualization

  • When symmetric=False, the matrix may be rectangular with different neuron sets for rows (pre-synaptic) and columns (post-synaptic)

  • When clean=True (default), autapses and background connections are removed

  • When update_ids=True (default), IDs are automatically updated with efficient caching

crantpy.queries.connections.get_connectivity(neuron_ids, upstream=True, downstream=True, threshold=1, min_size=None, materialization='latest', clean=True, update_ids=True, dataset=None)[source]#

Fetch connectivity information for given neuron(s) in CRANTb.

This function retrieves synaptic connections for the specified neurons, returning a table of connections with pre-synaptic neurons, post-synaptic neurons, and synapse counts.

Parameters:

  • neuron_ids (int, str, list, NeuronCriteria) – Neuron root ID(s) to query connectivity for. Can be a single ID, list of IDs, or NeuronCriteria object.

  • upstream (bool, default True) – Whether to fetch upstream (incoming) connectivity to the query neurons.

  • downstream (bool, default True) – Whether to fetch downstream (outgoing) connectivity from the query neurons.

  • threshold (int, default 1) – Minimum number of synapses required between a pair to be included in the results.

  • min_size (int, optional) – Minimum size for filtering synapses before aggregating connections.

  • materialization (str, default 'latest') – Materialization version to use. ‘latest’ (default) or ‘live’ for live table.

  • clean (bool, default True) – Whether to perform cleanup of the underlying synapse data: - Remove autapses (self-connections) - Remove connections involving neuron ID 0 (background) This parameter is passed to get_synapses().

  • update_ids (bool, default True) – Whether to automatically update outdated root IDs to their latest versions before querying. This ensures accurate results even after segmentation edits. Uses efficient per-ID caching to minimize overhead for repeated queries. Set to False only if you’re certain all IDs are current (faster but risky).

  • dataset (str, optional) – Dataset to use for the query.

Returns:

Connectivity table with columns: - ‘pre’: pre-synaptic neuron ID - ‘post’: post-synaptic neuron ID - ‘weight’: number of synapses between the pair

Return type:

pd.DataFrame

Raises:

ValueError – If both upstream and downstream are False.

Examples

>>> import crantpy as cp
>>> # Get all connections for a neuron
>>> conn = cp.get_connectivity(576460752641833774)
>>>
>>> # Get only downstream connections with threshold
>>> conn = cp.get_connectivity(576460752641833774, upstream=False, threshold=3)
>>>
>>> # Get connectivity for multiple neurons
>>> conn = cp.get_connectivity([576460752641833774, 576460752777916050])
>>>
>>> # Skip ID updates for faster queries (use only if IDs are known to be current)
>>> conn = cp.get_connectivity(576460752641833774, update_ids=False)

Notes

  • This function uses get_synapses() internally to retrieve synaptic connections

  • Results are aggregated by pre-post neuron pairs and sorted by synapse count

  • When clean=True, autapses and background connections are removed

  • When update_ids=True (default), IDs are automatically updated with efficient caching

crantpy.queries.connections.get_synapse_counts(neuron_ids, threshold=1, min_size=None, materialization='latest', clean=True, update_ids=True, dataset=None)[source]#

Get synapse counts (pre and post) for given neuron IDs in CRANTb.

This function returns the total number of presynaptic and postsynaptic connections for each specified neuron, aggregated across all their partners.

Parameters:

  • neuron_ids (int, str, list, NeuronCriteria) – Neuron root ID(s) to get synapse counts for. Can be a single ID, list of IDs, or NeuronCriteria object.

  • threshold (int, default 1) – Minimum number of synapses required between a pair to be counted towards the total. Pairs with fewer synapses are excluded.

  • min_size (int, optional) – Minimum size for filtering individual synapses before counting.

  • materialization (str, default 'latest') – Materialization version to use. ‘latest’ (default) or ‘live’ for live table.

  • clean (bool, default True) – Whether to perform cleanup of the underlying synapse data: - Remove autapses (self-connections) - Remove connections involving neuron ID 0 (background) This parameter is passed to get_connectivity().

  • update_ids (bool, default True) – Whether to automatically update outdated root IDs to their latest versions before querying. This ensures accurate results even after segmentation edits. Uses efficient per-ID caching to minimize overhead for repeated queries. Set to False only if you’re certain all IDs are current (faster but risky).

  • dataset (str, optional) – Dataset to use for the query.

Returns:

DataFrame with columns: - index: neuron IDs - ‘pre’: number of presynaptic connections (outgoing) - ‘post’: number of postsynaptic connections (incoming)

Return type:

pd.DataFrame

Examples

>>> import crantpy as cp
>>> # Get synapse counts for a single neuron
>>> counts = cp.get_synapse_counts(576460752641833774)
>>>
>>> # Get counts for multiple neurons with threshold
>>> counts = cp.get_synapse_counts([576460752641833774, 576460752777916050], threshold=3)
>>>
>>> # Skip ID updates for faster queries (use only if IDs are known to be current)
>>> counts = cp.get_synapse_counts(576460752641833774, update_ids=False)

Notes

  • This function uses get_connectivity() internally to get connection data

  • Counts represent the number of distinct synaptic partners, not individual synapses

  • The threshold is applied at the connection level (pairs of neurons)

  • When update_ids=True (default), IDs are automatically updated with efficient caching

crantpy.queries.connections.get_synapses(pre_ids=None, post_ids=None, threshold=1, min_size=None, materialization='latest', return_pixels=True, clean=True, update_ids=True, dataset=None)[source]#

Fetch synapses for a given set of pre- and/or post-synaptic neuron IDs in CRANTb.

Parameters:

  • pre_ids (int, str, list of int/str, NeuronCriteria, optional) – Pre-synaptic neuron root ID(s) to include. Can be a single ID, list of IDs, or NeuronCriteria object.

  • post_ids (int, str, list of int/str, NeuronCriteria, optional) – Post-synaptic neuron root ID(s) to include. Can be a single ID, list of IDs, or NeuronCriteria object.

  • threshold (int, default 1) – Minimum number of synapses required for a partner to be retained. Currently we don’t know what a good threshold is.

  • min_size (int, optional) – Minimum size for filtering synapses. Currently we don’t know what a good size is.

  • materialization (str, default 'latest') – Materialization version to use. ‘latest’ (default) or ‘live’ for live table.

  • return_pixels (bool, default True) – Whether to convert coordinate columns from nanometers to pixels. If True (default), coordinates in ctr_pt_position, pre_pt_position, and post_pt_position are converted using dataset scale factors. If False, coordinates remain in nanometer units.

  • clean (bool, default True) – Whether to perform cleanup of the synapse data: - Remove autapses (self-connections) - Remove connections involving neuron ID 0 (background)

  • update_ids (bool, default True) – Whether to automatically update outdated root IDs to their latest versions before querying. This ensures accurate results even after segmentation edits. Uses efficient per-ID caching to minimize overhead for repeated queries. Set to False only if you’re certain all IDs are current (faster but risky).

  • dataset (str, optional) – Dataset to use for the query.

Returns:

DataFrame of synaptic connections.

Return type:

pd.DataFrame

Raises:

ValueError – If neither pre_ids nor post_ids are provided.

Notes

  • When update_ids=True (default), outdated root IDs are automatically updated using supervoxel IDs from annotations when available for fast, reliable updates

  • ID updates are cached per-ID, so repeated queries with overlapping IDs are efficient

  • Updated IDs are used for the query, but the original IDs are not modified in place

See also

update_ids

Manually update root IDs to their latest versions

Contents