Client

All communication to the neuPrint server is peformed using a Client object, which holds your authorization credentials, the dataset name to use, and other connection settings. (To obtain your authorization credentials, see the Quickstart.)

For commonly used queries, see Queries. Or you can implement your own cypher queries using fetch_custom().

Example

In [1]: from neuprint import Client, fetch_custom, fetch_neurons

In [2]: # Create a default client.
   ...: # It will be implicitly used for all subsequent queries as
   ...: long as it remains the only client you've created.
   ...: c = Client('neuprint.janelia.org', dataset='hemibrain:v1.2.1')

In [3]: fetch_custom("""\
   ...:     MATCH (n: Neuron)
   ...:     WHERE n.status = "Traced" AND NOT n.cropped
   ...:     RETURN n.bodyId as bodyId, n.type as type, n.instance as instance
   ...:     ORDER BY n.type, n.instance
   ...: """)
Out[3]:
           bodyId        type             instance
0       511051477   5th s-LNv            5th s-LNv
1       947590512  ADL01a_pct  ADL01a_pct(ADL01)_R
2      1100952886  ADL01b_pct  ADL01b_pct(ADL01)_R
3      1228484534  ADL01b_pct  ADL01b_pct(ADL01)_R
4      1290563000  ADL01b_pct  ADL01b_pct(ADL01)_R
...           ...         ...                  ...
21658  2346523421        None                 None
21659  2397377415        None                 None
21660  2429314661        None                 None
21661  2464541644        None                 None
21662  2404203061        None                 None

[21663 rows x 3 columns]

Tip

All cypher queries are logged, but the messages are not shown in the console by default. To display them, see setup_debug_logging().

default_client()	Obtain the default Client object to use.
set_default_client(client)	Set (or overwrite) the default Client.
clear_default_client()	Unset the default Client, leaving no default in place.
list_all_clients()	List all Client objects in the program.
setup_debug_logging()	Simple debug logging configuration.
disable_debug_logging()

Client methods correspond directly to built-in neuprintHTTP API endpoints.

Client(server[, dataset, token, verify])	Client object for interacting with the neuprint database.
Client.fetch_custom(cypher[, dataset, format])	Query the neuprint server with a custom Cypher query.
Client.fetch_available()	Fetch the list of REST API endpoints supported by the server.
Client.fetch_help()	Fetch auto-generated REST API documentation, as YAML text.
Client.fetch_server_info()	Returns whether or not the server is public.
Client.fetch_version()	Returns the version of the neuPrintHTTP server.
Client.fetch_database()	Fetch the address of the neo4j database that the neuprint server is using.
Client.fetch_datasets([reload_cache])	Fetch basic information about the available datasets on the server.
Client.fetch_instances()	Fetch secondary data instances avaiable through neupint http
Client.fetch_db_version()	Fetch the database version
Client.fetch_profile()	Fetch basic information about your user profile, including your access level.
Client.fetch_token()	Fetch your user authentication token.
Client.fetch_daily_type([format])	Return information about today's cell type of the day.
Client.fetch_roi_completeness([format])	Fetch the pre-computed traced "completeness" statistics for each primary ROI in the dataset.
Client.fetch_roi_connectivity([format])	Fetch the pre-computed connectivity statistics between primary ROIs in the dataset.
Client.fetch_roi_mesh(roi[, export_path])	Fetch a mesh for the given ROI, in .obj format.
Client.fetch_skeleton(body[, heal, ...])	Fetch the skeleton for a neuron or segment.
Client.fetch_raw_keyvalue(instance, key)	Fetch a value from the neuprintHTTP server.
Client.post_raw_keyvalue(instance, key, value)	Post a value from the neuprintHTTP server.

class neuprint.client.Client(server, dataset=None, token=None, verify=True)

Client object for interacting with the neuprint database.

When you create the first Client, it becomes the default Client to be used with all neuprint-python functions if you don’t explicitly specify one. But if you create multiple Client objects, the default client is cleared and you must explicitly pass a client parameter to all query functions.

Parameters:

• server – URL of neuprintHttp server

• token – neuPrint token. Either pass explitily as an argument or set as NEUPRINT_APPLICATION_CREDENTIALS environment variable. Your token can be retrieved by clicking on your account in the NeuPrint web interface.

• verify – If True (default), enforce signed credentials.

• dataset – The dataset to run all queries against, e.g. ‘hemibrain’. If not provided, the server will use a default dataset for all queries.

fetch_available()

Fetch the list of REST API endpoints supported by the server.

fetch_custom(cypher, dataset='', format='pandas')

Query the neuprint server with a custom Cypher query.

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.

Returns:

Either json or DataFrame, depending on format.

fetch_daily_type(format='pandas')

Return information about today’s cell type of the day.

The server updates the completeness numbers each day. A different cell type is randomly picked and an exemplar is chosen from this type.

Returns:

If format='json', a dictionary is returned with keys ['info', 'connectivity', 'skeleton']. If format='pandas', three values are returned: (info, connectivity, skeleton), where connectivity and skeleton are DataFrames.

fetch_database()

Fetch the address of the neo4j database that the neuprint server is using.

fetch_datasets(reload_cache=False)

Fetch basic information about the available datasets on the server.

Parameters:

reload_cache – The result from each unique neuprint server is cached locally and re-used by all Clients, but you can invalidate the entire cache by setting reload_cache to True, causing it to be repopulated during this call.

Returns:

dict, keyed by dataset name

fetch_db_version()

Fetch the database version

fetch_help()

Fetch auto-generated REST API documentation, as YAML text.

fetch_instances()

Fetch secondary data instances avaiable through neupint http

fetch_neuron_keys()

Returns all available :Neuron properties in the database. Cached.

fetch_profile()

Fetch basic information about your user profile, including your access level.

fetch_raw_keyvalue(instance, key)

Fetch a value from the neuprintHTTP server. The data address is given by both the instance name and key. (For admins and experts only.)

fetch_roi_completeness(format='pandas')

Fetch the pre-computed traced “completeness” statistics for each primary ROI in the dataset.

The completeness statistics indicate how many synapses belong to Traced neurons.

Note

These results are not computed on-the-fly. They are computed periodically and cached.

fetch_roi_connectivity(format='pandas')

Fetch the pre-computed connectivity statistics between primary ROIs in the dataset.

Note

These results are not computed on-the-fly. They are computed periodically and cached.

fetch_roi_mesh(roi, export_path=None)

Fetch a mesh for the given ROI, in .obj format.

Parameters:

• roi – Name of an ROI

• export_path – Optional. Writes the .obj file to the given path.

Returns:

bytes The contents of the fetched .obj mesh file.

Note

ROI meshes are intended for visualization only. (They are not suitable for quantitative analysis.)

fetch_server_info()

Returns whether or not the server is public.

fetch_skeleton(body, heal=False, export_path=None, format='pandas', with_distances=False)

Fetch the skeleton for a neuron or segment.

Parameters:

• body (int) – A neuron or segment ID

• heal (bool) –

  If True and the skeleton is fragmented, ‘heal’ it by connecting its fragments into a single tree. The fragments are joined by selecting the minimum spanning tree after joining all fragments via their pairwise nearest neighbors. See heal_skeleton() for more details.

  If you want the healing procedure to refrain from connecting very distant fragments, set heal to a maximum allowed distance, e.g. heal=1000.0

• format (str) – Either ‘pandas’, ‘swc’ (similar to CSV), or ‘nx’ (networkx.DiGraph).

• export_path (str) – Optional. Writes the .swc file to disk. (SWC format is written, regardless of the returned format.)

• with_distances – Only valid when format is pandas or nx. If True, a ‘distance’ column (or edge attribute) will be added to the dataframe (or nx.Graph), indicating the distances from each node to its parent node. In DataFrame results, root nodes will be assigned a distance of np.inf. Distances are computed AFTER healing is performed. Distances will not be present in any exported SWC file.

Returns:

Either a string (swc), a DataFrame (pandas), or networkx.DiGraph (nx).

See also

• heal_skeleton()

• skeleton_df_to_nx()

• skeleton_df_to_swc()

fetch_token()

Fetch your user authentication token.

Note

This method just echoes the token back to you for debug purposes. To obtain your token for the first time, use the neuprint explorer web UI to login and obtain your token as explained elsewhere in this documentation.

fetch_version()

Returns the version of the neuPrintHTTP server.

post_raw_keyvalue(instance, key, value)

Post a value from the neuprintHTTP server. The data address is given by both the instance name and key. (For admins and experts only.)

neuprint.client.default_client()

Obtain the default Client object to use. This function returns a separate copy of the default client for each thread (and process).

There’s usually no need to call this function. It is automatically called by all query functions if you haven’t passed in an explict client argument.

neuprint.client.set_default_client(client)

Set (or overwrite) the default Client.

There’s usually no need to call this function. It’s is automatically called when your first Client is created, but you can call it again to replace the default.

neuprint.client.clear_default_client()

Unset the default Client, leaving no default in place.

neuprint.client.list_all_clients()

List all Client objects in the program.

neuprint.client.setup_debug_logging()

Simple debug logging configuration. Useful for interactive terminal sessions.

Warning

Replaces your current logging setup. If you’ve already set up logging for your app, don’t call this function. Enable neuprint debug logging via:

import logging
logging.getLogger('neuprint.client').setLevel(logging.DEBUG)

To disable cypher logging again, increase the logging severity threshold:

import logging
logging.getLogger('neuprint.client').setLevel(logging.INFO)

Example

In [1]: from neuprint.client import setup_debug_logging
   ...: from neuprint import fetch_neurons, NeuronCriteria as NC
   ...:
   ...: setup_debug_logging()
   ...: neuron_df, roi_df = fetch_neurons(NC(type='MBON.*', rois=['MB(R)']))
[2020-01-30 08:48:20,367] DEBUG Performing cypher query against dataset 'hemibrain:v1.2.1':
    MATCH (n :Neuron)
    // -- Basic conditions for segment 'n' --
    WHERE
      n.type =~ 'MBON.*'
      AND (n.`MB(R)`)
    RETURN n
    ORDER BY n.bodyId

neuprint.client.disable_debug_logging()