-
Notifications
You must be signed in to change notification settings - Fork 25
/
Copy pathmd_README.html
312 lines (310 loc) · 38.6 KB
/
md_README.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
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://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/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libBigWig: README</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libBigWig
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">README </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><object type="image/svg+xml" data="https://travis-ci.org/dpryan79/libBigWig.svg?branch=master" style="pointer-events: none;">Master build status</object> <a href="http://dx.doi.org/10.5281/zenodo.45278"><object type="image/svg+xml" data="https://zenodo.org/badge/doi/10.5281/zenodo.45278.svg" style="pointer-events: none;">DOI</object></a></p>
<p>A C library for reading/parsing local and remote bigWig and bigBed files. While Kent's source code is free to use for these purposes, it's really inappropriate as library code since it has the unfortunate habit of calling <code>exit()</code> whenever there's an error. If that's then used inside of something like python then the python interpreter gets killed. This library is aimed at resolving these sorts of issues and should also use more standard things like curl and has a friendlier license to boot.</p>
<p>Documentation is automatically generated by doxygen and can be found under <a href="/docs/html"><code>docs/html</code></a> or online <a href="https://cdn.rawgit.com/dpryan79/libBigWig/master/docs/html/index.html">here</a>.</p>
<h1><a class="anchor" id="autotoc_md0"></a>
Example</h1>
<p>The only functions and structures that end users need to care about are in "bigWig.h". Below is a commented example. You can see the files under <a href="./test/"><code>test/</code></a> for further examples.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="bigWig_8h.html">bigWig.h</a>"</span></div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[]) {</div>
<div class="line"> <a class="code" href="structbigWigFile__t.html">bigWigFile_t</a> *fp = NULL;</div>
<div class="line"> <a class="code" href="structbwOverlappingIntervals__t.html">bwOverlappingIntervals_t</a> *intervals = NULL;</div>
<div class="line"> <span class="keywordtype">double</span> *stats = NULL;</div>
<div class="line"> <span class="keywordflow">if</span>(argc != 2) {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Usage: %s {file.bw|URL://path/file.bw}\n"</span>, argv[0]);</div>
<div class="line"> <span class="keywordflow">return</span> 1;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Initialize enough space to hold 128KiB (1<<17) of data at a time</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#a4aa7fa5e6146a2719feb8815c9bccd62">bwInit</a>(1<<17) != 0) {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Received an error in bwInit\n"</span>);</div>
<div class="line"> <span class="keywordflow">return</span> 1;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Open the local/remote file</span></div>
<div class="line"> fp = <a class="code" href="bigWig_8h.html#a55e46bf04f13da31a3971044b85c9243">bwOpen</a>(argv[1], NULL, <span class="stringliteral">"r"</span>);</div>
<div class="line"> <span class="keywordflow">if</span>(!fp) {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"An error occured while opening %s\n"</span>, argv[1]);</div>
<div class="line"> <span class="keywordflow">return</span> 1;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Get values in a range (0-based, half open) without NAs</span></div>
<div class="line"> intervals = <a class="code" href="bigWig_8h.html#a29f3a6b4b6861833a35a1199666d2cf9">bwGetValues</a>(fp, <span class="stringliteral">"chr1"</span>, 10000000, 10000100, 0);</div>
<div class="line"> <a class="code" href="bigWig_8h.html#a6a3f9298129e7fa061707739a96b36f3">bwDestroyOverlappingIntervals</a>(intervals); <span class="comment">//Free allocated memory</span></div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Get values in a range (0-based, half open) with NAs</span></div>
<div class="line"> intervals = <a class="code" href="bigWig_8h.html#a29f3a6b4b6861833a35a1199666d2cf9">bwGetValues</a>(fp, <span class="stringliteral">"chr1"</span>, 10000000, 10000100, 1);</div>
<div class="line"> <a class="code" href="bigWig_8h.html#a6a3f9298129e7fa061707739a96b36f3">bwDestroyOverlappingIntervals</a>(intervals); <span class="comment">//Free allocated memory</span></div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Get the full intervals that overlap</span></div>
<div class="line"> intervals = <a class="code" href="bigWig_8h.html#aa1ac8480a8fdf24c53b73970149e359b">bwGetOverlappingIntervals</a>(fp, <span class="stringliteral">"chr1"</span>, 10000000, 10000100);</div>
<div class="line"> <a class="code" href="bigWig_8h.html#a6a3f9298129e7fa061707739a96b36f3">bwDestroyOverlappingIntervals</a>(intervals);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Get an example statistic - standard deviation</span></div>
<div class="line"> <span class="comment">//We want ~4 bins in the range</span></div>
<div class="line"> stats = <a class="code" href="bigWig_8h.html#af06eae8c9d405a03276c56d53e3c4fc4">bwStats</a>(fp, <span class="stringliteral">"chr1"</span>, 10000000, 10000100, 4, <a class="code" href="bigWig_8h.html#aa3e01d7486887aa111417b688bc1a22cac10cab3311c9fe30fbabf9137cd40d57">dev</a>);</div>
<div class="line"> <span class="keywordflow">if</span>(stats) {</div>
<div class="line"> printf(<span class="stringliteral">"chr1:10000000-10000100 std. dev.: %f %f %f %f\n"</span>, stats[0], stats[1], stats[2], stats[3]);</div>
<div class="line"> free(stats);</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <a class="code" href="bigWig_8h.html#ae9041b92bc3f69533fe6dc1711bbf485">bwClose</a>(fp);</div>
<div class="line"> <a class="code" href="bigWig_8h.html#af1f5d8a9bf0a96034b2ba3f3b3ee679a">bwCleanup</a>();</div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md1"></a>
Writing example</h2>
<p>N.B., creation of bigBed files is not supported (there are no plans to change this).</p>
<p>Below is an example of how to write bigWig files. You can also find this file under <a href="test/exampleWrite.c"><code>test/exampleWrite.c</code></a>. Unlike with Kent's tools, you can create bigWig files entry by entry without needing an intermediate wiggle or bedGraph file. Entries in bigWig files are stored in blocks with each entry in a block referring to the same chromosome and having the same type, of which there are three (see the <a href="http://genome.ucsc.edu/goldenpath/help/wiggle.html">wiggle specification</a> for more information on this).</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="bigWig_8h.html">bigWig.h</a>"</span></div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[]) {</div>
<div class="line"> <a class="code" href="structbigWigFile__t.html">bigWigFile_t</a> *fp = NULL;</div>
<div class="line"> <span class="keywordtype">char</span> *chroms[] = {<span class="stringliteral">"1"</span>, <span class="stringliteral">"2"</span>};</div>
<div class="line"> <span class="keywordtype">char</span> *chromsUse[] = {<span class="stringliteral">"1"</span>, <span class="stringliteral">"1"</span>, <span class="stringliteral">"1"</span>};</div>
<div class="line"> uint32_t chrLens[] = {1000000, 1500000};</div>
<div class="line"> uint32_t starts[] = {0, 100, 125,</div>
<div class="line"> 200, 220, 230,</div>
<div class="line"> 500, 600, 625,</div>
<div class="line"> 700, 800, 850};</div>
<div class="line"> uint32_t ends[] = {5, 120, 126,</div>
<div class="line"> 205, 226, 231};</div>
<div class="line"> <span class="keywordtype">float</span> values[] = {0.0f, 1.0f, 200.0f,</div>
<div class="line"> -2.0f, 150.0f, 25.0f,</div>
<div class="line"> 0.0f, 1.0f, 200.0f,</div>
<div class="line"> -2.0f, 150.0f, 25.0f,</div>
<div class="line"> -5.0f, -20.0f, 25.0f,</div>
<div class="line"> -5.0f, -20.0f, 25.0f};</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#a4aa7fa5e6146a2719feb8815c9bccd62">bwInit</a>(1<<17) != 0) {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Received an error in bwInit\n"</span>);</div>
<div class="line"> <span class="keywordflow">return</span> 1;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> fp = <a class="code" href="bigWig_8h.html#a55e46bf04f13da31a3971044b85c9243">bwOpen</a>(<span class="stringliteral">"example_output.bw"</span>, NULL, <span class="stringliteral">"w"</span>);</div>
<div class="line"> <span class="keywordflow">if</span>(!fp) {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"An error occurred while opening example_output.bw for writingn\n"</span>);</div>
<div class="line"> <span class="keywordflow">return</span> 1;</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Allow up to 10 zoom levels, though fewer will be used in practice</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#a0dc09da6beabf0c9ea3d0ca447ddff5b">bwCreateHdr</a>(fp, 10)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Create the chromosome lists</span></div>
<div class="line"> fp-><a class="code" href="structbigWigFile__t.html#ac1afdee9f31c8e69dc2a902ee0605f78">cl</a> = <a class="code" href="bigWig_8h.html#a121b65a3e554f8ef3f329b5f529de4a2">bwCreateChromList</a>(chroms, chrLens, 2);</div>
<div class="line"> <span class="keywordflow">if</span>(!fp-><a class="code" href="structbigWigFile__t.html#ac1afdee9f31c8e69dc2a902ee0605f78">cl</a>) <span class="keywordflow">goto</span> error;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Write the header</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#af66b538195826aa3bda7e3363cf3f201">bwWriteHdr</a>(fp)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Some example bedGraph-like entries</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#a11d64f7e0f8c9b7d79fe826bb97c5b59">bwAddIntervals</a>(fp, chromsUse, starts, ends, values, 3)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> <span class="comment">//We can continue appending similarly formatted entries</span></div>
<div class="line"> <span class="comment">//N.B. you can't append a different chromosome (those always go into different</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#ab89bcbcd986ba9a16cca29daa9329051">bwAppendIntervals</a>(fp, starts+3, ends+3, values+3, 3)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Add a new block of entries with a span. Since bwAdd/AppendIntervals was just used we MUST create a new block</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#a633635a8da1bb1e9e5f42b5557f9872a">bwAddIntervalSpans</a>(fp, <span class="stringliteral">"1"</span>, starts+6, 20, values+6, 3)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> <span class="comment">//We can continue appending similarly formatted entries</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#a96f517b42f51e9c97caf0b99fdca5f70">bwAppendIntervalSpans</a>(fp, starts+9, values+9, 3)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Add a new block of fixed-step entries</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#aec467bb957caab80a06c21ff5b4bbfab">bwAddIntervalSpanSteps</a>(fp, <span class="stringliteral">"1"</span>, 900, 20, 30, values+12, 3)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> <span class="comment">//The start is then 760, since that's where the previous step ended</span></div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#ab4a0512c15a6647fc92cb5e3b5bca861">bwAppendIntervalSpanSteps</a>(fp, values+15, 3)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Add a new chromosome</span></div>
<div class="line"> chromsUse[0] = <span class="stringliteral">"2"</span>;</div>
<div class="line"> chromsUse[1] = <span class="stringliteral">"2"</span>;</div>
<div class="line"> chromsUse[2] = <span class="stringliteral">"2"</span>;</div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#a11d64f7e0f8c9b7d79fe826bb97c5b59">bwAddIntervals</a>(fp, chromsUse, starts, ends, values, 3)) <span class="keywordflow">goto</span> error;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">//Closing the file causes the zoom levels to be created</span></div>
<div class="line"> <a class="code" href="bigWig_8h.html#ae9041b92bc3f69533fe6dc1711bbf485">bwClose</a>(fp);</div>
<div class="line"> <a class="code" href="bigWig_8h.html#af1f5d8a9bf0a96034b2ba3f3b3ee679a">bwCleanup</a>();</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line"> </div>
<div class="line">error:</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Received an error somewhere!\n"</span>);</div>
<div class="line"> <a class="code" href="bigWig_8h.html#ae9041b92bc3f69533fe6dc1711bbf485">bwClose</a>(fp);</div>
<div class="line"> <a class="code" href="bigWig_8h.html#af1f5d8a9bf0a96034b2ba3f3b3ee679a">bwCleanup</a>();</div>
<div class="line"> <span class="keywordflow">return</span> 1;</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md2"></a>
Testing file types</h1>
<p>As of version 0.3.0, this library supports accessing bigBed files, which are related to bigWig files. Applications that need to support both bigWig and bigBed input can use the <code>bwIsBigWig</code> and <code>bbIsBigBed</code> functions to determine if their inputs are bigWig/bigBed files:</p>
<div class="fragment"><div class="line">...code...</div>
<div class="line">if(<a class="code" href="bigWig_8h.html#a83cb23e15fed718ba77576e41865dab9">bwIsBigWig</a>(input_file_name, NULL)) {</div>
<div class="line"> <span class="comment">//do something</span></div>
<div class="line">} <span class="keywordflow">else</span> <span class="keywordflow">if</span>(<a class="code" href="bigWig_8h.html#a592fb218273e1f18d97448c88588df19">bbIsBigBed</a>(input_file_name, NULL)) {</div>
<div class="line"> <span class="comment">//do something else</span></div>
<div class="line">} <span class="keywordflow">else</span> {</div>
<div class="line"> <span class="comment">//handle unknown input</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>Note that these two functions rely on the "magic number" at the beginning of each file, which differs between bigWig and bigBed files.</p>
<h1><a class="anchor" id="autotoc_md3"></a>
bigBed support</h1>
<p>Support for accessing bigBed files was added in version 0.3.0. The function names used for accessing bigBed files are similar to those used for bigWig files. </p><pre class="fragment">Function | Use
--- | ---
bbOpen | Opens a bigBed file
bbGetSQL | Returns the SQL string (if it exists) in a bigBed file
bbGetOverlappingEntries | Returns all entries overlapping an interval (either with or without their associated strings
bbDestroyOverlappingEntries | Free memory allocated by the above command
</pre><p>Other functions, such as <code>bwClose</code> and <code>bwInit</code>, are shared between bigWig and bigBed files. See <code>test/testBigBed.c</code> for a full example.</p>
<h1><a class="anchor" id="autotoc_md4"></a>
A note on bigBed entries</h1>
<p>Inside bigBed files, entries are stored as chromosome, start, and end coordinates with an (optional) associated string. For example, a "bedRNAElements" file from Encode has name, score, strand, "level", "significance", and "score2" values associated with each entry. These are stored inside the bigBed files as a single tab-separated character vector (char *), which makes parsing difficult. The names of the various fields inside of bigBed files is stored as an SQL string, for example: </p><pre class="fragment">table RnaElements
"BED6 + 3 scores for RNA Elements data "
(
string chrom; "Reference sequence chromosome or scaffold"
uint chromStart; "Start position in chromosome"
uint chromEnd; "End position in chromosome"
string name; "Name of item"
uint score; "Normalized score from 0-1000"
char[1] strand; "+ or - or . for unknown"
float level; "Expression level such as RPKM or FPKM. Set to -1 for no data."
float signif; "Statistical significance such as IDR. Set to -1 for no data."
uint score2; "Additional measurement/count e.g. number of reads. Set to 0 for no data."
)
</pre><p>Entries will then be of the form (one per line): </p><pre class="fragment">59426 115 - 0.021 0.48 218
51 209 + 0.071 0.74 130
52 170 + 0.045 0.61 171
59433 178 - 0.049 0.34 296
53 156 + 0.038 0.19 593
59436 186 - 0.054 0.15 1010
59437 506 - 1.560 0.00 430611
</pre><p>Note that chromosome and start/end intervals are stored separately, so there's no need to parse them out of string. libBigWig can return these entries, either with or without the above associated strings. Parsing these string is left to the application requiring them and is currently outside the scope of this library.</p>
<h1><a class="anchor" id="autotoc_md5"></a>
Interval/Entry iterators</h1>
<p>Sometimes it is desirable to request a large number of intervals from a bigWig file or entries from a bigBed file, but not hold them all in memory at once (e.g., due to saving memory). To support this, libBigWig (since version 0.3.0) supports two kinds of iterators. The general process of using iterators is: (1) iterator creation, (2) traversal, and finally (3) iterator destruction. Only iterator creation differs between bigWig and bigBed files.</p>
<p>Importantly, iterators return results by one or more blocks. This is for convenience, since bigWig intervals and bigBed entries are stored in together in fixed-size groups, called blocks. The number of blocks of entries returned, therefore, is an option that can be specified to balance performance and memory usage.</p>
<h2><a class="anchor" id="autotoc_md6"></a>
Iterator creation</h2>
<p>For bigwig files, iterators are created with the <code><a class="el" href="bigWig_8h.html#afaeb6115f7056b209eefa9363b409ef5" title="Creates an iterator over intervals in a bigWig file Iterators can be traversed with bwIteratorNext() ...">bwOverlappingIntervalsIterator()</a></code>. This function takes chromosomal bounds (chromosome name, start, and end position) as well as a number of blocks. The equivalent function for bigBed files is <code><a class="el" href="bigWig_8h.html#a75c2894f13ba9d6917117c63565e5c42" title="Creates an iterator over entries in a bigBed file Iterators can be traversed with bwIteratorNext() an...">bbOverlappingEntriesIterator()</a></code>, which additionally takes a <code>withString</code> argutment, which dictates whether the returned entries include the associated string values or not.</p>
<p>Each of the aforementioned files returns a pointer to a <code><a class="el" href="structbwOverlapIterator__t.html" title="A structure to hold iterations One of intervals and entries should be used to access records from big...">bwOverlapIterator_t</a></code> object. The only important parts of this structure for end users are the following members: <code>entries</code>, <code>intervals</code>, and <code>data</code>. <code>entries</code> is a pointer to a <code><a class="el" href="structbbOverlappingEntries__t.html" title="Holds interval:str associations.">bbOverlappingEntries_t</a></code> object, or <code>NULL</code> if a bigWig file is being used. Likewise, <code>intervals</code> is a pointer to a <code><a class="el" href="structbwOverlappingIntervals__t.html" title="Holds interval:value associations.">bwOverlappingIntervals_t</a></code> object, or <code>NULL</code> if a bigBed file is being used. <code>data</code> is a special pointer, used to signify the end of iteration. Thus, when <code>data</code> is a <code>NULL</code> pointer, iteration has ended.</p>
<h2><a class="anchor" id="autotoc_md7"></a>
Iterator traversal</h2>
<p>Regardless of whether a bigWig or bigBed file is being used, the <code><a class="el" href="bigWig_8h.html#a3f15a3f526c2d9ad2f721b791bcdf956" title="Traverses to the entries/intervals in the next group of blocks.">bwIteratorNext()</a></code> function will free currently used memory and load the appropriate intervals or entries for the next block(s). On error, this will return a NULL pointer (memory is already internally freed in this case).</p>
<h2><a class="anchor" id="autotoc_md8"></a>
Iterator destruction</h2>
<p><code><a class="el" href="structbwOverlapIterator__t.html" title="A structure to hold iterations One of intervals and entries should be used to access records from big...">bwOverlapIterator_t</a></code> objects MUST be destroyed after use. This can be done with the <code><a class="el" href="bigWig_8h.html#a9b99f0c33d052d278d2e25044ca706e4" title="Destroys a bwOverlapIterator_t.">bwIteratorDestroy()</a></code> function.</p>
<h2><a class="anchor" id="autotoc_md9"></a>
Example</h2>
<p>A full example is provided in <code>tests/testIterator.c</code>, but a small example of iterating over all bigWig intervals in <code>chr1:0-10000000</code> in chunks of 5 blocks follows:</p>
<div class="fragment"><div class="line">iter = <a class="code" href="bigWig_8h.html#afaeb6115f7056b209eefa9363b409ef5">bwOverlappingIntervalsIterator</a>(fp, <span class="stringliteral">"chr1"</span>, 0, 10000000, 5);</div>
<div class="line"><span class="keywordflow">while</span>(iter->data) {</div>
<div class="line"> <span class="comment">//Do stuff with iter->intervals</span></div>
<div class="line"> iter = <a class="code" href="bigWig_8h.html#a3f15a3f526c2d9ad2f721b791bcdf956">bwIteratorNext</a>(iter);</div>
<div class="line">}</div>
<div class="line"><a class="code" href="bigWig_8h.html#a9b99f0c33d052d278d2e25044ca706e4">bwIteratorDestroy</a>(iter);</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md10"></a>
A note on bigWig statistics</h1>
<p>The results of <code>min</code>, <code>max</code>, and <code>mean</code> should be the same as those from <code>BigWigSummary</code>. <code>stdev</code> and <code>coverage</code>, however, may differ due to Kent's tools producing incorrect results (at least for <code>coverage</code>, though the same appears to be the case for <code>stdev</code>). The <code>sum</code> method doesn't exist in Kent's tools, so note that if zoom levels are used, that it will multiply the block average by the lesser of the number of bases covered in the block and the number of bases in a block overlapping the desired region.</p>
<h1><a class="anchor" id="autotoc_md11"></a>
Python interface</h1>
<p>There are currently two python interfaces that make use of libBigWig: <a href="https://github.com/dpryan79/pyBigWig">pyBigWig</a> by me and <a href="https://github.com/brentp/bw-python">bw-python</a> by Brent Pederson. Those interested are encouraged to give both a try!</p>
<h1><a class="anchor" id="autotoc_md12"></a>
Building without remote file access</h1>
<p>If you want to compile without remote file access (e.g., you don't have curl installed), then you can append <code>-DNOCURL</code> to the <code>CFLAGS</code> line in the <code>Makefile</code>. You will also need to remove <code>-lcurl</code> from the <code>LIBS</code> line. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<div class="ttc" id="abigWig_8h_html_a29f3a6b4b6861833a35a1199666d2cf9"><div class="ttname"><a href="bigWig_8h.html#a29f3a6b4b6861833a35a1199666d2cf9">bwGetValues</a></div><div class="ttdeci">bwOverlappingIntervals_t * bwGetValues(bigWigFile_t *fp, char *chrom, uint32_t start, uint32_t end, int includeNA)</div><div class="ttdoc">Return all per-base bigWig values in a given interval. Given an interval (e.g., chr1:0-100),...</div><div class="ttdef"><b>Definition:</b> bwValues.c:713</div></div>
<div class="ttc" id="abigWig_8h_html_ab4a0512c15a6647fc92cb5e3b5bca861"><div class="ttname"><a href="bigWig_8h.html#ab4a0512c15a6647fc92cb5e3b5bca861">bwAppendIntervalSpanSteps</a></div><div class="ttdeci">int bwAppendIntervalSpanSteps(bigWigFile_t *fp, float *values, uint32_t n)</div><div class="ttdoc">Append to a previous block of fixed-step entries. If you previously used bwAddIntervalSpanSteps(),...</div><div class="ttdef"><b>Definition:</b> bwWrite.c:552</div></div>
<div class="ttc" id="abigWig_8h_html"><div class="ttname"><a href="bigWig_8h.html">bigWig.h</a></div></div>
<div class="ttc" id="abigWig_8h_html_aa1ac8480a8fdf24c53b73970149e359b"><div class="ttname"><a href="bigWig_8h.html#aa1ac8480a8fdf24c53b73970149e359b">bwGetOverlappingIntervals</a></div><div class="ttdeci">bwOverlappingIntervals_t * bwGetOverlappingIntervals(bigWigFile_t *fp, char *chrom, uint32_t start, uint32_t end)</div><div class="ttdoc">Return bigWig entries overlapping an interval. Find all bigWig entries overlapping a range and return...</div><div class="ttdef"><b>Definition:</b> bwValues.c:563</div></div>
<div class="ttc" id="abigWig_8h_html_a83cb23e15fed718ba77576e41865dab9"><div class="ttname"><a href="bigWig_8h.html#a83cb23e15fed718ba77576e41865dab9">bwIsBigWig</a></div><div class="ttdeci">int bwIsBigWig(char *fname, CURLcode(*callBack)(CURL *))</div><div class="ttdoc">Determine if a file is a bigWig file. This function will quickly check either local or remote files t...</div><div class="ttdef"><b>Definition:</b> bwRead.c:302</div></div>
<div class="ttc" id="abigWig_8h_html_a3f15a3f526c2d9ad2f721b791bcdf956"><div class="ttname"><a href="bigWig_8h.html#a3f15a3f526c2d9ad2f721b791bcdf956">bwIteratorNext</a></div><div class="ttdeci">bwOverlapIterator_t * bwIteratorNext(bwOverlapIterator_t *iter)</div><div class="ttdoc">Traverses to the entries/intervals in the next group of blocks.</div><div class="ttdef"><b>Definition:</b> bwValues.c:652</div></div>
<div class="ttc" id="abigWig_8h_html_a121b65a3e554f8ef3f329b5f529de4a2"><div class="ttname"><a href="bigWig_8h.html#a121b65a3e554f8ef3f329b5f529de4a2">bwCreateChromList</a></div><div class="ttdeci">chromList_t * bwCreateChromList(char **chroms, uint32_t *lengths, int64_t n)</div><div class="ttdoc">Take a list of chromosome names and lengths and return a pointer to a chromList_t This MUST be run be...</div><div class="ttdef"><b>Definition:</b> bwWrite.c:22</div></div>
<div class="ttc" id="abigWig_8h_html_a4aa7fa5e6146a2719feb8815c9bccd62"><div class="ttname"><a href="bigWig_8h.html#a4aa7fa5e6146a2719feb8815c9bccd62">bwInit</a></div><div class="ttdeci">int bwInit(size_t bufSize)</div><div class="ttdoc">Initializes curl and global variables. This MUST be called before other functions (at least if you wa...</div><div class="ttdef"><b>Definition:</b> bwRead.c:38</div></div>
<div class="ttc" id="abigWig_8h_html_a96f517b42f51e9c97caf0b99fdca5f70"><div class="ttname"><a href="bigWig_8h.html#a96f517b42f51e9c97caf0b99fdca5f70">bwAppendIntervalSpans</a></div><div class="ttdeci">int bwAppendIntervalSpans(bigWigFile_t *fp, uint32_t *start, float *values, uint32_t n)</div><div class="ttdoc">Append to a previous block of variable-step entries. If you previously used bwAddIntervalSpans(),...</div><div class="ttdef"><b>Definition:</b> bwWrite.c:495</div></div>
<div class="ttc" id="abigWig_8h_html_a592fb218273e1f18d97448c88588df19"><div class="ttname"><a href="bigWig_8h.html#a592fb218273e1f18d97448c88588df19">bbIsBigBed</a></div><div class="ttdeci">int bbIsBigBed(char *fname, CURLcode(*callBack)(CURL *))</div><div class="ttdoc">Determine is a file is a bigBed file. This function will quickly check either local or remote files t...</div><div class="ttdef"><b>Definition:</b> bwRead.c:332</div></div>
<div class="ttc" id="abigWig_8h_html_a11d64f7e0f8c9b7d79fe826bb97c5b59"><div class="ttname"><a href="bigWig_8h.html#a11d64f7e0f8c9b7d79fe826bb97c5b59">bwAddIntervals</a></div><div class="ttdeci">int bwAddIntervals(bigWigFile_t *fp, char **chrom, uint32_t *start, uint32_t *end, float *values, uint32_t n)</div><div class="ttdoc">Write a new block of bedGraph-like intervals to a bigWig file Adds entries of the form: chromosome st...</div><div class="ttdef"><b>Definition:</b> bwWrite.c:374</div></div>
<div class="ttc" id="astructbwOverlappingIntervals__t_html"><div class="ttname"><a href="structbwOverlappingIntervals__t.html">bwOverlappingIntervals_t</a></div><div class="ttdoc">Holds interval:value associations.</div><div class="ttdef"><b>Definition:</b> bigWig.h:223</div></div>
<div class="ttc" id="abigWig_8h_html_ab89bcbcd986ba9a16cca29daa9329051"><div class="ttname"><a href="bigWig_8h.html#ab89bcbcd986ba9a16cca29daa9329051">bwAppendIntervals</a></div><div class="ttdeci">int bwAppendIntervals(bigWigFile_t *fp, uint32_t *start, uint32_t *end, float *values, uint32_t n)</div><div class="ttdoc">Append bedGraph-like intervals to a previous block of bedGraph-like intervals in a bigWig file....</div><div class="ttdef"><b>Definition:</b> bwWrite.c:434</div></div>
<div class="ttc" id="abigWig_8h_html_a55e46bf04f13da31a3971044b85c9243"><div class="ttname"><a href="bigWig_8h.html#a55e46bf04f13da31a3971044b85c9243">bwOpen</a></div><div class="ttdeci">bigWigFile_t * bwOpen(char *fname, CURLcode(*callBack)(CURL *), const char *mode)</div><div class="ttdoc">Opens a local or remote bigWig file. This will open a local or remote bigWig file....</div><div class="ttdef"><b>Definition:</b> bwRead.c:345</div></div>
<div class="ttc" id="abigWig_8h_html_af1f5d8a9bf0a96034b2ba3f3b3ee679a"><div class="ttname"><a href="bigWig_8h.html#af1f5d8a9bf0a96034b2ba3f3b3ee679a">bwCleanup</a></div><div class="ttdeci">void bwCleanup(void)</div><div class="ttdoc">The counterpart to bwInit, this cleans up curl.</div><div class="ttdef"><b>Definition:</b> bwRead.c:52</div></div>
<div class="ttc" id="astructbigWigFile__t_html_ac1afdee9f31c8e69dc2a902ee0605f78"><div class="ttname"><a href="structbigWigFile__t.html#ac1afdee9f31c8e69dc2a902ee0605f78">bigWigFile_t::cl</a></div><div class="ttdeci">chromList_t * cl</div><div class="ttdef"><b>Definition:</b> bigWig.h:213</div></div>
<div class="ttc" id="abigWig_8h_html_ae9041b92bc3f69533fe6dc1711bbf485"><div class="ttname"><a href="bigWig_8h.html#ae9041b92bc3f69533fe6dc1711bbf485">bwClose</a></div><div class="ttdeci">void bwClose(bigWigFile_t *fp)</div><div class="ttdoc">Closes a bigWigFile_t and frees up allocated memory This closes both bigWig and bigBed files.</div><div class="ttdef"><b>Definition:</b> bwRead.c:289</div></div>
<div class="ttc" id="abigWig_8h_html_af66b538195826aa3bda7e3363cf3f201"><div class="ttname"><a href="bigWig_8h.html#af66b538195826aa3bda7e3363cf3f201">bwWriteHdr</a></div><div class="ttdeci">int bwWriteHdr(bigWigFile_t *bw)</div><div class="ttdoc">Write a the header to a bigWig file. You must have already opened the output file,...</div><div class="ttdef"><b>Definition:</b> bwWrite.c:187</div></div>
<div class="ttc" id="abigWig_8h_html_afaeb6115f7056b209eefa9363b409ef5"><div class="ttname"><a href="bigWig_8h.html#afaeb6115f7056b209eefa9363b409ef5">bwOverlappingIntervalsIterator</a></div><div class="ttdeci">bwOverlapIterator_t * bwOverlappingIntervalsIterator(bigWigFile_t *fp, char *chrom, uint32_t start, uint32_t end, uint32_t blocksPerIteration)</div><div class="ttdoc">Creates an iterator over intervals in a bigWig file Iterators can be traversed with bwIteratorNext() ...</div><div class="ttdef"><b>Definition:</b> bwValues.c:587</div></div>
<div class="ttc" id="abigWig_8h_html_aec467bb957caab80a06c21ff5b4bbfab"><div class="ttname"><a href="bigWig_8h.html#aec467bb957caab80a06c21ff5b4bbfab">bwAddIntervalSpanSteps</a></div><div class="ttdeci">int bwAddIntervalSpanSteps(bigWigFile_t *fp, char *chrom, uint32_t start, uint32_t span, uint32_t step, float *values, uint32_t n)</div><div class="ttdoc">Add a new block of fixed-step entries to a bigWig file Adds entries for the form value to the file....</div><div class="ttdef"><b>Definition:</b> bwWrite.c:520</div></div>
<div class="ttc" id="abigWig_8h_html_aa3e01d7486887aa111417b688bc1a22cac10cab3311c9fe30fbabf9137cd40d57"><div class="ttname"><a href="bigWig_8h.html#aa3e01d7486887aa111417b688bc1a22cac10cab3311c9fe30fbabf9137cd40d57">dev</a></div><div class="ttdeci">@ dev</div><div class="ttdef"><b>Definition:</b> bigWig.h:108</div></div>
<div class="ttc" id="abigWig_8h_html_a633635a8da1bb1e9e5f42b5557f9872a"><div class="ttname"><a href="bigWig_8h.html#a633635a8da1bb1e9e5f42b5557f9872a">bwAddIntervalSpans</a></div><div class="ttdeci">int bwAddIntervalSpans(bigWigFile_t *fp, char *chrom, uint32_t *start, uint32_t span, float *values, uint32_t n)</div><div class="ttdoc">Add a new block of variable-step entries to a bigWig file Adds entries for the form chromosome start ...</div><div class="ttdef"><b>Definition:</b> bwWrite.c:462</div></div>
<div class="ttc" id="abigWig_8h_html_a0dc09da6beabf0c9ea3d0ca447ddff5b"><div class="ttname"><a href="bigWig_8h.html#a0dc09da6beabf0c9ea3d0ca447ddff5b">bwCreateHdr</a></div><div class="ttdeci">int bwCreateHdr(bigWigFile_t *fp, int32_t maxZooms)</div><div class="ttdoc">Create a largely empty bigWig header Every bigWig file has a header, this creates the template for on...</div><div class="ttdef"><b>Definition:</b> bwWrite.c:56</div></div>
<div class="ttc" id="abigWig_8h_html_a9b99f0c33d052d278d2e25044ca706e4"><div class="ttname"><a href="bigWig_8h.html#a9b99f0c33d052d278d2e25044ca706e4">bwIteratorDestroy</a></div><div class="ttdeci">void bwIteratorDestroy(bwOverlapIterator_t *iter)</div><div class="ttdoc">Destroys a bwOverlapIterator_t.</div><div class="ttdef"><b>Definition:</b> bwValues.c:643</div></div>
<div class="ttc" id="astructbigWigFile__t_html"><div class="ttname"><a href="structbigWigFile__t.html">bigWigFile_t</a></div><div class="ttdoc">A structure that holds everything needed to access a bigWig file.</div><div class="ttdef"><b>Definition:</b> bigWig.h:210</div></div>
<div class="ttc" id="abigWig_8h_html_af06eae8c9d405a03276c56d53e3c4fc4"><div class="ttname"><a href="bigWig_8h.html#af06eae8c9d405a03276c56d53e3c4fc4">bwStats</a></div><div class="ttdeci">double * bwStats(bigWigFile_t *fp, char *chrom, uint32_t start, uint32_t end, uint32_t nBins, enum bwStatsType type)</div><div class="ttdoc">Determines per-interval bigWig statistics Can determine mean/min/max/coverage/standard deviation of v...</div><div class="ttdef"><b>Definition:</b> bwStats.c:530</div></div>
<div class="ttc" id="abigWig_8h_html_a6a3f9298129e7fa061707739a96b36f3"><div class="ttname"><a href="bigWig_8h.html#a6a3f9298129e7fa061707739a96b36f3">bwDestroyOverlappingIntervals</a></div><div class="ttdeci">void bwDestroyOverlappingIntervals(bwOverlappingIntervals_t *o)</div><div class="ttdoc">Frees space allocated by bwGetOverlappingIntervals</div><div class="ttdef"><b>Definition:</b> bwValues.c:325</div></div>
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sun Nov 8 2020 13:48:36 for libBigWig by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>