// Copyright 2018 Google LLC.

//

// Redistribution and use in source and binary forms, with or without

// modification, are permitted provided that the following conditions

// are met:

//

// 1. Redistributions of source code must retain the above copyright notice,

//    this list of conditions and the following disclaimer.

//

// 2. Redistributions in binary form must reproduce the above copyright

//    notice, this list of conditions and the following disclaimer in the

//    documentation and/or other materials provided with the distribution.

//

// 3. Neither the name of the copyright holder nor the names of its

//    contributors may be used to endorse or promote products derived from this

//    software without specific prior written permission.

//

// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

// POSSIBILITY OF SUCH DAMAGE.

syntax = "proto3";

package nucleus.genomics.v1;

import "third_party/nucleus/protos/cigar.proto";

import "third_party/nucleus/protos/position.proto";

import "third_party/nucleus/protos/reference.proto";

import "third_party/nucleus/protos/struct.proto";

// A linear alignment can be represented by one CIGAR string. Describes the

// mapped position and local alignment of the read to the reference.

message LinearAlignment {

  // The position of this alignment.

  Position position = 1;

  // The mapping quality of this alignment. Represents how likely

  // the read maps to this position as opposed to other locations.

  //

  // Specifically, this is -10 log10 Pr(mapping position is wrong), rounded to

  // the nearest integer.

  int32 mapping_quality = 2;

  // Represents the local alignment of this sequence (alignment matches, indels,

  // etc) against the reference.

  repeated CigarUnit cigar = 3;

}

// A read alignment describes a linear alignment of a string of DNA to a

// [reference sequence][learning.genomics.v1.Reference], in addition to metadata

// about the fragment (the molecule of DNA sequenced) and the read (the bases

// which were read by the sequencer). A read is equivalent to a line in a SAM

// file. A read belongs to exactly one read group and exactly one

// [read group set][learning.genomics.v1.ReadGroupSet].

//

// For more genomics resource definitions, see [Fundamentals of Google

// Genomics](https://cloud.google.com/genomics/fundamentals-of-google-genomics)

//

// ### Reverse-stranded reads

//

// Mapped reads (reads having a non-null `alignment`) can be aligned to either

// the forward or the reverse strand of their associated reference. Strandedness

// of a mapped read is encoded by `alignment.position.reverseStrand`.

//

// If we consider the reference to be a forward-stranded coordinate space of

// `[0, reference.length)` with `0` as the left-most position and

// `reference.length` as the right-most position, reads are always aligned left

// to right. That is, `alignment.position.position` always refers to the

// left-most reference coordinate and `alignment.cigar` describes the alignment

// of this read to the reference from left to right. All per-base fields such as

// `alignedSequence` and `alignedQuality` share this same left-to-right

// orientation; this is true of reads which are aligned to either strand. For

// reverse-stranded reads, this means that `alignedSequence` is the reverse

// complement of the bases that were originally reported by the sequencing

// machine.

//

// ### Generating a reference-aligned sequence string

//

// When interacting with mapped reads, it's often useful to produce a string

// representing the local alignment of the read to reference. The following

// pseudocode demonstrates one way of doing this:

//

//     out = ""

//     offset = 0

//     for c in read.alignment.cigar {

//       switch c.operation {

//       case "ALIGNMENT_MATCH", "SEQUENCE_MATCH", "SEQUENCE_MISMATCH":

//         out += read.alignedSequence[offset:offset+c.operationLength]

//         offset += c.operationLength

//         break

//       case "CLIP_SOFT", "INSERT":

//         offset += c.operationLength

//         break

//       case "PAD":

//         out += repeat("*", c.operationLength)

//         break

//       case "DELETE":

//         out += repeat("-", c.operationLength)

//         break

//       case "SKIP":

//         out += repeat(" ", c.operationLength)

//         break

//       case "CLIP_HARD":

//         break

//       }

//     }

//     return out

//

// ### Converting to SAM's CIGAR string

//

// The following pseudocode generates a SAM CIGAR string from the

// `cigar` field. Note that this is a lossy conversion

// (`cigar.referenceSequence` is lost).

//

//     cigarMap = {

//       "ALIGNMENT_MATCH": "M",

//       "INSERT": "I",

//       "DELETE": "D",

//       "SKIP": "N",

//       "CLIP_SOFT": "S",

//       "CLIP_HARD": "H",

//       "PAD": "P",

//       "SEQUENCE_MATCH": "=",

//       "SEQUENCE_MISMATCH": "X",

//     }

//     cigarStr = ""

//     for c in read.alignment.cigar {

//       cigarStr += c.operationLength + cigarMap[c.operation]

//     }

//     return cigarStr

//

// (== resource_for v1.reads ==)

message Read {

  // The server-generated read ID, unique across all reads. This is different

  // from the `fragmentName`.

  string id = 1;

  // The ID of the read group this read belongs to. A read belongs to exactly

  // one read group. This is a server-generated ID which is distinct from SAM's

  // RG tag (for that value, see

  // [ReadGroup.name][learning.genomics.v1.ReadGroup.name]).

  string read_group_id = 2;

  // The ID of the read group set this read belongs to. A read belongs to

  // exactly one read group set.

  string read_group_set_id = 3;

  // The fragment name. Equivalent to QNAME (query template name) in SAM.

  string fragment_name = 4;

  // The orientation and the distance between reads from the fragment are

  // consistent with the sequencing protocol (SAM flag 0x2).

  bool proper_placement = 5;

  // The fragment is a PCR or optical duplicate (SAM flag 0x400).

  bool duplicate_fragment = 6;

  // The observed length of the fragment, equivalent to TLEN in SAM.

  int32 fragment_length = 7;

  // The read number in sequencing. 0-based and less than numberReads. This

  // field replaces SAM flag 0x40 and 0x80.

  int32 read_number = 8;

  // The number of reads in the fragment (extension to SAM flag 0x1).

  int32 number_reads = 9;

  // Whether this read did not pass filters, such as platform or vendor quality

  // controls (SAM flag 0x200).

  bool failed_vendor_quality_checks = 10;

  // The linear alignment for this alignment record. This field is null for

  // unmapped reads.

  LinearAlignment alignment = 11;

  // Whether this alignment is secondary. Equivalent to SAM flag 0x100.

  // A secondary alignment represents an alternative to the primary alignment

  // for this read. Aligners may return secondary alignments if a read can map

  // ambiguously to multiple coordinates in the genome. By convention, each read

  // has one and only one alignment where both `secondaryAlignment`

  // and `supplementaryAlignment` are false.

  bool secondary_alignment = 12;

  // Whether this alignment is supplementary. Equivalent to SAM flag 0x800.

  // Supplementary alignments are used in the representation of a chimeric

  // alignment. In a chimeric alignment, a read is split into multiple

  // linear alignments that map to different reference contigs. The first

  // linear alignment in the read will be designated as the representative

  // alignment; the remaining linear alignments will be designated as

  // supplementary alignments. These alignments may have different mapping

  // quality scores. In each linear alignment in a chimeric alignment, the read

  // will be hard clipped. The `alignedSequence` and

  // `alignedQuality` fields in the alignment record will only

  // represent the bases for its respective linear alignment.

  bool supplementary_alignment = 13;

  // The bases of the read sequence contained in this alignment record,

  // **without CIGAR operations applied** (equivalent to SEQ in SAM).

  // `alignedSequence` and `alignedQuality` may be

  // shorter than the full read sequence and quality. This will occur if the

  // alignment is part of a chimeric alignment, or if the read was trimmed. When

  // this occurs, the CIGAR for this read will begin/end with a hard clip

  // operator that will indicate the length of the excised sequence.

  string aligned_sequence = 14;

  // The quality of the read sequence contained in this alignment record

  // (equivalent to QUAL in SAM). Optionally can be read from OQ tag. See

  // `SamReaderOptions` proto for more details.

  // `alignedSequence` and `alignedQuality` may be shorter than the full read

  // sequence and quality. This will occur if the alignment is part of a

  // chimeric alignment, or if the read was trimmed. When this occurs, the CIGAR

  // for this read will begin/end with a hard clip operator that will indicate

  // the length of the excised sequence.

  repeated int32 aligned_quality = 15;

  // The mapping of the primary alignment of the

  // `(readNumber+1)%numberReads` read in the fragment. It replaces

  // mate position and mate strand in SAM.

  Position next_mate_position = 16;

  // A map of additional read alignment information. This must be of the form

  // map<string, string[]> (string key mapping to a list of string values).

  map<string, ListValue> info = 17;

}

// The SamHeader message represents the metadata present in the header of a

// SAM/BAM file.

message SamHeader {

  // The VN field from the HD line.  Empty if not present (valid formats

  // will match /^[0-9]+\.[0-9]+$/).

  string format_version = 1;

  // The SO field from the HD line.

  enum SortingOrder {

    UNKNOWN = 0;

    UNSORTED = 1;

    QUERYNAME = 2;

    COORDINATE = 3;

  }

  SortingOrder sorting_order = 2;

  // The GO field from the HD line.

  enum AlignmentGrouping {

    NONE = 0;

    QUERY = 1;

    REFERENCE = 2;

  }

  AlignmentGrouping alignment_grouping = 3;

  // @SQ header field in SAM spec.

  // The order of the contigs defines the sorting order.

  repeated nucleus.genomics.v1.ContigInfo contigs = 4;

  // @RG header field in SAM spec.

  // Read groups.

  repeated ReadGroup read_groups = 5;

  // @PG header field in SAM spec.

  // A program run to generate the alignment data.

  repeated Program programs = 6;

  // @CO header field in SAM spec.

  // One-line text comments.

  repeated string comments = 7;

}

// A read group is all the data that's processed the same way by the sequencer.

// This is a sub-message of SamHeader, at the same scope to reduce verbosity.

message ReadGroup {

  // RG@ ID field in SAM spec.

  // The read group name.

  string name = 1;

  // RG@ CN field in SAM spec.

  // The name of the sequencing center producing the read.

  string sequencing_center = 2;

  // @RG DS field in SAM spec.

  // A free-form text description of this read group.

  string description = 3;

  // @RG DT field in SAM spec.

  string date = 4;

  // @RG FO field in SAM spec.

  string flow_order = 5;

  // @RG KS field in SAM spec.

  string key_sequence = 6;

  // @RG LB field in SAM spec.

  // A library is a collection of DNA fragments which have been prepared for

  // sequencing from a sample. This field is important for quality control as

  // error or bias can be introduced during sample preparation.

  string library_id = 7;

  // @RG PG field in SAM spec.

  repeated string program_ids = 8;

  // @RG PI field in SAM spec.

  // The predicted insert size of this read group. The insert size is the length

  // of the sequenced DNA fragment from end-to-end, not including the adapters.

  int32 predicted_insert_size = 9;

  // @RG PL field in SAM spec.

  // The platform/technology used to produce the reads.

  string platform = 10;

  // @RG PM field in SAM spec.

  // The platform model used as part of this run.

  string platform_model = 11;

  // @RG PU field in SAM spec.

  // The platform unit used as part of this experiment, for example

  // flowcell-barcode.lane for Illumina or slide for SOLiD. A unique identifier.

  string platform_unit = 12;

  // @RG SM field in SAM spec.

  // A client-supplied sample identifier for the reads in this read group.

  string sample_id = 13;

}

// A Program is used in the SAM header to track how alignment data is generated.

// This is a sub-message of SamHeader, at the same scope to reduce verbosity.

message Program {

  // @PG ID field in SAM spec.

  // The locally unique ID of the program. Used along with

  // `prev_program_id` to define an ordering between programs.

  string id = 2;

  // @PG PN field in SAM spec.

  // The display name of the program. This is typically the colloquial name of

  // the tool used, for example 'bwa' or 'picard'.

  string name = 3;

  // @PG CL field in SAM spec.

  // The command line used to run this program.

  string command_line = 1;

  // @PG PP field in SAM spec.

  // The ID of the program run before this one.

  string prev_program_id = 4;

  // @PG DS field in SAM spec.

  // The description of the program.

  string description = 6;

  // @PG VN field in SAM spec.

  // The version of the program run.

  string version = 5;

}

///////////////////////////////////////////////////////////////////////////////

// I/O-related messages.

///////////////////////////////////////////////////////////////////////////////

// The SamReaderOptions message is used to alter the properties of a SamReader.

// It enables reads to be omitted from parsing based on their attributes, as

// well as more fine-grained handling of particular fields within the SAM

// records.

// Next ID: 12.

message SamReaderOptions {

  // Read requirements that must be satisfied before our reader will return

  // a read to use.

  ReadRequirements read_requirements = 1;

  // How should we handle the aux fields in the SAM record?

  enum AuxFieldHandling {

    UNSPECIFIED = 0;

    SKIP_AUX_FIELDS = 1;

    PARSE_ALL_AUX_FIELDS = 2;

  }

  AuxFieldHandling aux_field_handling = 3;

  // Block size to use in htslib, in reading the SAM/BAM. Value <=0 will use the

  // default htslib block size.

  int64 hts_block_size = 4;

  // Controls if, and at what rate, we discard reads from the input stream.

  //

  // This option allows the user to efficiently remove a random fraction of

  // reads from the source SAM/BAM file. The reads are discarded on the fly

  // before being parsed into protos, so the downsampling is reasonably

  // efficient.

  //

  // If 0.0 (the default protobuf value), this field is ignored. If != 0.0, then

  // this must be a value between (0.0, 1.0] indicating the probability p that a

  // read should be kept, or equivalently (1 - p) that a read will be kept. For

  // example, if downsample_fraction is 0.25, then each read has a 25% chance of

  // being included in the output reads.

  float downsample_fraction = 5;

  // Random seed to use with downsampling fraction.

  int64 random_seed = 6;

  // By default aligned_quality field is read from QUAL in SAM. If flag is set,

  // aligned_quality field is read from OQ tag in SAM.

  bool use_original_base_quality_scores = 10;

  // By default, this field is empty. If empty, we keep all aux fields if they

  // are parsed. If set, we only keep the aux fields with the names in this

  // list.

  repeated string aux_fields_to_keep = 11;

}

// Describes requirements for a read for it to be returned by a SamReader.

message ReadRequirements {

  // By default, duplicate reads will not be kept. Set this flag to keep them.

  bool keep_duplicates = 1;

  // By default, reads that failed the vendor quality checks will not be kept.

  // Set this flag to keep them.

  bool keep_failed_vendor_quality_checks = 2;

  // By default, reads that are marked as secondary alignments will not be kept.

  // Set this flag to keep them.

  bool keep_secondary_alignments = 3;

  // By default, reads that are marked as supplementary alignments will not be

  // kept. Set this flag to keep them.

  bool keep_supplementary_alignments = 4;

  // By default, reads that aren't aligned are not kept. Set this flag to keep

  // them.

  bool keep_unaligned = 5;

  // Paired (or greater) reads that are improperly placed are not kept by

  // default. Set this flag to keep them. We define improperly placed to mean

  // reads whose (next) mate is mapped to a different contig.

  bool keep_improperly_placed = 6;

  // By default, reads with any mapping quality are kept. Setting this field

  // to a positive integer i will only keep reads that have a MAPQ >= i. Note

  // this only applies to aligned reads. If keep_unaligned is set, unaligned

  // reads, which by definition do not have a mapping quality, will still be

  // kept.

  int32 min_mapping_quality = 7;

  // Minimum base quality. This field indicates that we are enforcing a minimum

  // base quality score for a read to be used. How this field is enforced,

  // though, depends on the enum field min_base_quality_mode, as there are

  // multiple ways for this requirement to be interpreted.

  int32 min_base_quality = 8;

  // How should we enforce the min_base_quality requirement?

  enum MinBaseQualityMode {

    // If UNSPECIFIED, there are no guarantees on whether and how

    // min_base_quality would be enforced. By default we recommend

    // implementations ignore min_base_quality if this is set to UNSPECIFIED.

    UNSPECIFIED = 0;

    // The min_base_quality requirement is being enforced not by the reader but

    // by the client itself. This is commonly used when the algorithm for

    // computing whether a read satisfying the min_base_quality requirement is

    // too complex or too specific for the reader.

    ENFORCED_BY_CLIENT = 1;

  }

  MinBaseQualityMode min_base_quality_mode = 9;

}