From f0031e0a4d6ab34b35debc33e4453247ebec6148 Mon Sep 17 00:00:00 2001
From: Pablo Cingolani <pablo.e.cingolani@gmail.com>
Date: Mon, 29 Sep 2014 19:22:21 -0400
Subject: [PATCH] Added comments clarifying how to handle coordinates in
 circular genomes

---
 src/main/resources/avro/common.avdl                 | 1 +
 src/main/resources/avro/readmethods.avdl            | 3 +++
 src/main/resources/avro/referencemethods.avdl       | 3 +++
 src/main/resources/avro/variantmethods.avdl         | 3 +++
 src/main/resources/avro/variants.avdl               | 3 +++
 src/main/resources/avro/wip/variationReference.avdl | 3 +++
 6 files changed, 16 insertions(+)

diff --git a/src/main/resources/avro/common.avdl b/src/main/resources/avro/common.avdl
index 911a8e4d..8aebe74c 100644
--- a/src/main/resources/avro/common.avdl
+++ b/src/main/resources/avro/common.avdl
@@ -33,6 +33,7 @@ record GAPosition {
 
   /**
   The 0-based offset from the start of the forward strand for that reference.
+  Genomic positions are non-negative integers less than reference length.
   */
   long position;
 
diff --git a/src/main/resources/avro/readmethods.avdl b/src/main/resources/avro/readmethods.avdl
index edf64a95..5216b814 100644
--- a/src/main/resources/avro/readmethods.avdl
+++ b/src/main/resources/avro/readmethods.avdl
@@ -33,6 +33,9 @@ record GASearchReadsRequest {
   /**
   The start position (0-based) of this query.
   If a reference is specified, this defaults to 0.
+  Genomic positions are non-negative integers less than reference length.
+  Requests spanning the join of circular genomes are represented as 
+  two requests one on each side of the join (position 0).
   */
   union { null, long } start = 0;
 
diff --git a/src/main/resources/avro/referencemethods.avdl b/src/main/resources/avro/referencemethods.avdl
index 48887096..33c4c446 100644
--- a/src/main/resources/avro/referencemethods.avdl
+++ b/src/main/resources/avro/referencemethods.avdl
@@ -171,6 +171,9 @@ example:
 record GAListReferenceBasesRequest {
   /**
   The start position (0-based) of this query. Defaults to 0.
+  Genomic positions are non-negative integers less than reference length.
+  Requests spanning the join of circular genomes are represented as
+  two requests one on each side of the join (position 0).
   */
   long start = 0;
 
diff --git a/src/main/resources/avro/variantmethods.avdl b/src/main/resources/avro/variantmethods.avdl
index b5720ad5..2cc8abde 100644
--- a/src/main/resources/avro/variantmethods.avdl
+++ b/src/main/resources/avro/variantmethods.avdl
@@ -71,6 +71,9 @@ record GASearchVariantsRequest {
   /**
   Required. The beginning of the window (0-based, inclusive) for
   which overlapping variants should be returned.
+  Genomic positions are non-negative integers less than reference length.
+  Requests spanning the join of circular genomes are represented as
+  two requests one on each side of the join (position 0).
   */
   long start;
 
diff --git a/src/main/resources/avro/variants.avdl b/src/main/resources/avro/variants.avdl
index e268accb..50cfc8f2 100644
--- a/src/main/resources/avro/variants.avdl
+++ b/src/main/resources/avro/variants.avdl
@@ -182,6 +182,9 @@ record GAVariant {
   /**
   The start position at which this variant occurs (0-based).
   This corresponds to the first base of the string of reference bases.
+  Genomic positions are non-negative integers less than reference length.
+  Variants spanning the join of circular genomes are represented as
+  two variants one on each side of the join (position 0).
   */
   long start;
 
diff --git a/src/main/resources/avro/wip/variationReference.avdl b/src/main/resources/avro/wip/variationReference.avdl
index 8e0fc012..3b3d5cfb 100644
--- a/src/main/resources/avro/wip/variationReference.avdl
+++ b/src/main/resources/avro/wip/variationReference.avdl
@@ -94,6 +94,9 @@ record GASegment {
   string variantId ;  //references an id of a GAVariant
   int start, end ;   	// start is 0-based and inclusive, end is exclusive
   // So start <= x < end if end > start, or end < x <= start if end < start.
+  // Genomic positions are non-negative integers less than reference length.
+  // Segments spanning the join of circular genomes are represented as 
+  // two segments, one on each side of the join (position 0).
   GAVariantSide side ; 
   int length ;	// alternative to end
   // if start == 0 and end == 0 then this is the whole Variant