API reference

The following is the public API (Application Programming Interface) for CoCoTools. Any module, class or function not listed here should be considered a private implementation detailed and is subject to change without notice in future releases.

Query-related functions

cocotools.multi_map_ebunch(search_type, subset=False)

Construct and return ebunch from data for several BrainMaps.

Also return the BrainMaps for which queries failed.

search_type : string

‘Mapping’ or ‘Connectivity’

subset : sequence or string (optional)

Subset of BrainMaps to query. Default is to query all BrainMaps in CoCoMac. If a string is supplied, it must be the name of a text file with one BrainMap per line.

big_ebunch : list of tuples

Each tuple specifies a source and target node and edge attributes.

failures : list of strings

These are the BrainMaps for which no data were acquired.

Querying a BrainMap for which there is only Mapping data using the Connectivity search type would result in its being a failure. Failures can also result from CoCoMac server errors.

The term ebunch, borrowed from NetworkX, refers to a sequence of graph theory edges.

Integrated primary projections are returned for Connectivity queries, and primary relations are returned for Mapping queries.

cocotools.query_maps_by_area(search_type, subset=False)

Construct and return ebunch from data for several BrainMaps.

Also return the BrainMaps for which queries failed.

search_type : string

‘Mapping’ or ‘Connectivity’

subset : sequence or string (optional)

Subset of BrainMaps to query. Default is to query all BrainMaps in CoCoMac. If a string is supplied, it must be the name of a text file with one BrainMap per line.

big_ebunch : list of tuples

Each tuple specifies a source and target node and edge attributes.

failures : list of strings

These are the BrainMaps for which no data were acquired.

Querying a BrainMap for which there is only Mapping data using the Connectivity search type would result in its being a failure. Failures can also result from CoCoMac server errors.

The term ebunch, borrowed from NetworkX, refers to a sequence of graph theory edges.

Integrated primary projections are returned for Connectivity queries, and primary relations are returned for Mapping queries.

Pre-Processing

MapGraph.clean_data()

Remove errors and add missing data.

See comments for more information.

MapGraph.keep_only_one_level_of_resolution(cong, target_map)

Determine each map’s hierarchy and keep only one level.

cong : ConGraph instance

Associated Connectivity data.

target_map : string

Name of BrainMap to which translation will be performed.

cong : ConGraph instance

Updated Connectivity data.

MapGraph.deduce_edges()

Deduce new edges based on those in the graph and add them.

Intra-map edges are disallowed. It is assumed that all regions in the graph from the same BrainMap are disjoint (i.e., at the same level of resolution).

Coordinate-free registration

EndGraph.add_translated_edges(mapp, conn, desired_map, method)

Translate edges in conn to nomenclature of desired_bmap.

Add all desired_map nodes in mapp to this graph.

mapp : MapGraph

Graph of spatial relationships between BrainSites from various BrainMaps.

conn : ConGraph

Graph of anatomical connections between BrainSites.

desired_map : string

Name of BrainMap to which translation will be performed.

method : string

AT method to be used: ‘original’ (that of Stephan & Kotter) or ‘modified’

Post-processing

cocotools.strip_absent_and_unknown_edges(end)

Return graph with known-absent edges removed.

Do not modify the graph passed as input; return a new graph.

end : EndGraph

EndGraph after translated edges have been added.

g : NetworkX DiGraph

Graph with those edges in EndGraph known to be present. Edge attributes are not transferred to this graph.

Main classes

class cocotools.MapGraph

Subclass of the NetworkX DiGraph designed to hold CoCoMac Mapping data.

Each node must be specified in CoCoMac format as a string: ‘BrainMap-BrainSite’. Nodes not in this format are rejected. Node attributes are not allowed.

Edges have the following attributes (but only RC and PDC should be supplied by the user):

(1) RC (relation code). Allowable values are ‘I’ (identical to), ‘S’ (smaller than), ‘L’ (larger than), or ‘O’ (overlaps with). These values complete the sentence, The source node is _____ the target node.

(2) TP (transformation path). This is a list of regions representing the chain of relationships (the path within the graph) that mediates the relationship between the source and the target. When the relationship between the source and the target has been pulled directly from the literature, TP is an empty list. When source’s relationship to target is known because of source’s relationship to region X and region X’s relationship to target, TP is [‘X’]. The list grows with the number of intervening nodes. Of note, the TP for the edge from target to source must be the reverse of the TP for the edge from source to target.

(3) PDC (precision description code). An integer (from zero to 18, with zero being the best) corresponding to an index in the PDC hierarchy (cocotools.query.PDC_HIER), which was developed by the CoCoMac curators. Entries in the hierarchy represent levels of precision with which a statement in the original literature can be made. When the edge is absent from the literature and has been deduced based on other edges (i.e., when the TP length is greater than zero), the PDC corresponds to the worst PDC of the edges represented by TP.

Accurate deduction of new spatial relationships among regions and accurate translation of connectivity data between maps demand that each map be represented at just one level of resolution. This implies that when a suite of spatially related regions from the same map is identified, one or more regions must be excluded from the MapGraph until all remaining are disjoint.

When keep_only_one_level_of_resolution is called, all but one level of resolution is removed from the graph (and cong). The level with the most anatomical connections (i.e., edges in cong) is chosen; in the event of a tie, the finest level of resolution is chosen for all maps but the target map, for which the coarsest level of resolution is chosen.

Redundant nodes within a map are merged into a single node in this graph and in the associated ConGraph. A name for the node is chosen from the list of redundant ones arbitrarily.

New spatial relationships are deduced using an enhanced version of Objective Relational Transformation (ORT) with the deduce_edges method. The strategy used in MapGraph for handling intra-map spatial relationships described above ensures that levels of resolution will not be mixed within maps when deduce_edges is called. This allows deduce_edges to assume all regions within a map are disjoint, which enables, after all possible deductions have been made, automatic identification and removal of relationships that cannot be true due to their implication (in combination with other known relationships) of spatial overlap between regions in the same map.

class cocotools.ConGraph(data=None, **attr)

Subclass of the NetworkX DiGraph designed to hold Connectivity data.

The DiGraph methods add_edge and add_edges_from have been overridden, to enforce that edges have valid attributes with the highest likelihood of correctness referring to their extension codes (ECs), precision description codes (PDCs), and degree.

class cocotools.EndGraph(data=None, **attr)

Subclass of the NetworkX DiGraph designed to hold post-ORT data.