Skip to content

Commit

Permalink
Clarify structured vs unstructured meta-information lines
Browse files Browse the repository at this point in the history
Introduce the term "unstructured meta-information line", and reword this
section so it describes the two flavours of meta-information line clearly.
Specify that an unstructured value must not start with `<` (so that
structured/unstructured are easily distinguished) and must be non-empty.

Remove `<>` from unstructured `##pedigreeDB` example. PR samtools#88 removed
the `<>` from one instance of `##pedigreeDB=<url>` presumably on the
grounds that they were merely metasyntactic variable notation and not
intended to appear literally, but missed this instance.
  • Loading branch information
jmarshall committed Jan 4, 2022
1 parent 6835cd3 commit cf4e7ac
Showing 1 changed file with 24 additions and 10 deletions.
34 changes: 24 additions & 10 deletions VCFv4.3.tex
Original file line number Diff line number Diff line change
Expand Up @@ -100,24 +100,37 @@ \subsection{Data types}
For the Integer type, the values from $-2^{31}$ to $-2^{31}+7$ cannot be stored in the binary version and therefore are disallowed in both VCF and BCF, see \ref{BcfTypeEncoding}.

\subsection{Meta-information lines}
File meta-information is included after the \#\# string and must be key=value pairs.
Meta-information lines are optional, but if they are present then they must be completely well-formed.
Note that BCF, the binary counterpart of VCF, requires that all entries are present.
It is recommended to include meta-information lines describing the entries used in the body of the VCF file.
File meta-information lines start with ``\verb|##|'' and must appear first in the VCF file, before the header line (section~\ref{header-line}) and data record lines (section~\ref{data-lines}).
They may be either \emph{unstructured} or \emph{structured}.

An \emph{unstructured} meta-information line consists of a~\emph{key} (denoting the type of meta-information recorded) and a~\emph{value} (which may not be empty and must not start with a `\verb|<|' character), separated by an `\verb|=|' character:
\begin{quote}
\verb|##|\emph{key}\verb|=|\emph{value}
\end{quote}
Several unstructured meta-information lines are defined in this specification, notably \verb|##fileformat|.
Others not defined by this specification, e.g.\ \verb|##fileDate| and \verb|##source|, are commonly found in VCF files.
These typically have meanings that are obvious, or they are immaterial for processing the file, or both.

All structured lines that have their value enclosed within ``$<>$'' require an ID which must be unique within their type.
For all of the structured lines (\#\#INFO, \#\#FORMAT, \#\#FILTER, etc.), extra fields can be included after the default fields.
A \emph{structured} meta-information line is similar, but the value is itself a comma-separated list of key=value pairs, enclosed within `\verb|<|' and `\verb|>|' characters:
\begin{quote}
\verb|##|\emph{key}\verb|=<|\emph{key}\verb|=|\emph{value}\verb|,|\emph{key}\verb|=|\emph{value}\verb|,|\emph{key}\verb|=|\emph{value}\verb|,|\ldots\verb|>|
\end{quote}
All structured lines require an ID which must be unique within their type, i.e., within all the meta-information lines with the same ``\verb|##|\emph{key}\verb|=|'' prefix.
For all of the structured lines (\verb|##INFO|, \verb|##FORMAT|, \verb|##FILTER|, etc.), extra fields can be included after the default fields.
For example:
\begin{verbatim}
##INFO=<ID=ID,Number=number,Type=type,Description="description",Source="description",Version="128">
##INFO=<ID=ID,Number=number,Type=type,Description="description",Source="source",Version="128">
\end{verbatim}
In the above example, the extra fields of ``Source'' and ``Version'' are provided.
Optional fields must be stored as strings even for numeric values.
The values of optional fields must be written as quoted strings, even for numeric values.

It is recommended in VCF and required in BCF that the header includes tags describing the reference and contigs backing the data contained in the file.
These tags are based on the SQ field from the SAM spec; all tags are optional (see the VCF example above).

Meta-information lines can be in any order with the exception of `fileformat` which must come first.
Meta-information lines are optional, but if they are present then they must be completely well-formed.
Other than \verb|##fileformat|, they may appear in any order.
Note that BCF, the binary counterpart of VCF, requires that all entries are present.
It is recommended to include meta-information lines describing the entries used in the body of the VCF file.


\subsubsection{File format}
Expand Down Expand Up @@ -266,6 +279,7 @@ \subsubsection{Pedigree field format}
\subsection{Header line syntax}
\label{header-line}
The header line names the 8 fixed, mandatory columns. These columns are as follows:
\begin{center}
\#CHROM
Expand Down Expand Up @@ -1306,7 +1320,7 @@ \subsubsection{Clonal derivation relationships}
Alternately, if data on the genomes is compiled in a database, a simple pointer can be provided:
\begin{verbatim}
##pedigreeDB=<url>
##pedigreeDB=URL
\end{verbatim}
\begin{samepage}
Expand Down

0 comments on commit cf4e7ac

Please sign in to comment.