-
Notifications
You must be signed in to change notification settings - Fork 0
/
querying.html
243 lines (231 loc) · 14.7 KB
/
querying.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Querying — CoCoTools 0.0.1 documentation</title>
<link rel="stylesheet" href="_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="CoCoTools 0.0.1 documentation" href="index.html" />
<link rel="up" title="Processing Pipeline in Detail" href="details.html" />
<link rel="next" title="Pre-Processing Query Results" href="preprocessing.html" />
<link rel="prev" title="Processing Pipeline in Detail" href="details.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="preprocessing.html" title="Pre-Processing Query Results"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="details.html" title="Processing Pipeline in Detail"
accesskey="P">previous</a> |</li>
<li><a href="index.html">CoCoTools 0.0.1 documentation</a> »</li>
<li><a href="documentation.html" >CoCoTools’s documentation</a> »</li>
<li><a href="details.html" accesskey="U">Processing Pipeline in Detail</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Querying</a><ul>
<li><a class="reference internal" href="#querying-the-hard-way">Querying the <em>hard</em> way</a></li>
<li><a class="reference internal" href="#querying-the-easy-way-using-cocotools">Querying the <em>easy</em> way using CoCoTools</a><ul>
<li><a class="reference internal" href="#search-type-mandatory">Search type (<em>mandatory</em>)</a></li>
<li><a class="reference internal" href="#subset-optional">Subset (<em>optional</em>)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#query-map-by-area">Query map by area</a></li>
<li><a class="reference internal" href="#ebunch-format">ebunch format</a></li>
<li><a class="reference internal" href="#mapgraphs-and-congraphs-cocotool-directed-graph-container-variables">mapgraphs and congraphs: CoCoTool directed graph container variables</a></li>
<li><a class="reference internal" href="#local-cache">local cache</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="details.html"
title="previous chapter">Processing Pipeline in Detail</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="preprocessing.html"
title="next chapter">Pre-Processing Query Results</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/querying.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="querying">
<h1>Querying<a class="headerlink" href="#querying" title="Permalink to this headline">¶</a></h1>
<p id="detail-querying">Here is where you can learn about how to query the CoCoMac database using CoCoTools</p>
<div class="section" id="querying-the-hard-way">
<h2>Querying the <em>hard</em> way<a class="headerlink" href="#querying-the-hard-way" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
</div>
<div class="section" id="querying-the-easy-way-using-cocotools">
<h2>Querying the <em>easy</em> way using CoCoTools<a class="headerlink" href="#querying-the-easy-way-using-cocotools" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>CoCoTools makes performing custom CoCoMac queries simple. To query the CoCoMac server using CoCoTools users need only to use the function:</dt>
<dd><a class="reference internal" href="api.html#cocotools.multi_map_ebunch" title="cocotools.multi_map_ebunch"><tt class="xref py py-func docutils literal"><span class="pre">cocotools.multi_map_ebunch()</span></tt></a></dd>
</dl>
<p>This function calls lower-level routines that:</p>
<blockquote>
<div><ul class="simple">
<li>form SQL query from user’s command-line input, pass it to CoCoMac server</li>
<li>parse resulting XML output</li>
<li>caches XML results locally to speed up repeated queries (i.e. will check cache before querying server)</li>
<li>populates a special container object, a multi-map ebunch, with query results</li>
</ul>
</div></blockquote>
<p>This function takes 1 mandatory and 1 option inputs</p>
<div class="section" id="search-type-mandatory">
<h3>Search type (<em>mandatory</em>)<a class="headerlink" href="#search-type-mandatory" title="Permalink to this headline">¶</a></h3>
<p>Mapping and Connectivity queries need to be performed seperately. Here you specify <cite>Mapping</cite> to run a mapping query or <cite>Connectivity</cite> for a connectivity query.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">map_bunch</span><span class="o">=</span><span class="n">coco</span><span class="o">.</span><span class="n">multi_map_ebunch</span><span class="p">(</span><span class="s">'Mapping'</span><span class="p">)</span>
<span class="n">con_bunch</span><span class="o">=</span><span class="n">coco</span><span class="o">.</span><span class="n">multi_map_ebunch</span><span class="p">(</span><span class="s">'Connectivity'</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="subset-optional">
<h3>Subset (<em>optional</em>)<a class="headerlink" href="#subset-optional" title="Permalink to this headline">¶</a></h3>
<p>With the subset parameter you can specify the studies you want to query. By default <a class="reference internal" href="api.html#cocotools.multi_map_ebunch" title="cocotools.multi_map_ebunch"><tt class="xref py py-func docutils literal"><span class="pre">cocotools.multi_map_ebunch()</span></tt></a> 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:</p>
<blockquote>
<div><ul class="simple">
<li><cite>coco.MAPPING_NON_TIMEOUTS</cite> lists all the mapping studies that do not lead to a server timeout</li>
<li><cite>coco.CONNECTIVITY_NON_TIMEOUTS</cite> lists all the connectivity studies that do not lead to a server timeout</li>
</ul>
</div></blockquote>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">map_bunch</span><span class="o">=</span><span class="n">coco</span><span class="o">.</span><span class="n">multi_map_ebunch</span><span class="p">(</span><span class="s">'Mapping'</span><span class="p">,</span> <span class="n">coco</span><span class="o">.</span><span class="n">MAPPING_NON_TIMEOUTS</span><span class="p">)</span>
<span class="n">con_bunch</span><span class="o">=</span><span class="n">coco</span><span class="o">.</span><span class="n">multi_map_ebunch</span><span class="p">(</span><span class="s">'Connectivity'</span><span class="p">,</span> <span class="n">coco</span><span class="o">.</span><span class="n">CONNECTIVITY_NON_TIMEOUTS</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="query-map-by-area">
<h2>Query map by area<a class="headerlink" href="#query-map-by-area" title="Permalink to this headline">¶</a></h2>
<p>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</p>
<blockquote>
<div><a class="reference internal" href="api.html#cocotools.query_maps_by_area" title="cocotools.query_maps_by_area"><tt class="xref py py-func docutils literal"><span class="pre">cocotools.query_maps_by_area()</span></tt></a></div></blockquote>
<p>These lists are studies that are known to produce timeouts</p>
<blockquote>
<div><ul class="simple">
<li>coco.MAPPING_TIMEOUTS</li>
<li>coco.CONNECTIVITY_TIMEOUTS</li>
</ul>
</div></blockquote>
<p>thus, where we querying the <em>non-timeout</em> studies using <strong>multi_map_ebunch</strong>, now we want to query the <em>timeouts</em> using:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">map_bunch_to</span><span class="o">=</span><span class="n">coco</span><span class="o">.</span><span class="n">query_maps_by_area</span><span class="p">(</span><span class="s">'Mapping'</span><span class="p">,</span> <span class="n">coco</span><span class="o">.</span><span class="n">MAPPING_TIMEOUTS</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="ebunch-format">
<h2>ebunch format<a class="headerlink" href="#ebunch-format" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>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</p>
</div>
<div class="section" id="mapgraphs-and-congraphs-cocotool-directed-graph-container-variables">
<h2>mapgraphs and congraphs: CoCoTool directed graph container variables<a class="headerlink" href="#mapgraphs-and-congraphs-cocotool-directed-graph-container-variables" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<blockquote>
<div><ul class="simple">
<li>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.</li>
<li>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.</li>
</ul>
</div></blockquote>
<p>To place your query results into them:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mapg</span><span class="o">=</span><span class="n">coco</span><span class="o">.</span><span class="n">MapGraph</span><span class="p">()</span>
<span class="n">mapg</span><span class="o">=</span><span class="n">mapg</span><span class="o">.</span><span class="n">add_edges_from</span><span class="p">(</span><span class="n">map_bunch</span><span class="p">)</span>
</pre></div>
</div>
<p>the same can be done for the connectivity data:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">cong</span><span class="o">=</span><span class="n">coco</span><span class="o">.</span><span class="n">ConGraph</span><span class="p">()</span>
<span class="n">cong</span><span class="o">=</span><span class="n">cong</span><span class="o">.</span><span class="n">add_edges_from</span><span class="p">(</span><span class="n">con_bunch</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="local-cache">
<h2>local cache<a class="headerlink" href="#local-cache" title="Permalink to this headline">¶</a></h2>
<p>By default CoCoTools creates 2 sqlite caches in ~/.cache directory:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">cocotools</span><span class="o">.</span><span class="n">sqlite</span>
<span class="n">cocotools_area</span><span class="o">.</span><span class="n">sqlite</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="preprocessing.html" title="Pre-Processing Query Results"
>next</a> |</li>
<li class="right" >
<a href="details.html" title="Processing Pipeline in Detail"
>previous</a> |</li>
<li><a href="index.html">CoCoTools 0.0.1 documentation</a> »</li>
<li><a href="documentation.html" >CoCoTools’s documentation</a> »</li>
<li><a href="details.html" >Processing Pipeline in Detail</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2011, Daniel Bliss, Rob Blumenfeld and Fernando Perez.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>