Takashi Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 1 | <html><body> |
| 2 | <style> |
| 3 | |
| 4 | body, 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 | |
| 15 | body { |
| 16 | font-size: 13px; |
| 17 | padding: 1em; |
| 18 | } |
| 19 | |
| 20 | h1 { |
| 21 | font-size: 26px; |
| 22 | margin-bottom: 1em; |
| 23 | } |
| 24 | |
| 25 | h2 { |
| 26 | font-size: 24px; |
| 27 | margin-bottom: 1em; |
| 28 | } |
| 29 | |
| 30 | h3 { |
| 31 | font-size: 20px; |
| 32 | margin-bottom: 1em; |
| 33 | margin-top: 1em; |
| 34 | } |
| 35 | |
| 36 | pre, code { |
| 37 | line-height: 1.5; |
| 38 | font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace; |
| 39 | } |
| 40 | |
| 41 | pre { |
| 42 | margin-top: 0.5em; |
| 43 | } |
| 44 | |
| 45 | h1, h2, h3, p { |
| 46 | font-family: Arial, sans serif; |
| 47 | } |
| 48 | |
| 49 | h1, 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 Cheemalapati | c30d2b5 | 2017-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 Parrott | 36e41bc | 2016-02-19 16:02:29 -0800 | [diff] [blame] | 80 | <p class="toc_element"> |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-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 Cheemalapati | c30d2b5 | 2017-03-13 12:12:03 -0400 | [diff] [blame^] | 86 | <pre>Gets a list of reads for one or more read group sets. |
| 87 | |
| 88 | For the definitions of read group sets and other genomics resources, see |
| 89 | [Fundamentals of Google |
| 90 | Genomics](https://cloud.google.com/genomics/fundamentals-of-google-genomics) |
| 91 | |
| 92 | Reads search operates over a genomic coordinate space of reference sequence |
| 93 | & position defined over the reference sequences to which the requested |
| 94 | read group sets are aligned. |
| 95 | |
| 96 | If a target positional range is specified, search returns all reads whose |
| 97 | alignment to the reference genome overlap the range. A query which |
| 98 | specifies only read group set IDs yields all reads in those read group |
| 99 | sets, including unmapped reads. |
| 100 | |
| 101 | All reads returned (including reads on subsequent pages) are ordered by |
| 102 | genomic coordinate (by reference sequence, then position). Reads with |
| 103 | equivalent genomic coordinates are returned in an unspecified order. This |
| 104 | order is consistent, such that two queries for the same content (regardless |
| 105 | of page size) yield reads in the same order across their respective streams |
| 106 | of paginated responses. |
| 107 | |
| 108 | Implements |
| 109 | [GlobalAllianceApi.searchReads](https://github.com/ga4gh/schemas/blob/v0.5.1/src/main/resources/avro/readmethods.avdl#L85). |
Takashi Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 110 | |
| 111 | Args: |
| 112 | body: object, The request body. (required) |
| 113 | The object takes the form of: |
| 114 | |
| 115 | { # The read search request. |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 120 | "A String", |
| 121 | ], |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 125 | "A String", |
| 126 | ], |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 139 | } |
| 140 | |
| 141 | x__xgafv: string, V1 error format. |
Sai Cheemalapati | c30d2b5 | 2017-03-13 12:12:03 -0400 | [diff] [blame^] | 142 | Allowed values |
| 143 | 1 - v1 error format |
| 144 | 2 - v2 error format |
Takashi Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 145 | |
| 146 | Returns: |
| 147 | An object of the form: |
| 148 | |
| 149 | { # The read search response. |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 241 | "a_key": [ |
| 242 | "", |
| 243 | ], |
| 244 | }, |
Jon Wayne Parrott | 36e41bc | 2016-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 Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 266 | 42, |
| 267 | ], |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 291 | "fragmentLength": 42, # The observed length of the fragment, equivalent to TLEN in SAM. |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-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 Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-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 Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 315 | { # A single CIGAR operation. |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-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 Cheemalapati | c30d2b5 | 2017-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 Parrott | 36e41bc | 2016-02-19 16:02:29 -0800 | [diff] [blame] | 329 | }, |
Sai Cheemalapati | c30d2b5 | 2017-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 Parrott | 36e41bc | 2016-02-19 16:02:29 -0800 | [diff] [blame] | 336 | }, |
| 337 | ], |
| 338 | }</pre> |
| 339 | </div> |
| 340 | |
| 341 | <div class="method"> |
Sai Cheemalapati | c30d2b5 | 2017-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 Parrott | 36e41bc | 2016-02-19 16:02:29 -0800 | [diff] [blame] | 344 | |
| 345 | Args: |
Sai Cheemalapati | c30d2b5 | 2017-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 Parrott | 36e41bc | 2016-02-19 16:02:29 -0800 | [diff] [blame] | 348 | |
| 349 | Returns: |
Sai Cheemalapati | c30d2b5 | 2017-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 Matsuo | 0669410 | 2015-09-11 13:55:40 -0700 | [diff] [blame] | 353 | </div> |
| 354 | |
| 355 | </body></html> |