Here is where you can learn about how to query the CoCoMac database using CoCoTools
To get data from the CoCoMac database, you could browse the website, click through the dropdown boxes to get the desired data table and copy paste. However, this method will be a bit cumbersome for most users. Alternatively, you can pass customized SQL (structured query language) queries directly to the server (which is an excellent feature of the cocomac server!) and it will return query results in XML. This is by far a preferrable method, but does require knowledge of SQL and XML and then you have to deal with putting the results into some sort of container variable that will be amenable for further processing.
This function calls lower-level routines that:
- form SQL query from user’s command-line input, pass it to CoCoMac server
- parse resulting XML output
- caches XML results locally to speed up repeated queries (i.e. will check cache before querying server)
- populates a special container object, a multi-map ebunch, with query results
This function takes 1 mandatory and 1 option inputs
Mapping and Connectivity queries need to be performed seperately. Here you specify Mapping to run a mapping query or Connectivity for a connectivity query.
Examples:
map_bunch=coco.multi_map_ebunch('Mapping')
con_bunch=coco.multi_map_ebunch('Connectivity')
With the subset parameter you can specify the studies you want to query. By default cocotools.multi_map_ebunch() will query the entire CoCoMac database. Querying certain mapping and connectivity studies will produce CoCoMac server timeouts. Therefore, it is preferrable to query from the following lists:
- coco.MAPPING_NON_TIMEOUTS lists all the mapping studies that do not lead to a server timeout
- coco.CONNECTIVITY_NON_TIMEOUTS lists all the connectivity studies that do not lead to a server timeout
Examples:
map_bunch=coco.multi_map_ebunch('Mapping', coco.MAPPING_NON_TIMEOUTS)
con_bunch=coco.multi_map_ebunch('Connectivity', coco.CONNECTIVITY_NON_TIMEOUTS)
To gather the data from the studies that are known to produce server timeouts (when querying the entire study), you will need to query the study, region by region This is done using the
These lists are studies that are known to produce timeouts
- coco.MAPPING_TIMEOUTS
- coco.CONNECTIVITY_TIMEOUTS
thus, where we querying the non-timeout studies using multi_map_ebunch, now we want to query the timeouts using:
map_bunch_to=coco.query_maps_by_area('Mapping', coco.MAPPING_TIMEOUTS)
You dont need to know much about the ebunch format. We borrowed it from NetworkX. It holds edges as tuples. It is a handy format for holding query results, but for CoCoTools, that is all this good for.
In fact, the first thing you want to do after your query is returned is to place the output into one of two special networkx directed graph (digraph) objects
These are the special cocotools directed graph containers for holding mapping data (MapGraph) and connectivity data (ConGraph) that are much easier to address and manipulate using standard networkx commands and more amenable for CoCoTools processing.
- ConGraphs contain connectivity results, whereby each directed edge represents a single result or statement from a tracer study about the presence or absence of staining that would connect two regions.
- MapGraphs contain mapping results, whereby each edge represents a single statement about the logical relationship shared between two brain regions in the same or different parcellation schemes.
To place your query results into them:
mapg=coco.MapGraph()
mapg=mapg.add_edges_from(map_bunch)
the same can be done for the connectivity data:
cong=coco.ConGraph()
cong=cong.add_edges_from(con_bunch)
By default CoCoTools creates 2 sqlite caches in ~/.cache directory:
cocotools.sqlite
cocotools_area.sqlite