Queries¶

Convenience functions for common queries.

If you are familiar with the neuPrint data model and the cypher query language, you can write your own queries using fetch_custom. But the functions in this file offer a convenient API for common queries.

Server Built-in Queries¶

See the Client class reference for the neuprint server’s built-in (non-cypher) queries, such as skeletons, ROI meshes, ROI connectivity, and server metadata.

General¶

`fetch_custom`(cypher[, dataset, format, client])	Make a custom cypher query.
`fetch_meta`(*[, client])	Fetch the dataset metadata.

ROIs¶

`fetch_all_rois`(*[, client])	List all ROIs in the dataset.
`fetch_primary_rois`(*[, client])	List 'primary' ROIs in the dataset.
`fetch_roi_hierarchy`([include_subprimary, ...])	Fetch the ROI hierarchy nesting relationships.

Neurons¶

`NeuronCriteria`([matchvar, bodyId, type, ...])	Neuron selection criteria.
`fetch_neurons`(criteria, *[, client])	Return properties and per-ROI synapse counts for a set of neurons.
`fetch_custom_neurons`(q, *[, client])	Return properties and per-ROI synapse counts for a set of neurons, using your own cypher query.

Connectivity¶

`fetch_simple_connections`([...])	Find connections to/from small set(s) of neurons.
`fetch_adjacencies`([sources, targets, rois, ...])	Find connections to/from large sets of neurons, with per-ROI connection strengths.
`fetch_traced_adjacencies`([export_dir, ...])	Convenience function that calls `fetch_adjacencies()` for all `Traced`, non-`cropped` neurons.
`fetch_common_connectivity`(criteria[, ...])	Find shared connections among a set of neurons.
`fetch_shortest_paths`(upstream_bodyId, ...[, ...])	Find all neurons along the shortest path between two neurons.

Synapses¶

`SynapseCriteria`([matchvar, rois, type, ...])	Synapse selection criteria.
`fetch_synapses`(neuron_criteria[, ...])	Fetch synapses from a neuron or selection of neurons.
`fetch_mean_synapses`(neuron_criteria[, ...])	Fetch per-ROI average synapse position and confidence for a set of neurons.
`fetch_synapse_connections`([source_criteria, ...])	Fetch synaptic-level connections between source and target neurons.

Mitochondria¶

`MitoCriteria`([matchvar, rois, mitoType, ...])	Mitochondrion selection criteria.
`fetch_mitochondria`(neuron_criteria[, ...])	Fetch mitochondria from a neuron or selection of neurons.
`fetch_synapses_and_closest_mitochondria`(...)	Fetch a set of synapses from a selection of neurons and also return their nearest mitocondria (by path-length within the neuron segment).
`fetch_connection_mitochondria`(...[, ...])	For a given set of source neurons and target neurons, find all synapse-level connections between the sources and targets, along with the nearest mitochondrion on the pre-synaptic side and the post-synaptic side.

Reconstruction Tools¶

`fetch_output_completeness`(criteria[, ...])	Compute an estimate of "output completeness" for a set of neurons.
`fetch_downstream_orphan_tasks`(criteria[, ...])	Fetch the set of "downstream orphans" for a given set of neurons.

Reference¶

General¶

neuprint.queries.fetch_custom(cypher, dataset='', format='pandas', *, client=None)[source]¶

Make a custom cypher query.

Alternative form of Client.fetch_custom(), as a free function. That is, fetch_custom(..., client=c) is equivalent to c.fetch_custom(...).

If client=None, the default Client is used (assuming you have created at least one Client.)

Parameters

cypher – A cypher query string
dataset –
Deprecated. Please provide your dataset as a Client constructor argument.

Which neuprint dataset to query against. If None provided, the client’s default dataset is used.
format – Either ‘pandas’ or ‘json’. Whether to load the results into a pandas DataFrame, or return the server’s raw json response as a Python dict.
client – If not provided, the global default Client will be used.

Returns

Either json or DataFrame, depending on format.

In [4]: from neuprint import fetch_custom
   ...:
   ...: q = """\
   ...: MATCH (n:Neuron)
   ...: WHERE n.bodyId = 5813027016
   ...: RETURN n.type, n.instance
   ...: """
   ...: fetch_custom(q)
Out[4]:
  n.type      n.instance
0   FB4Y  FB4Y(EB/NO1)_R

neuprint.queries.fetch_meta(*, client=None)[source]¶

Fetch the dataset metadata. Parses json fields as needed.

Returns: dict

Example

In [1]: from neuprint import fetch_meta

In [2]: meta = fetch_meta()

In [3]: list(meta.keys())
Out[3]:
['dataset',
 'info',
 'lastDatabaseEdit',
 'latestMutationId',
 'logo',
 'meshHost',
 'neuroglancerInfo',
 'neuroglancerMeta',
 'postHPThreshold',
 'postHighAccuracyThreshold',
 'preHPThreshold',
 'primaryRois',
 'roiHierarchy',
 'roiInfo',
 'statusDefinitions',
 'superLevelRois',
 'tag',
 'totalPostCount',
 'totalPreCount',
 'uuid']

ROIs¶

neuprint.queries.fetch_all_rois(*, client=None)[source]¶: List all ROIs in the dataset.

neuprint.queries.fetch_primary_rois(*, client=None)[source]¶: List ‘primary’ ROIs in the dataset. Primary ROIs do not overlap with each other.

neuprint.queries.fetch_roi_hierarchy(include_subprimary=True, mark_primary=True, format='dict', *, client=None)[source]¶

Fetch the ROI hierarchy nesting relationships.

Most ROIs in neuprint are part of a hierarchy of nested regions. The structure of the hierarchy is stored in the dataset metadata, and can be retrieved with this function.

Parameters

include_subprimary – If True, all hierarchy levels are included in the output. Otherwise, the hierarchy will only go as deep as necessary to cover all “primary” ROIs, but not any sub-primary ROIs that are contained within them.
mark_primary – If True, append an asterisk (*) to the names of “primary” ROIs in the hierarchy. Primary ROIs do not overlap with each other.
format – Either "dict", "text", or nx. Specifies whether to return the hierarchy as a dict, or as a printable text-based tree, or as a networkx.DiGraph (requires networkx).

Returns

Either dict, str, or nx.DiGraph, depending on your chosen format.

Example

In [1]: from neuprint.queries import fetch_roi_hierarchy
   ...:
   ...: # Print the first few nodes of the tree -- you get the idea
   ...: roi_tree_text = fetch_roi_hierarchy(False, True, 'text')
   ...: print(roi_tree_text[:180])
hemibrain
 +-- AL(L)*
 +-- AL(R)*
 +-- AOT(R)
 +-- CX
 |   +-- AB(L)*
 |   +-- AB(R)*
 |   +-- EB*
 |   +-- FB*
 |   +-- NO*
 |   +-- PB*
 +-- GC
 +-- GF(R)
 +-- GNG*
 +-- INP
 |

Neurons¶

neuprint.queries.fetch_neurons(criteria, *, client=None)[source]¶

Return properties and per-ROI synapse counts for a set of neurons.

Searches for a set of Neurons (or Segments) that match the given NeuronCriteria. Returns their properties, including the distibution of their synapses in all brain regions.

This implements a superset of the features on the Neuprint Explorer Find Neurons page.

Returns data in the the same format as fetch_custom_neurons(), but doesn’t require you to write cypher.

Parameters

criteria (bodyId(s), type/instance, or NeuronCriteria) – Only Neurons which satisfy all components of the given criteria are returned.
client – If not provided, the global default Client will be used.

Returns

Two DataFrames. (neurons_df, roi_counts_df)

In neurons_df, all available :Neuron columns are returned, with the following changes:

ROI boolean columns are removed

roiInfo is parsed as json data

coordinates (such as somaLocation) are provided as a list [x, y, z]

New columns input_rois and output_rois contain lists of each neuron’s ROIs.

In roi_counts_df, the roiInfo has been loadded into a table of per-neuron-per-ROI synapse counts, with separate columns for pre (outputs) and post (inputs).

Note

The roi_counts_df, the sum of the pre and post counts will be more than the total pre and post values returned in neuron_df. That is, synapses are double-counted in roi_counts_df. This is because ROIs form a hierarchical structure, so each synapse intersects more than one ROI. See fetch_roi_hierarchy() for more information.

Note

Connections which fall outside of all primary ROIs are listed via special entries using NotPrimary in place of an ROI name. The term NotPrimary is introduced by this function. It isn’t used internally by the neuprint database.

Connectivity¶

neuprint.queries.fetch_simple_connections(upstream_criteria=None, downstream_criteria=None, rois=None, min_weight=1, properties=['type', 'instance'], *, client=None)[source]¶

Find connections to/from small set(s) of neurons. Most users should prefer fetch_adjacencies() instead of this function.

Finds all connections from a set of “upstream” neurons, or to a set of “downstream” neurons, or all connections from a set of upstream neurons to a set of downstream neurons.

Note

This function is not intended to be used with very large sets of neurons. Furthermore, it does not return ROI information in a convenient format. But the simple output table it returns is sometimes convenient for small, interactive queries.

To fetch all adjacencies between a large set of neurons, see fetch_adjacencies(), which also has additional ROI-filtering options, and also returns ROI info in a separate table.

Parameters

upstream_criteria (bodyId(s), type/instance, or NeuronCriteria) – How to filter for neurons on the presynaptic side of connections.
downstream_criteria (bodyId(s), type/instance, or NeuronCriteria) – How to filter for neurons on the postsynaptic side of connections.
rois – Limit results to neuron pairs that connect in at least one of the given ROIs. Note that the total weight of each connection may include connections outside of the listed ROIs, too.
min_weight – Exclude connections whose total weight (across all ROIs) falls below this threshold.
properties – Additional columns to include in the results, for both the upstream and downstream body.
client – If not provided, the global default Client will be used.

Returns

DataFrame One row per connection, with columns for upstream (pre-synaptic) and downstream (post-synaptic) properties.

Example

In [1]: from neuprint import fetch_simple_connections
   ...: sources = [329566174, 425790257, 424379864, 329599710]
   ...: targets = [425790257, 424379864, 329566174, 329599710, 420274150]
   ...: fetch_simple_connections(sources, targets)
Out[1]:
   bodyId_pre  bodyId_post  weight                   type_pre                  type_post         instance_pre        instance_post                                       conn_roiInfo
0   329566174    425790257      43                    OA-VPM3                        APL   OA-VPM3(NO2/NO3)_R                APL_R  {'MB(R)': {'pre': 39, 'post': 39}, 'b'L(R)': {...
1   329566174    424379864      37                    OA-VPM3                 AVM03e_pct   OA-VPM3(NO2/NO3)_R  AVM03e_pct(AVM03)_R  {'SNP(R)': {'pre': 34, 'post': 34}, 'SLP(R)': ...
2   425790257    329566174      12                        APL                    OA-VPM3                APL_R   OA-VPM3(NO2/NO3)_R  {'MB(R)': {'pre': 12, 'post': 12}, 'gL(R)': {'...
3   424379864    329566174       7                 AVM03e_pct                    OA-VPM3  AVM03e_pct(AVM03)_R   OA-VPM3(NO2/NO3)_R  {'SNP(R)': {'pre': 5, 'post': 5}, 'SLP(R)': {'...
4   329599710    329566174       4  olfactory multi lvPN mALT                    OA-VPM3        mPNX(AVM06)_R   OA-VPM3(NO2/NO3)_R  {'SNP(R)': {'pre': 4, 'post': 4}, 'SIP(R)': {'...
5   329566174    329599710       1                    OA-VPM3  olfactory multi lvPN mALT   OA-VPM3(NO2/NO3)_R        mPNX(AVM06)_R  {'SNP(R)': {'pre': 1, 'post': 1}, 'SLP(R)': {'...
6   329566174    420274150       1                    OA-VPM3                 AVM03m_pct   OA-VPM3(NO2/NO3)_R  AVM03m_pct(AVM03)_R  {'SNP(R)': {'pre': 1, 'post': 1}, 'SLP(R)': {'...

neuprint.queries.fetch_adjacencies(sources=None, targets=None, rois=None, min_roi_weight=1, min_total_weight=1, include_nonprimary=False, export_dir=None, batch_size=200, properties=['type', 'instance'], *, client=None)[source]¶

Find connections to/from large sets of neurons, with per-ROI connection strengths.

Fetches the adjacency table for connections between sets of neurons, broken down by ROI. Unless include_nonprimary=True, only primary ROIs are included in the per-ROI connection table. Connections outside of the primary ROIs are labeled with the special name "NotPrimary" (which is not currently an ROI name in neuprint itself).

Note

fetch_simple_connections() has similar functionality, but that function isn’t suitable for querying large sets of neurons. However, it may be more convenient for small interactive queries.

Parameters

sources (bodyId(s), type/instance, or NeuronCriteria) – Limit results to connections from bodies that match this criteria. If None, all neurons upstream of targets will be fetched.
targets (bodyId(s), type/instance, or NeuronCriteria) – Limit results to connections to bodies that match this criteria. If None, all neurons downstream of sources will be fetched.
rois – Limit results to connections within the listed ROIs.
min_roi_weight – Limit results to connections of at least this strength within at least one of the returned ROIs.
min_total_weight –
Limit results to connections that are at least this strong when totaled across all ROIs.

Note

Even if min_roi_weight is also specified, all connections are counted towards satisfying the total weight threshold, even though some ROI entries are filtered out. Therefore, some connections in the results may appear not to satisfy min_total_weight when their per-ROI weights are totaled. That’s just because you filtered out the weak per-ROI entries.
include_nonprimary –
If True, also list per-ROI totals for non-primary ROIs (i.e. parts of the ROI hierarchy that are sub-primary or super-primary). See fetch_roi_hierarchy() for details.

Note

Since non-primary ROIs overlap with primary ROIs, then the sum of the weight column for each body pair will not be equal to the total connection strength between the bodies. (Some connections will be counted twice.)
export_dir – Optional. Export CSV files for the neuron table, connection table (total weight), and connection table (per ROI).
batch_size – For optimal performance, connections will be fetched in batches. This parameter specifies the batch size.
properties – Which Neuron properties to include in the output table.
client – If not provided, the global default Client will be used.

Returns

Two DataFrames, (neurons_df, roi_conn_df), containing a table of neuron IDs and the per-ROI connection table, respectively. See caveat above concerning non-primary ROIs.

Synapses¶

neuprint.queries.fetch_synapses(neuron_criteria, synapse_criteria=None, batch_size=10, *, client=None)[source]¶

Fetch synapses from a neuron or selection of neurons.

Parameters

neuron_criteria (bodyId(s), type/instance, or NeuronCriteria) –
Determines which bodies to fetch synapses for.

Note

Any ROI criteria specified in this argument does not affect which synapses are returned, only which bodies are inspected.
synapse_criteria (SynapseCriteria) –
Optional. Allows you to filter synapses by roi, type, confidence. See SynapseCriteria for details.

If the criteria specifies primary_only=True only primary ROIs will be returned in the results. If a synapse does not intersect any primary ROI, it will be listed with an roi of None. (Since ‘primary’ ROIs do not overlap, each synapse will be listed only once.) Otherwise, all ROI names will be included in the results. In that case, some synapses will be listed multiple times – once per intersecting ROI. If a synapse does not intersect any ROI, it will be listed with an roi of None.
batch_size – To improve performance and avoid timeouts, the synapses for multiple bodies will be fetched in batches, where each batch corresponds to N bodies. This argument sets the batch size N.
client – If not provided, the global default Client will be used.

Returns

DataFrame in which each row represent a single synapse. Unless primary_only was specified, some synapses may be listed more than once, if they reside in more than one overlapping ROI.

Example

In [1]: from neuprint import NeuronCriteria as NC, SynapseCriteria as SC, fetch_synapses
   ...: fetch_synapses(NC(type='ADL.*', rois=['FB']),
   ...:                SC(rois=['LH(R)', 'SIP(R)'], primary_only=True))
Out[1]:
        bodyId  type     roi      x      y      z  confidence
 5812983094   pre  SIP(R)  15300  25268  14043    0.992000
 5812983094   pre  SIP(R)  15300  25268  14043    0.992000
 5812983094   pre  SIP(R)  15300  25268  14043    0.992000
 5812983094   pre  SIP(R)  15300  25268  14043    0.992000
 5812983094   pre   LH(R)   5447  21281  19155    0.991000
 5812983094   pre   LH(R)   5434  21270  19201    0.995000
 5812983094   pre   LH(R)   5434  21270  19201    0.995000
 5812983094   pre   LH(R)   5434  21270  19201    0.995000
 5812983094   pre   LH(R)   5447  21281  19155    0.991000
 5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5434  21270  19201    0.995000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5434  21270  19201    0.995000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5434  21270  19201    0.995000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre   LH(R)   5434  21270  19201    0.995000
5812983094   pre   LH(R)   5447  21281  19155    0.991000
5812983094   pre  SIP(R)  15300  25268  14043    0.992000
5812983094   pre  SIP(R)  15300  25268  14043    0.992000
5812983094   pre  SIP(R)  15300  25268  14043    0.992000
5812983094   pre  SIP(R)  15300  25268  14043    0.992000
5812983094   pre  SIP(R)  15300  25268  14043    0.992000
5812983094   pre  SIP(R)  15300  25268  14043    0.992000
 764377593  post   LH(R)   8043  21587  15146    0.804000
 764377593  post   LH(R)   8057  21493  15140    0.906482
 859152522   pre  SIP(R)  13275  25499  13629    0.997000
 859152522   pre  SIP(R)  13275  25499  13629    0.997000
 859152522  post  SIP(R)  13349  25337  13653    0.818386
 859152522  post  SIP(R)  12793  26362  14202    0.926918
 859152522   pre  SIP(R)  13275  25499  13629    0.997000

neuprint.queries.fetch_mean_synapses(neuron_criteria, synapse_criteria=None, batch_size=100, *, client=None)[source]¶

Fetch per-ROI average synapse position and confidence for a set of neurons.

Parameters

neuron_criteria (bodyId(s), type/instance, or NeuronCriteria) –
Determines which bodies to fetch synapses for.

Note

Any ROI criteria specified in this argument does not affect which synapses are returned, only which bodies are inspected.
synapse_criteria (SynapseCriteria) –
Optional. Allows you to filter synapses by roi, type, confidence. See SynapseCriteria for details.

If the criteria specifies primary_only=True only primary ROIs will be returned in the results. If a synapse does not intersect any primary ROI, it will be ignored by this function.
batch_size – To improve performance and avoid timeouts, the synapses for multiple bodies will be processed in batches, where each batch corresponds to N bodies. This argument sets the batch size N.
client – If not provided, the global default Client will be used.

Returns

DataFrame in which each row contains the average synapse position and average confidence for a particular body, ROI, and synapse type (pre/post).

Example

In [1]: from neuprint import fetch_mean_synapses, SynapseCriteria as SC
   ...: fetch_mean_synapses('LC10', SC(type='pre', rois=['LO(R)', 'AOTU(R)']))
Out[1]:
        bodyId      roi type  count             x             y             z  confidence
0    1017448980  AOTU(R)  pre    141  10691.737305  30304.355469  15508.099609    0.956000
1    1017448980    LO(R)  pre      2   8530.500000  18898.000000  34857.000000    0.954500
2    1017090133  AOTU(R)  pre     49  10560.469727  31032.041016  14548.550781    0.956286
3    1017090133    LO(R)  pre     52   3737.115479  19489.923828  29530.000000    0.949673
4    1017094185  AOTU(R)  pre    157  10922.248047  30326.693359  15349.484375    0.959185
..          ...      ...  ...    ...           ...           ...           ...         ...
772  1262602271    LO(R)  pre      3   5178.666504  14584.666992  23227.333984    0.957333
773  1291573712  AOTU(R)  pre    273  11285.106445  31097.925781  15987.640625    0.954418
774  1291573712    LO(R)  pre      3   6482.000000  13845.333008  25962.666016    0.936333
775  5812993252  AOTU(R)  pre     17  11110.706055  30892.470703  17220.175781    0.960471
776  5812993252    LO(R)  pre     39   7758.897461  11723.154297  28176.794922    0.943128

neuprint.queries.fetch_synapse_connections(source_criteria=None, target_criteria=None, synapse_criteria=None, min_total_weight=1, batch_size=10000, *, client=None)[source]¶

Fetch synaptic-level connections between source and target neurons.

Note

Use this function if you need information about individual synapse connections, such as their exact positions or confidence scores. If you’re just interested in aggregate neuron-to-neuron connection info (including connection strengths and ROI intersections), see fetch_simple_connections() and fetch_adjacencies(), which are faster and have more condensed outputs than this function.

Note

If you experience timeouts while running this function, try reducing the batch_size setting.

Parameters

source_criteria (bodyId(s), type/instance, or NeuronCriteria) –
Criteria to by which to filter source (pre-synaptic) neurons. If omitted, all Neurons will be considered as possible sources.

Note

Any ROI criteria specified in this argument does not affect which synapses are returned, only which bodies are inspected.
target_criteria (bodyId(s), type/instance, or NeuronCriteria) –
Criteria to by which to filter target (post-synaptic) neurons. If omitted, all Neurons will be considered as possible targets.

Note

Any ROI criteria specified in this argument does not affect which synapses are returned, only which bodies are inspected.
synapse_criteria (SynapseCriteria) –
Optional. Allows you to filter synapses by roi or confidence. The same criteria is used to filter both pre and post sides of the connection, except for the rois – see note below. By default, SynapseCriteria(primary_only=True) is used, with no additional filters.

If primary_only is specified in the criteria, then the resulting roi_pre and roi_post columns will contain a single string (or None) in every row.

Otherwise, the roi columns will contain a list of ROIs for every row. (Primary ROIs do not overlap, so every synapse resides in only one (or zero) primary ROI.) See SynapseCriteria for details.

Note

Any rois specified in your synapse_criteria will be used to filter the target (post-synaptic) side of the synapse connection, but not the pre-synaptic side. So in the rare cases where the pre and post synapses reside on different sides of an ROI boundary, the connection is associated with the post-synaptic ROI.

That’s consistent with neuprint’s conventions for ROI assignment in the neuron-to-neuron ConnectsTo: relationship, and thus ensures that this function returns synapse counts that are consistent with fetch_adjacencies().
min_total_weight –
If the total weight of the connection between two bodies is not at least this strong, don’t include the synapses for that connection in the results.

Note

This filters for total connection weight, regardless of the weight within any particular ROI. So, if your SynapseCriteria limits results to a particular ROI, but two bodies connect in multiple ROIs, then the number of synapses returned for the two bodies may appear to be less than min_total_weight. That’s because you filtered out the synapses in other ROIs.
batch_size – To avoid timeouts and improve performance, the synapse connections will be fetched in batches. The batching strategy is to process each body one at a time, and if it has lots of connection partners, split the request across several batches to avoid timeouts that could arise from a large request. This argument specifies the maximum size of each batch in the inner loop. Larger batches are more efficient to fetch, but increase the likelihood of timeouts.
client – If not provided, the global default Client will be used.

Returns

DataFrame in which each row represents a single synaptic connection between an upstream (pre-synaptic) body and downstream (post-synaptic) body.

Synapse locations are listed in columns [x_pre, y_pre, z_pre] and [x_post, y_post, z_post] for the upstream and downstream synapses, respectively.

The roi_pre and roi_post columns will contain either strings or lists-of-strings, depending on the primary_only synapse criteria as described above.

Example

In [1]: from neuprint import fetch_synapse_connections, SynapseCriteria as SC
   ...: fetch_synapse_connections(792368888, None, SC(rois=['PED(R)', 'SMP(R)'], primary_only=True))
Out[1]:
    bodyId_pre  bodyId_post roi_pre roi_post  x_pre  y_pre  z_pre  x_post  y_post  z_post  confidence_pre  confidence_post
  792368888    754547386  PED(R)   PED(R)  14013  27747  19307   13992   27720   19313           0.996         0.401035
  792368888    612742248  PED(R)   PED(R)  14049  27681  19417   14044   27662   19408           0.921         0.881487
  792368888   5901225361  PED(R)   PED(R)  14049  27681  19417   14055   27653   19420           0.921         0.436177
  792368888   5813117385  SMP(R)   SMP(R)  23630  29443  16297   23634   29437   16279           0.984         0.970746
  792368888   5813083733  SMP(R)   SMP(R)  23630  29443  16297   23634   29419   16288           0.984         0.933871
  792368888   5813058320  SMP(R)   SMP(R)  18662  34144  12692   18655   34155   12697           0.853         0.995000
  792368888   5812981989  PED(R)   PED(R)  14331  27921  20099   14351   27928   20085           0.904         0.877373
  792368888   5812981381  PED(R)   PED(R)  14331  27921  20099   14301   27919   20109           0.904         0.567321
  792368888   5812981381  PED(R)   PED(R)  14013  27747  19307   14020   27747   19285           0.996         0.697836
  792368888   5812979314  PED(R)   PED(R)  14331  27921  20099   14329   27942   20109           0.904         0.638362
 792368888    424767514  PED(R)   PED(R)  14331  27921  20099   14324   27934   20085           0.904         0.985734
 792368888    424767514  PED(R)   PED(R)  14013  27747  19307   14020   27760   19294           0.996         0.942831
 792368888    424767514  PED(R)   PED(R)  14049  27681  19417   14040   27663   19420           0.921         0.993586
 792368888    331662710  SMP(R)   SMP(R)  23630  29443  16297   23644   29429   16302           0.984         0.996389
 792368888   1196854070  PED(R)   PED(R)  14331  27921  20099   14317   27935   20101           0.904         0.968408
 792368888   1131831702  SMP(R)   SMP(R)  23630  29443  16297   23651   29434   16316           0.984         0.362952

Mitochondria¶

neuprint.queries.fetch_mitochondria(neuron_criteria, mito_criteria=None, batch_size=10, *, client=None)[source]¶

Fetch mitochondria from a neuron or selection of neurons.

Parameters

neuron_criteria (bodyId(s), type/instance, or NeuronCriteria) –
Determines which bodies from which to fetch mitochondria.

Note

Any ROI criteria specified in this argument does not affect which mitochondria are returned, only which bodies are inspected.
mito_criteria (MitoCriteria) –
Optional. Allows you to filter mitochondria by roi, mitoType, size. See MitoCriteria for details.

If the criteria specifies primary_only=True only primary ROIs will be returned in the results. If a mitochondrion does not intersect any primary ROI, it will be listed with an roi of None. (Since ‘primary’ ROIs do not overlap, each mitochondrion will be listed only once.) Otherwise, all ROI names will be included in the results. In that case, some mitochondria will be listed multiple times – once per intersecting ROI. If a mitochondria does not intersect any ROI, it will be listed with an roi of None.
batch_size – To improve performance and avoid timeouts, the mitochondria for multiple bodies will be fetched in batches, where each batch corresponds to N bodies.
client – If not provided, the global default Client will be used.

Returns

DataFrame in which each row represent a single synapse. If primary_only=False was specified in mito_criteria, some mitochondria may be listed more than once, if they reside in more than one overlapping ROI.

Example

In [1]: from neuprint import NeuronCriteria as NC, SynapseCriteria as SC, fetch_synapses
   ...:
   ...: # Consider only neurons which innervate EB
   ...: nc = NC(type='ExR.*', rois=['EB'])
   ...:
   ...: # But return only large mitos from those neurons that reside in the FB or LAL(R)
   ...: mc = MC(rois=['FB', 'LAL(R)'], size=100_000)
   ...: fetch_mitochondria(nc, mc)
Out[1]:
          bodyId mitoType     roi      x      y      z     size          r0         r1        r2
0     1136865339     dark  LAL(R)  15094  30538  23610   259240  101.586632  31.482559  0.981689
1     1136865339     dark  LAL(R)  14526  30020  23464   297784   67.174950  36.328964  0.901079
2     1136865339     dark  LAL(R)  15196  30386  23336   133168   54.907104  25.761894  0.912385
3     1136865339     dark  LAL(R)  14962  30126  23184   169776   66.780258  27.168915  0.942389
4     1136865339     dark  LAL(R)  15004  30252  23164   148528   69.316467  24.082989  0.951892
...          ...      ...     ...    ...    ...    ...      ...         ...        ...       ...
2807  1259386264     dark      FB  18926  24632  21046   159184   99.404472  21.919170  0.984487
2808  1259386264     dark      FB  22162  24474  22486   127968   94.380531  20.547171  0.985971
2809  1259386264   medium      FB  19322  24198  21952  1110888  116.050323  66.010017  0.954467
2810  1259386264     dark      FB  19272  23632  21728   428168   87.865768  40.370171  0.944690
2811  1259386264     dark      FB  19208  23442  21602   141928   53.694149  29.956501  0.919831

[2812 rows x 10 columns]

neuprint.queries.fetch_synapses_and_closest_mitochondria(neuron_criteria, synapse_criteria=None, *, batch_size=10, client=None)[source]¶

Fetch a set of synapses from a selection of neurons and also return their nearest mitocondria (by path-length within the neuron segment).

Note

Some synapses have no nearby mitochondria, possibly due to fragmented segmentation around the synapse point. Such synapses ARE NOT RETURNED by this function. They’re omitted.

Parameters

neuron_criteria (bodyId(s), type/instance, or NeuronCriteria) –
Determines which bodies to fetch synapses for.

Note

Any ROI criteria specified in this argument does not affect which synapses are returned, only which bodies are inspected.
synapse_criteria (SynapseCriteria) –
Optional. Allows you to filter synapses by roi, type, confidence. See SynapseCriteria for details.

If the criteria specifies primary_only=True only primary ROIs will be returned in the results. If a synapse does not intersect any primary ROI, it will be listed with an roi of None. (Since ‘primary’ ROIs do not overlap, each synapse will be listed only once.) Otherwise, all ROI names will be included in the results. In that case, some synapses will be listed multiple times – once per intersecting ROI. If a synapse does not intersect any ROI, it will be listed with an roi of None.
batch_size – To improve performance and avoid timeouts, the synapses for multiple bodies will be fetched in batches, where each batch corresponds to N bodies. This argument sets the batch size N.
client – If not provided, the global default Client will be used.

Returns

DataFrame in which each row represent a single synapse, along with information about its closest mitochondrion. Unless primary_only was specified, some synapses may be listed more than once, if they reside in more than one overlapping ROI.

The synapse coordinates will be returned in columns x,y,z, and the mitochondria centroids will be stored in columns mx,my,mz.

The distance column indicates the distance from the synapse coordinate to the nearest edge of the mitochondria (not the centroid), as traveled along the neuron dendrite (not euclidean distance). The distance is given in voxel units (e.g. 8nm), not nanometers. See release notes concerning the estimated error of these measurements.

Example

In [1]: from neuprint import fetch_synapses_and_closest_mitochondria, NeuronCriteria as NC, SynapseCriteria as SC
   ...: fetch_synapses_and_closest_mitochondria(NC(type='ExR2'), SC(type='pre'))
Out[1]:
          bodyId type     roi      x      y      z  confidence mitoType    distance    size     mx     my     mz          r0         r1        r2
0     1136865339  pre      EB  25485  22873  19546       0.902   medium  214.053040  410544  25544  23096  19564  105.918625  35.547806  0.969330
1     1136865339  pre      EB  25985  25652  23472       0.930     dark   19.313709   90048  26008  25646  23490   81.459419  21.493509  0.988575
2     1136865339  pre  LAL(R)  14938  29149  22604       0.826     dark  856.091736  495208  14874  29686  22096   64.086639  46.906826  0.789570
3     1136865339  pre      EB  24387  23583  20681       0.945     dark   78.424950  234760  24424  23536  20752   80.774353  29.854616  0.957713
4     1136865339  pre   BU(R)  16909  25233  17658       0.994     dark  230.588562  215160  16862  25418  17824   42.314690  36.891937  0.628753
...          ...  ...     ...    ...    ...    ...         ...      ...         ...     ...    ...    ...    ...         ...        ...       ...
4508   787762461  pre   BU(R)  16955  26697  17300       0.643     dark  105.765854  176952  16818  26642  17200   91.884338  22.708199  0.975422
4509   787762461  pre  LAL(R)  15008  28293  25995       0.747     dark  112.967644  446800  15044  28166  26198  176.721512  27.971079  0.992517
4510   787762461  pre      EB  23468  24073  20882       0.757     dark  248.562714   92536  23400  23852  20760   39.696674  27.490204  0.860198
4511   787762461  pre   BU(R)  18033  25846  20393       0.829     dark   38.627419  247640  18028  25846  20328   73.585144  29.661413  0.929788
4512   787762461  pre      EB  22958  24565  20340       0.671     dark  218.104736  120880  23148  24580  20486   39.752777  32.047478  0.821770

[4513 rows x 16 columns]

neuprint.queries.fetch_connection_mitochondria(source_criteria, target_criteria, synapse_criteria=None, min_total_weight=1, *, client=None)[source]¶

For a given set of source neurons and target neurons, find all synapse-level connections between the sources and targets, along with the nearest mitochondrion on the pre-synaptic side and the post-synaptic side.

Returns a table similar to fetch_synapse_connections(), but with extra _pre and _post columns to describe the nearest mitochondria to the pre/post synapse in the connection. If a given synapse has no nearby mitochondrion, the corresponding mito columns will be populated with NaN values. (This is typically much more likely to occur on the post-synaptic side than the pre-synaptic side.)

Arguments are the same as fetch_synapse_connections()

Note

This function does not employ a custom cypher query to minimize the data fetched from the server. Instead, it makes multiple calls to the server and merges the results on the client.

Parameters

source_criteria (bodyId(s), type/instance, or NeuronCriteria) –
Criteria to by which to filter source (pre-synaptic) neurons. If omitted, all Neurons will be considered as possible sources.

Note

Any ROI criteria specified in this argument does not affect which synapses are returned, only which bodies are inspected.
target_criteria (bodyId(s), type/instance, or NeuronCriteria) –
Criteria to by which to filter target (post-synaptic) neurons. If omitted, all Neurons will be considered as possible sources.

Note

Any ROI criteria specified in this argument does not affect which synapses are returned, only which bodies are inspected.
synapse_criteria (SynapseCriteria) –
Optional. Allows you to filter synapses by roi, type, confidence. The same criteria is used to filter both pre and post sides of the connection. By default, SynapseCriteria(primary_only=True) is used.

If primary_only is specified in the criteria, then the resulting roi_pre and roi_post columns will contain a single string (or None) in every row.

Otherwise, the roi columns will contain a list of ROIs for every row. (Primary ROIs do not overlap, so every synapse resides in only one (or zero) primary ROI.) See SynapseCriteria for details.
min_total_weight –
If the total weight of the connection between two bodies is not at least this strong, don’t include the synapses for that connection in the results.

Note

This filters for total connection weight, regardless of the weight within any particular ROI. So, if your SynapseCriteria limits results to a particular ROI, but two bodies connect in multiple ROIs, then the number of synapses returned for the two bodies may appear to be less than min_total_weight. That’s because you filtered out the synapses in other ROIs.
client – If not provided, the global default Client will be used.

Reconstruction Tools¶

neuprint.queries.fetch_output_completeness(criteria, complete_statuses=['Traced'], batch_size=1000, *, client=None)[source]¶

Compute an estimate of “output completeness” for a set of neurons. Output completeness is defined as the fraction of post-synaptic connections which belong to ‘complete’ neurons, as defined by their status.

Parameters

criteria (bodyId(s), type/instance, or NeuronCriteria) – Defines the set of neurons for which output completeness should be computed.
complete_statuses – A list of neuron statuses should be considered complete for the purposes of this function.

Returns

DataFrame with columns ['bodyId', 'completeness', 'traced_weight', 'untraced_weight', 'total_weight']

For the purposes of these results, any statuses in the set of complete_statuses are considered ‘traced’.

neuprint.queries.fetch_downstream_orphan_tasks(criteria, complete_statuses=['Traced'], *, client=None)[source]¶

Fetch the set of “downstream orphans” for a given set of neurons.

Returns a single DataFrame, where the downstream orphans have been sorted by the weight of the connection, and their cumulative contributions to the overall output-completeness of the upstream neuron is also given.

That is, if you started tracing orphans from this DataFrame in order, then the cum_completeness column indicates how complete the upstream body is after each orphan becomes traced.

Parameters: criteria (bodyId(s), type/instance, or NeuronCriteria) – Determines the set of “upstream” bodies for which downstream orphans should be identified.
Returns: DataFrame, where bodyId_pre contains the upstream bodies you specified via criteria, and bodyId_post contains the list of downstream orphans.

Example

In [1]: orphan_tasks = fetch_downstream_orphan_tasks(NC(status='Traced', cropped=False, rois=['PB']))

In [1]: orphan_tasks.query('cum_completeness < 0.2').head(10)
Out[1]:
       bodyId_pre  bodyId_post  orphan_weight status_post  total_weight  orig_traced_weight  orig_untraced_weight  orig_completeness  cum_orphan_weight  cum_completeness
  759685279    759676733              2      Assign          7757                1427                  6330           0.183963                  2          0.184221
  759685279    913193340              1        None          7757                1427                  6330           0.183963                  3          0.184350
  759685279    913529796              1        None          7757                1427                  6330           0.183963                  4          0.184479
  759685279    913534416              1        None          7757                1427                  6330           0.183963                  5          0.184607
1002507170   1387701052              1        None           522                 102                   420           0.195402                  1          0.197318
 759685279    790382544              1        None          7757                1427                  6330           0.183963                  6          0.184736
 759685279    851023555              1      Assign          7757                1427                  6330           0.183963                  7          0.184865
 759685279    974908767              2        None          7757                1427                  6330           0.183963                  9          0.185123
 759685279   1252526211              1        None          7757                1427                  6330           0.183963                 10          0.185252
 759685279   1129418900              1        None          7757                1427                  6330           0.183963                 11          0.185381