# Primer definition file formats

### If primer coordinates are known (recommended)

Provide a BED file with at least 4 columns: `chrom`, `chromStart`, `chromEnd`, `primerName`. Additional columns can be included: `pool`, `strand`, `sequence`, but their order must be maintained.

For example, `chrom`, `chromStart`, `chromEnd`, `primerName`, `pool` for 5-column BED format:

```
#chrom  chromStart  chromEnd  primerName     pool
seqX    0           15        primer1_LEFT   1
seqX    1745        1760      primer1_RIGHT  1
seqY    0           15        primer2_LEFT   2
seqY    1015        1030      primer2_RIGHT  2
```

And `chrom`, `chromStart`, `chromEnd`, `primerName`, `pool`, `strand`, `sequence` for 7-column BED format:

```
#chrom  chromStart  chromEnd  primerName     pool  strand  sequence
seqX    0           15        primer1_LEFT   1     +       GGGCAAACCTAAAGG
seqX    1745        1760      primer1_RIGHT  1     -       GTTATGTAAAGGTGC
seqY    0           15        primer2_LEFT   2     +       GGGCGAAACTAAAGG
seqY    1015        1030      primer2_RIGHT  2     -       GTTATGTAAAGGTGC
```

### If primer coordinates are unknown

Option 1. One line per amplicon with 3 columns: `ampliconName`, `forwardSequence`,`reverseSequence`.

```
#ampliconName  forwardSequence  reverseSequence
amplicon1      GGGCAAACCTAAAGG  GTTATGTAAAGGTGC
amplicon2      GGGCGAAACTAAAGG  GTTATGTAAAGGTGC
```

Option 2. One line per primer with 3 columns: `primerName`, `sequence`, `pool`.

```
#primerName       sequence         pool
primer1_LEFT      GGGCAAACCTAAAGG  1
primer1_LEFT_alt  GGGCGAAACTAAAGG  1
primer1_RIGHT     GTTATGTAAAGGTGC  1
```

### Formatting rules

* General
  * All text is case sensitive.
  * Any line starting with '#' is ignored. This can be used to add a header line with column names.
  * Every line must have the same number of columns and format (except those starting with '#').
  * Any number of spaces can separate the columns. A value within a single column should not have any space.
* BED format
  * Per standard BED conventions, sequence coordinates are given as 0-based, half-open intervals, such that the `chromStart` field (2nd column) contains the first nucleotide in the primer binding site and the last nucleotide in the primer binding site is the value in the `chromEnd` field (3rd column) minus 1.
  * `chrom` field must contain a sequence identifier that matches the header of the FASTA file containing the sequence that the coordinates are relative to.
  * Multiple sequence identifiers (`chrom`) are permitted within one file.
* Primer name
  * `primerName` must be unique and encode the name of the amplicon for which the primer is designed, the direction tag indicating which side of the amplicon, left or right, the primer belongs to, and an optional indicator that the primer is an alternative primer for that amplicon.
  * In addition to `_LEFT` and `_RIGHT`, we permit `_L` and `_R` as direction tags in `primerName`. Any text after the direction tag should be separated by an underscore.
  * Text in `primerName` before the direction tag is considered to be an amplicon identifier. Ensure that the text of the amplicon identifier is unique for that amplicon and that the direction tag occurs only once in `primerName`.
  * Each amplicon must have at least one left and right primer (including alternative primers) associated with it.
  * Alternative primers are used to bind to locations that avoid sequence variation in the default primer binding site that may disrupt hybridization. An amplicon may have an arbitrary number of alternative primers (as long as the primer name is unique), but most amplicons will have none. Alternative primers are indicated by the presence of the `_alt` after the direction tag in `primerName`, followed by optional text to distinguish between different alternative primers, such as a number.
  * Examples of valid primer names:
    * MY\_SEQUENCE\_434\_A\_LEFT
    * virus1\_L
    * amplicon\_4934m\_RIGHT\_alt
    * amplicon\_4934m\_RIGHT\_alt1
    * amplicon\_4934m\_R\_altprimerB
  * Examples of invalid primer names:
    * LEFT\_MY\_SEQUENCE\_434\_A
    * virus1\_l
    * amplicon\_4934m\_RIGHT\_L