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

// This message represents a single GFF3 record.  See
// https://github.com/The-Sequence-Ontology/Specifications/blob/master/gff3.md
// for details on the file format; that document is quoted below.
//
// TODO: deal with %-encoding.
message GffRecord {
  // `range` field, reflecting the genomic location of the feature.
  // NOTE: this is a 0-based, end-exclusive interval, in contrast to the 1-based
  // encoding used natively in the GFF text format.  For reference, consult the
  // documentation for `Range`.  This field is required.
  Range range = 1;

  // `source` designation, as defined by GFF spec:
  // "The source is a free text qualifier intended to describe the algorithm or
  // operating procedure that generated this feature. Typically this is the name
  // of a piece of software, such as "Genescan" or a database name, such as
  // "Genbank." In effect, the source is used to extend the feature ontology by
  // adding a qualifier to the type creating a new composite type that is a
  // subclass of the type in the type column."
  //
  // Missingness of this field is encoded as "".
  string source = 2;

  // `type` designation, as defined by GFF spec:
  // "The type of the feature (previously called the "method"). This is
  // constrained to be either a term from the Sequence Ontology or an SO
  // accession number. The latter alternative is distinguished using the syntax
  // SO:000000. In either case, it must be sequence_feature (SO:0000110) or an
  // is_a child of it."
  //
  // Missingness of this field is encoded as "".
  string type = 3;

  // `score` designation, as defined by GFF spec:
  // "The score of the feature, a floating point number. As in earlier versions
  // of the format, the semantics of the score are ill-defined. It is strongly
  // recommended that E-values be used for sequence similarity features, and
  // that P-values be used for ab initio gene prediction features."
  //
  // Missingness of this field is encoded by -infinity.
  double score = 4;

  // TODO: factor this out (here and BED, at least)
  enum Strand {
    // The strand is unspecified, unknown, or not meaningful.
    UNSPECIFIED_STRAND = 0;
    FORWARD_STRAND = 1;
    REVERSE_STRAND = 2;
  }

  // The strand if the feature, if relevant.
  Strand strand = 5;

  // `phase` designation, as defined by the GFF spec:
  // "For features of type "CDS", the phase indicates where the feature begins
  // with reference to the reading frame. The phase is one of the integers 0, 1,
  // or 2, indicating the number of bases that should be removed from the
  // beginning of this feature to reach the first base of the next codon. In
  // other words, a phase of "0" indicates that the next codon begins at the
  // first base of the region described by the current line, a phase of "1"
  // indicates that the next codon begins at the second base of this region, and
  // a phase of "2" indicates that the codon begins at the third base of this
  // region. This is NOT to be confused with the frame, which is simply start
  // modulo 3.
  //
  // For forward strand features, phase is counted from the start field. For
  // reverse strand features, phase is counted from the end field.
  //
  // The phase is REQUIRED for all CDS features."
  //
  // Missingness of this field is encoded by -1.
  int32 phase = 6;

  // `attributes`, a free-form map of keys to string values, corresponding to
  // the semi-colon separated attributes field in the GFF text format.
  map<string, string> attributes = 7;
}

// A message encoding the directives contained in a GFF3 file header.
// Consult the file format reference for detailed descriptions of
// these directives.  Note that we do NOT handle the FASTA directive
// (a rarely-used method to bundle reference sequences within a GFF
// file.)
message GffHeader {
  // `gff_version`, a string of the format "gff-version 3.#.#"
  // encoding the exact GFF spec version used.
  string gff_version = 1;

  // `sequence_regions` is a list of the sequence regions that are
  // referenced by GFF records.
  repeated Range sequence_regions = 2;

  // An OntologyDirective holds the URI to a sequence ontology
  // database, reflecting the ontology over the entities in the
  // `type`, `source`, and `attributes` fields of a GffRecord.
  message OntologyDirective {
    string uri = 1;
  }
  repeated OntologyDirective feature_ontologies = 3;
  repeated OntologyDirective attribute_ontologies = 4;
  repeated OntologyDirective source_ontologies = 5;

  // A string name for the biological species analyzed.
  // "This directive indicates the species that the annotations apply
  // to. The preferred format is a NCBI URL that points to the
  // relevant species page in either of the following formats:
  //   http://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=6239
  //   http://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?name=Caenorhabditis+elegans"
  string species = 6;

  message GenomeBuildDirective {
    string source = 1;
    string name = 2;
  }
  GenomeBuildDirective genome_build = 7;
}

message GffReaderOptions {
}

message GffWriterOptions {
}