// 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/reference.proto";

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

// A variant represents a change in DNA sequence relative to a reference

// sequence. For example, a variant could represent a SNP or an insertion.

//

// The definition of the Variant message closely follows the common VCF variant

// representation.

//

// Each of the calls on a variant represent a determination of genotype with

// respect to that variant. For example, a call might assign probability of 0.32

// to the occurrence of a SNP named rs1234 in a sample named NA12345.

// NextID: 17

message Variant {

  reserved 1, 4, 5;

  // The reference on which this variant occurs.

  // (such as `chr20` or `X`)

  // Corresponds to the "CHROM" field of VCF 4.3.

  string reference_name = 14;

  // The position at which this variant occurs (0-based inclusive).

  // This corresponds to the first base of the string of reference bases.

  int64 start = 16;

  // The end position (0-based exclusive) of this variant. This corresponds to

  // the first base after the last base in the reference allele. So, the length

  // of the reference allele is (end - start). This is useful for variants

  // that don't explicitly give alternate bases, for example large deletions.

  int64 end = 13;

  // Names for the variant, for example a dbSNP ID.

  // Corresponds to the "ID" field of VCF 4.3.

  repeated string names = 3;

  // The reference bases for this variant. They start at the given

  // position.

  string reference_bases = 6;

  // The bases that appear instead of the reference bases.

  repeated string alternate_bases = 7;

  // A measure of how likely this variant is to be real.

  // A higher value is better.

  // Since this is a Phred-scaled probability (i.e. is -10 * log_10(p) for some

  // p, which depends on whether this is a variant or non-variant site) it is

  // guaranteed to be non-negative. We use -1 to represent the `unset` value.

  double quality = 8;

  // A list of filters (normally quality filters) this variant has failed.

  // `PASS` indicates this variant has passed all filters.

  repeated string filter = 9;

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

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

  map<string, ListValue> info = 10;

  // The variant calls for this particular variant. Each one represents the

  // determination of genotype with respect to this variant.

  repeated VariantCall calls = 11;

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

  // DEPRECATED or unused fields of the Variant proto below.

  // These are relics of the Google Genomics API and/or are used to support

  // GA4GH specs.

  //

  // The ID of the variant set this variant belongs to.

  // DEPRECATED.

  string variant_set_id = 15;

  // The server-generated variant ID, unique across all variants.

  // DEPRECATED.

  string id = 2;

  // The date this variant was created, in milliseconds from the epoch.

  // (-- GA4GH also specifies an "updated" timestamp. --)

  // DEPRECATED.

  int64 created = 12;

}

// A call represents the determination of genotype with respect to a particular

// variant. It may include associated information such as quality and phasing.

// For example, a call might assign a probability of 0.32 to the occurrence of

// a SNP named rs1234 in a call set with the name NA12345.

// NextID: 10

message VariantCall {

  reserved 1, 3, 4;

  // The name of the call set this variant call belongs to. Also known as

  // "sample".

  string call_set_name = 9;

  // The genotype of this variant call. Each value represents either the value

  // of the `referenceBases` field or a 1-based index into `alternateBases`. If

  // a variant had a `referenceBases` value of `T` and an `alternateBases` value

  // of `["A", "C"]`, and the `genotype` was `[2, 1]`, that would mean the call

  // represented the heterozygous value `CA` for this variant. If the `genotype`

  // was instead `[0, 1]`, the represented value would be `TA`. Ordering of the

  // genotype values is important if the `phaseset` is present ('PS' field in

  // the call.info map). Uncalled genotypes (represented as `.` in the GT

  // string) are represented by -1 in this array.

  repeated int32 genotype = 7;

  // If true, this variant call's genotype ordering implies the phase of the

  // bases and is consistent with any other variant calls in the same reference

  // sequence which have the same phaseset value (the integer 'PS' field in the

  // call.info map). If this is true but the 'PS' field is not set, the call is

  // assumed to be phased with all other calls for which the same state applies.

  bool is_phased = 10;

  // DEPRECATED. This previously was used as a special-cased field for capturing

  // phasing information. This field should no longer be set, in favor of using

  // the 'PS' field in the call.info map and the `is_phased` boolean attribute.

  string phaseset = 5;  // DEPRECATED.

  // The genotype log10-likelihoods for this variant call. Each array entry

  // represents how likely a specific genotype is for this call. The value

  // ordering is defined by the GL tag in the VCF spec.

  // If Phred-scaled genotype likelihood scores (PL) are available and

  // log10(P) genotype likelihood scores (GL) are not, PL scores are converted

  // to GL scores.  If both are available, the GL scores are stored here and

  // PL scores are omitted (as they are just a lower-resolution representation

  // of GL scores).

  repeated double genotype_likelihood = 6;

  // A map of additional variant call information. This must be of the form

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

  map<string, ListValue> info = 2;

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

  // DEPRECATED or unused fields of the VariantCall proto below.

  // These are relics of the Google Genomics API and/or are used to support

  // GA4GH specs.

  //

  // The ID of the call set this variant call belongs to.

  string call_set_id = 8;

}

// This record type mirrors a VCF header. See

// https://samtools.github.io/hts-specs/VCFv4.3.pdf for details on the spec.

message VcfHeader {

  // The required first line of the VCF. Values e.g. "VCFv4.3".

  string fileformat = 1;

  // The list of contigs used to produce this VCF. All variants within the VCF

  // must lie on a contig represented here. All contigs must have distinct IDs.

  repeated ContigInfo contigs = 2;

  // A list of all filters used to produce this VCF. All variants within the VCF

  // must only use filters represented here. All filters must have distinct IDs.

  repeated VcfFilterInfo filters = 3;

  // A list of all info tags used to annotate variants within the VCF. All info

  // fields present in Variants must only use infos with IDs represented here.

  // All infos must have distinct IDs.

  repeated VcfInfo infos = 4;

  // A list of all format fields used to annotate genotypes within the VCF. All

  // fields present in VariantCalls must only use formats with IDs represented

  // here. All formats must have distinct IDs.

  repeated VcfFormatInfo formats = 5;

  // An ordered list of all the sample names present in the VCF. All Variants

  // within the VCF must contain `len(sample_names)` VariantCalls and must be

  // in the same order. I.e. for any Variant v,

  // v.calls[i].call_set_name == sample_names[i] for all i.

  repeated string sample_names = 6;

  // A list of all header lines that are not one represented above, represented

  // in a key=value format. The key within the extras may be duplicated.

  repeated VcfStructuredExtra structured_extras = 8;

  // A list of all header lines that are not one represented above, represented

  // in an unstructured format. The key within the extras may be duplicated.

  repeated VcfExtra extras = 7;

}

// The below messages are sub-messages of the VCF header. They are not nested

// within VcfHeader simply to avoid verbosity.

//

// We comment fields in one of three states:

// "Required": Required by both the VCF file format and for downstream users of

//             Variant and VariantCall protos.

// "Required by VCF": Required by the VCF file format, unused otherwise.

// "Optional": Optional within the VCF file format, unused otherwise.

//

// This record type mirrors a VCF "FILTER" header.

message VcfFilterInfo {

  // Required. The unique ID of the filter. Examples include "PASS", "RefCall".

  string id = 1;

  // Required by VCF. The description of the filter.

  string description = 2;

}

// This message type mirrors a VCF "INFO" header.

message VcfInfo {

  // Required. The unique ID of the INFO field. Examples include "MQ0" or "END".

  string id = 1;

  // Required. The number of values included with the info field. This should be

  // the string representation of the number, e.g. "1" for a single entry, "2"

  // for a pair of entries, etc. Special cases arise when the number of entries

  // depend on attributes of the Variant or are unknown in advance, and include:

  // "A": The field has one value per alternate allele.

  // "R": The field has one value per allele (including the reference).

  // "G": The field has one value for each possible genotype.

  // ".": The number of values varies, is unknown, or is unbounded.

  string number = 2;

  // Required. The type of the INFO field. Valid values are "Integer", "Float",

  // "Flag", "Character", and "String".

  string type = 3;

  // Required by VCF. The description of the field.

  string description = 4;

  // Optional. The annotation source used to generate the field.

  string source = 5;

  // Optional. The version of the annotation source used to generate the field.

  string version = 6;

}

// This record type mirrors a VCF "FORMAT" header.

message VcfFormatInfo {

  // Required. The unique ID of the FORMAT field. Examples include "GT", "PL".

  string id = 1;

  // Required. The number of entries expected. See description above in the

  // VcfInfo message.

  string number = 2;

  // Required. The type of the field. Valid values are "Integer", "Float",

  // "Character", and "String" (same as INFO except "Flag" is not supported).

  string type = 3;

  // Required by VCF. The description of the field.

  string description = 4;

}

// This record type is a catch-all for other headers containing multiple

// key-value pairs. For example, headers may have META lines that provide

// metadata about the VCF as a whole, e.g.

// ##META=<ID=Assay,Type=String,Number=.,Values=[WholeGenome, Exome]>

// The VcfStructuredExtra message would represent this with key="META",

// and fields mapping "ID" -> "Assay", "Type" -> "String", etc.

message VcfStructuredExtra {

  // Required by VCF. The key of the extra header field. Note that this key does

  // not have to be unique within a VcfHeader.

  string key = 1;

  // Required by VCF. The key=value pairs contained in the structure.

  repeated VcfExtra fields = 2;

}

// This record type is a catch-all for other types of headers. For example,

// ##pedigreeDB=http://url_of_pedigrees

// The VcfExtra message would represent this with key="pedigreeDB",

// value="http://url_of_pedigrees".

message VcfExtra {

  // Required by VCF. The key of the extra header field. Note that this key does

  // not have to be unique within a VcfHeader.

  string key = 1;

  // Required by VCF. The value of the extra header field.

  string value = 2;

}

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

// I/O-related messages.

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

// The Vcf{Reader,Writer}Options messages are used to alter the properties of

// reading and writing variants. They enables certain fields to be omitted from

// parsing.

message VcfReaderOptions {

  reserved 1, 2;

  // A list of all INFO field IDs that should be excluded from parsing.

  repeated string excluded_info_fields = 3;

  // A list of all FORMAT field IDs that should be excluded from parsing.

  repeated string excluded_format_fields = 4;

  // If true, the GL and PL format tags are stored in the VariantCall.info map

  // with the type and number as specified in the VCF header, similar to other

  // FORMAT fields. Otherwise, the GL and PL tags are special-cased and

  // available in the VariantCall.genotype_likelihood field, with the

  // enforcement that each is of type=Float and Number=G.

  bool store_gl_and_pl_in_info_map = 5;

}

message VcfWriterOptions {

  reserved 1, 2, 3, 4, 5;

  // A list of all INFO field IDs that should be excluded from writing.

  repeated string excluded_info_fields = 7;

  // A list of all FORMAT field IDs that should be excluded from writing.

  repeated string excluded_format_fields = 8;

  // Should QUAL field values be rounded to one point past the decimal?

  bool round_qual_values = 6;

  // If true, the GL and PL format tags are written from the VariantCall.info

  // map with the type and number as specified in the VCF header. In this case,

  // any values set in the VariantCall.genotype_likelihood field are ignored.

  // Otherwise, the GL and PL tags are retrieved from the

  // VariantCall.genotype_likelihood field, with the enforcement that each is of

  // type=Float and Number=G, and neither GL nor PL should be present in the

  // VariantCall.info map.

  bool retrieve_gl_and_pl_from_info_map = 9;

  // If true, the writer will skip writing the VcfHeader.

  bool exclude_header = 10;

}