Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / c30d2b5d4478b230246dcaaa9f1c533ca3304387 / . / docs / dyn / genomics_v1.reads.html
blob: 8a9e671a496efa526fe250eeec184380bfd790ce [file] [log] [blame]
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]1<html><body>
2<style>
3
4body, h1, h2, h3, div, span, p, pre, a {
5 margin: 0;
6 padding: 0;
7 border: 0;
8 font-weight: inherit;
9 font-style: inherit;
10 font-size: 100%;
11 font-family: inherit;
12 vertical-align: baseline;
13}
14
15body {
16 font-size: 13px;
17 padding: 1em;
18}
19
20h1 {
21 font-size: 26px;
22 margin-bottom: 1em;
23}
24
25h2 {
26 font-size: 24px;
27 margin-bottom: 1em;
28}
29
30h3 {
31 font-size: 20px;
32 margin-bottom: 1em;
33 margin-top: 1em;
34}
35
36pre, code {
37 line-height: 1.5;
38 font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
39}
40
41pre {
42 margin-top: 0.5em;
43}
44
45h1, h2, h3, p {
46 font-family: Arial, sans serif;
47}
48
49h1, h2, h3 {
50 border-bottom: solid #CCC 1px;
51}
52
53.toc_element {
54 margin-top: 0.5em;
55}
56
57.firstline {
58 margin-left: 2 em;
59}
60
61.method {
62 margin-top: 1em;
63 border: solid 1px #CCC;
64 padding: 1em;
65 background: #EEE;
66}
67
68.details {
69 font-weight: bold;
70 font-size: 14px;
71}
72
73</style>
74
75<h1><a href="genomics_v1.html">Genomics API</a> . <a href="genomics_v1.reads.html">reads</a></h1>
76<h2>Instance Methods</h2>
77<p class="toc_element">
78 <code><a href="#search">search(body, x__xgafv=None)</a></code></p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]79<p class="firstline">Gets a list of reads for one or more read group sets.</p>
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]80<p class="toc_element">
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]81 <code><a href="#search_next">search_next(previous_request, previous_response)</a></code></p>
82<p class="firstline">Retrieves the next page of results.</p>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]83<h3>Method Details</h3>
84<div class="method">
85 <code class="details" id="search">search(body, x__xgafv=None)</code>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]86 <pre>Gets a list of reads for one or more read group sets.
87
88For the definitions of read group sets and other genomics resources, see
89[Fundamentals of Google
90Genomics](https://cloud.google.com/genomics/fundamentals-of-google-genomics)
91
92Reads search operates over a genomic coordinate space of reference sequence
93& position defined over the reference sequences to which the requested
94read group sets are aligned.
95
96If a target positional range is specified, search returns all reads whose
97alignment to the reference genome overlap the range. A query which
98specifies only read group set IDs yields all reads in those read group
99sets, including unmapped reads.
100
101All reads returned (including reads on subsequent pages) are ordered by
102genomic coordinate (by reference sequence, then position). Reads with
103equivalent genomic coordinates are returned in an unspecified order. This
104order is consistent, such that two queries for the same content (regardless
105of page size) yield reads in the same order across their respective streams
106of paginated responses.
107
108Implements
109[GlobalAllianceApi.searchReads](https://github.com/ga4gh/schemas/blob/v0.5.1/src/main/resources/avro/readmethods.avdl#L85).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]110
111Args:
112 body: object, The request body. (required)
113 The object takes the form of:
114
115{ # The read search request.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]116 "readGroupSetIds": [ # The IDs of the read groups sets within which to search for reads. All
117 # specified read group sets must be aligned against a common set of reference
118 # sequences; this defines the genomic coordinates for the query. Must specify
119 # one of `readGroupSetIds` or `readGroupIds`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]120 "A String",
121 ],
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]122 "readGroupIds": [ # The IDs of the read groups within which to search for reads. All specified
123 # read groups must belong to the same read group sets. Must specify one of
124 # `readGroupSetIds` or `readGroupIds`.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]125 "A String",
126 ],
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]127 "pageSize": 42, # The maximum number of results to return in a single page. If unspecified,
128 # defaults to 256. The maximum value is 2048.
129 "start": "A String", # The start position of the range on the reference, 0-based inclusive. If
130 # specified, `referenceName` must also be specified.
131 "pageToken": "A String", # The continuation token, which is used to page through large result sets.
132 # To get the next page of results, set this parameter to the value of
133 # `nextPageToken` from the previous response.
134 "referenceName": "A String", # The reference sequence name, for example `chr1`, `1`, or `chrX`. If set to
135 # `*`, only unmapped reads are returned. If unspecified, all reads (mapped
136 # and unmapped) are returned.
137 "end": "A String", # The end position of the range on the reference, 0-based exclusive. If
138 # specified, `referenceName` must also be specified.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]139 }
140
141 x__xgafv: string, V1 error format.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]142 Allowed values
143 1 - v1 error format
144 2 - v2 error format
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]145
146Returns:
147 An object of the form:
148
149 { # The read search response.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]150 "nextPageToken": "A String", # The continuation token, which is used to page through large result sets.
151 # Provide this value in a subsequent request to return the next page of
152 # results. This field will be empty if there aren't any additional results.
153 "alignments": [ # The list of matching alignments sorted by mapped genomic coordinate,
154 # if any, ascending in position within the same reference. Unmapped reads,
155 # which have no position, are returned contiguously and are sorted in
156 # ascending lexicographic order by fragment name.
157 { # A read alignment describes a linear alignment of a string of DNA to a
158 # reference sequence, in addition to metadata
159 # about the fragment (the molecule of DNA sequenced) and the read (the bases
160 # which were read by the sequencer). A read is equivalent to a line in a SAM
161 # file. A read belongs to exactly one read group and exactly one
162 # read group set.
163 #
164 # For more genomics resource definitions, see [Fundamentals of Google
165 # Genomics](https://cloud.google.com/genomics/fundamentals-of-google-genomics)
166 #
167 # ### Reverse-stranded reads
168 #
169 # Mapped reads (reads having a non-null `alignment`) can be aligned to either
170 # the forward or the reverse strand of their associated reference. Strandedness
171 # of a mapped read is encoded by `alignment.position.reverseStrand`.
172 #
173 # If we consider the reference to be a forward-stranded coordinate space of
174 # `[0, reference.length)` with `0` as the left-most position and
175 # `reference.length` as the right-most position, reads are always aligned left
176 # to right. That is, `alignment.position.position` always refers to the
177 # left-most reference coordinate and `alignment.cigar` describes the alignment
178 # of this read to the reference from left to right. All per-base fields such as
179 # `alignedSequence` and `alignedQuality` share this same left-to-right
180 # orientation; this is true of reads which are aligned to either strand. For
181 # reverse-stranded reads, this means that `alignedSequence` is the reverse
182 # complement of the bases that were originally reported by the sequencing
183 # machine.
184 #
185 # ### Generating a reference-aligned sequence string
186 #
187 # When interacting with mapped reads, it's often useful to produce a string
188 # representing the local alignment of the read to reference. The following
189 # pseudocode demonstrates one way of doing this:
190 #
191 # out = ""
192 # offset = 0
193 # for c in read.alignment.cigar {
194 # switch c.operation {
195 # case "ALIGNMENT_MATCH", "SEQUENCE_MATCH", "SEQUENCE_MISMATCH":
196 # out += read.alignedSequence[offset:offset+c.operationLength]
197 # offset += c.operationLength
198 # break
199 # case "CLIP_SOFT", "INSERT":
200 # offset += c.operationLength
201 # break
202 # case "PAD":
203 # out += repeat("*", c.operationLength)
204 # break
205 # case "DELETE":
206 # out += repeat("-", c.operationLength)
207 # break
208 # case "SKIP":
209 # out += repeat(" ", c.operationLength)
210 # break
211 # case "CLIP_HARD":
212 # break
213 # }
214 # }
215 # return out
216 #
217 # ### Converting to SAM's CIGAR string
218 #
219 # The following pseudocode generates a SAM CIGAR string from the
220 # `cigar` field. Note that this is a lossy conversion
221 # (`cigar.referenceSequence` is lost).
222 #
223 # cigarMap = {
224 # "ALIGNMENT_MATCH": "M",
225 # "INSERT": "I",
226 # "DELETE": "D",
227 # "SKIP": "N",
228 # "CLIP_SOFT": "S",
229 # "CLIP_HARD": "H",
230 # "PAD": "P",
231 # "SEQUENCE_MATCH": "=",
232 # "SEQUENCE_MISMATCH": "X",
233 # }
234 # cigarStr = ""
235 # for c in read.alignment.cigar {
236 # cigarStr += c.operationLength + cigarMap[c.operation]
237 # }
238 # return cigarStr
239 "info": { # A map of additional read alignment information. This must be of the form
240 # map<string, string[]> (string key mapping to a list of string values).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]241 "a_key": [
242 "",
243 ],
244 },
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]245 "duplicateFragment": True or False, # The fragment is a PCR or optical duplicate (SAM flag 0x400).
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]246 "supplementaryAlignment": True or False, # Whether this alignment is supplementary. Equivalent to SAM flag 0x800.
247 # Supplementary alignments are used in the representation of a chimeric
248 # alignment. In a chimeric alignment, a read is split into multiple
249 # linear alignments that map to different reference contigs. The first
250 # linear alignment in the read will be designated as the representative
251 # alignment; the remaining linear alignments will be designated as
252 # supplementary alignments. These alignments may have different mapping
253 # quality scores. In each linear alignment in a chimeric alignment, the read
254 # will be hard clipped. The `alignedSequence` and
255 # `alignedQuality` fields in the alignment record will only
256 # represent the bases for its respective linear alignment.
257 "readGroupSetId": "A String", # The ID of the read group set this read belongs to. A read belongs to
258 # exactly one read group set.
259 "alignedQuality": [ # The quality of the read sequence contained in this alignment record
260 # (equivalent to QUAL in SAM).
261 # `alignedSequence` and `alignedQuality` may be shorter than the full read
262 # sequence and quality. This will occur if the alignment is part of a
263 # chimeric alignment, or if the read was trimmed. When this occurs, the CIGAR
264 # for this read will begin/end with a hard clip operator that will indicate
265 # the length of the excised sequence.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]266 42,
267 ],
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]268 "failedVendorQualityChecks": True or False, # Whether this read did not pass filters, such as platform or vendor quality
269 # controls (SAM flag 0x200).
270 "fragmentName": "A String", # The fragment name. Equivalent to QNAME (query template name) in SAM.
271 "readNumber": 42, # The read number in sequencing. 0-based and less than numberReads. This
272 # field replaces SAM flag 0x40 and 0x80.
273 "properPlacement": True or False, # The orientation and the distance between reads from the fragment are
274 # consistent with the sequencing protocol (SAM flag 0x2).
275 "readGroupId": "A String", # The ID of the read group this read belongs to. A read belongs to exactly
276 # one read group. This is a server-generated ID which is distinct from SAM's
277 # RG tag (for that value, see
278 # ReadGroup.name).
279 "nextMatePosition": { # An abstraction for referring to a genomic position, in relation to some # The mapping of the primary alignment of the
280 # `(readNumber+1)%numberReads` read in the fragment. It replaces
281 # mate position and mate strand in SAM.
282 # already known reference. For now, represents a genomic position as a
283 # reference name, a base number on that reference (0-based), and a
284 # determination of forward or reverse strand.
285 "position": "A String", # The 0-based offset from the start of the forward strand for that reference.
286 "reverseStrand": True or False, # Whether this position is on the reverse strand, as opposed to the forward
287 # strand.
288 "referenceName": "A String", # The name of the reference in whatever reference set is being used.
289 },
290 "numberReads": 42, # The number of reads in the fragment (extension to SAM flag 0x1).
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]291 "fragmentLength": 42, # The observed length of the fragment, equivalent to TLEN in SAM.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]292 "alignedSequence": "A String", # The bases of the read sequence contained in this alignment record,
293 # **without CIGAR operations applied** (equivalent to SEQ in SAM).
294 # `alignedSequence` and `alignedQuality` may be
295 # shorter than the full read sequence and quality. This will occur if the
296 # alignment is part of a chimeric alignment, or if the read was trimmed. When
297 # this occurs, the CIGAR for this read will begin/end with a hard clip
298 # operator that will indicate the length of the excised sequence.
299 "id": "A String", # The server-generated read ID, unique across all reads. This is different
300 # from the `fragmentName`.
301 "alignment": { # A linear alignment can be represented by one CIGAR string. Describes the # The linear alignment for this alignment record. This field is null for
302 # unmapped reads.
303 # mapped position and local alignment of the read to the reference.
304 "position": { # An abstraction for referring to a genomic position, in relation to some # The position of this alignment.
305 # already known reference. For now, represents a genomic position as a
306 # reference name, a base number on that reference (0-based), and a
307 # determination of forward or reverse strand.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]308 "position": "A String", # The 0-based offset from the start of the forward strand for that reference.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]309 "reverseStrand": True or False, # Whether this position is on the reverse strand, as opposed to the forward
310 # strand.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]311 "referenceName": "A String", # The name of the reference in whatever reference set is being used.
312 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]313 "cigar": [ # Represents the local alignment of this sequence (alignment matches, indels,
314 # etc) against the reference.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]315 { # A single CIGAR operation.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]316 "referenceSequence": "A String", # `referenceSequence` is only used at mismatches
317 # (`SEQUENCE_MISMATCH`) and deletions (`DELETE`).
318 # Filling this field replaces SAM's MD tag. If the relevant information is
319 # not available, this field is unset.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]320 "operation": "A String",
321 "operationLength": "A String", # The number of genomic bases that the operation runs for. Required.
322 },
323 ],
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]324 "mappingQuality": 42, # The mapping quality of this alignment. Represents how likely
325 # the read maps to this position as opposed to other locations.
326 #
327 # Specifically, this is -10 log10 Pr(mapping position is wrong), rounded to
328 # the nearest integer.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]329 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]330 "secondaryAlignment": True or False, # Whether this alignment is secondary. Equivalent to SAM flag 0x100.
331 # A secondary alignment represents an alternative to the primary alignment
332 # for this read. Aligners may return secondary alignments if a read can map
333 # ambiguously to multiple coordinates in the genome. By convention, each read
334 # has one and only one alignment where both `secondaryAlignment`
335 # and `supplementaryAlignment` are false.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]336 },
337 ],
338 }</pre>
339</div>
340
341<div class="method">
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]342 <code class="details" id="search_next">search_next(previous_request, previous_response)</code>
343 <pre>Retrieves the next page of results.
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]344
345Args:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]346 previous_request: The request for the previous page. (required)
347 previous_response: The response from the request for the previous page. (required)
Jon Wayne Parrott36e41bc2016-02-19 16:02:29 -0800[diff] [blame]348
349Returns:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame^]350 A request object that you can call 'execute()' on to request the next
351 page. Returns None if there are no more items in the collection.
352 </pre>
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]353</div>
354
355</body></html>