fix #637, fix #650: VCF I/O ##contig and #CHROM should use name

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -40,7 +40,7 @@
 <p class="p3">Calling this function, added in SLiM 5, initiates the configuration of a chromosome in the species being initialized.<span class="Apple-converted-space">  </span>The new <span class="s3">Chromosome</span> object is returned, but it is still under construction and will error if used; see below for details.<span class="Apple-converted-space">  </span>That chromosome is then the “focal chromosome” for subsequent genetic initialization functions – specifically, for <span class="s3">initializeAncestralNucleotides()</span>, <span class="s3">initializeGeneConversion()</span>, <span class="s3">initializeGenomicElement()</span>, <span class="s3">initializeHotspotMap()</span>, <span class="s3">initializeMutationRate()</span>, and <span class="s3">initializeRecombinationRate()</span>.<span class="Apple-converted-space">  </span>If you wish to call <span class="s3">initializeChromosome()</span> at all (which is not required), you must call it <i>before</i> calling any of those genetic initialization functions, so that the focal chromosome is created <i>before</i> being configured further; otherwise, SLiM will assume that you want a default single-chromosome model, and when <span class="s3">initializeChromosome()</span> is called later (contradicting that assumption), an error will result.</p>
 <p class="p3">Furthermore, there are some other initialization functions must be called before <span class="s3">initializeChromosome()</span> if they are called at all – specifically, <span class="s3">initializeSex()</span>, <span class="s3">initializeTreeSeq()</span>, <span class="s3">initializeSpecies()</span>, and <span class="s3">initializeSLiMOptions()</span>.<span class="Apple-converted-space">  </span>This is so that <span class="s3">initializeChromosome()</span> knows the context within which the new chromosome is to be created; if these methods have not been called when <span class="s3">initializeChromosome()</span> is called, the default context is assumed (non-sexual, no tree-sequence recording, single-species, non-nucleotide-based), and an error will result downstream if one of those functions is later called (indicating that those assumptions might be incorrect).</p>
 <p class="p3">The parameters to <span class="s3">initializeChromosome()</span> configure the chromosome created.<span class="Apple-converted-space">  </span>They will be discussed out of order here, because that order of presentation will, I hope, be clearer.</p>
-<p class="p3">There are three parameters that in some way identify the chromosome.<span class="Apple-converted-space">  </span>First, the required <span class="s3">id</span> parameter provides an <span class="s3">integer</span> identifier for the chromosome, which can be used to look up the chromosome later in the simulation; it can be any non-negative <span class="s3">integer</span> value, but must be unique within the species (two chromosomes in the same species cannot have the same <span class="s3">id</span>).<span class="Apple-converted-space">  </span>Often it is an empirical chromosome number, for convenience and clarity; if modeling human chromosome 7, for example, you might provide <span class="s3">7</span>.<span class="Apple-converted-space">  </span>Second, the <span class="s3">symbol</span> parameter provides a <span class="s3">string</span> identifier for the chromosome, which can also be used to look up the chromosome later in the simulation.<span class="Apple-converted-space">  </span>If <span class="s3">NULL</span> (the default) is passed for <span class="s3">symbol</span>, the chromosome’s default <span class="s3">symbol</span> value will be the <span class="s3">string</span> version of its <span class="s3">id</span> (<span class="s3">"7"</span> for an <span class="s3">id</span> of <span class="s3">7</span>, for example).<span class="Apple-converted-space">  </span>The chromosome’s <span class="s3">symbol</span> value will be used to identify the chromosome in output – in VCF output, for example, and in SLiMgui.<span class="Apple-converted-space">  </span>It must be non-empty (not <span class="s3">""</span>), no more than five characters long, and unique within the species.<span class="Apple-converted-space">  </span>Third, the <span class="s3">name</span> parameter can be any <span class="s3">string</span> value; if <span class="s3">NULL</span> (the default) is passed, the <span class="s3">name</span> value will be <span class="s3">""</span>.<span class="Apple-converted-space">  </span>The <span class="s3">name</span> is not used by SLiM, and can be used in any way you wish.</p>
+<p class="p3">There are three parameters that in some way identify the chromosome.<span class="Apple-converted-space">  </span>First, the required <span class="s3">id</span> parameter provides an <span class="s3">integer</span> identifier for the chromosome, which can be used to look up the chromosome later in the simulation; it can be any non-negative <span class="s3">integer</span> value, but must be unique within the species (two chromosomes in the same species cannot have the same <span class="s3">id</span>).<span class="Apple-converted-space">  </span>Often it is an empirical chromosome number, for convenience and clarity; if modeling human chromosome 7, for example, you might provide <span class="s3">7</span>.<span class="Apple-converted-space">  </span>Second, the <span class="s3">symbol</span> parameter provides a <span class="s3">string</span> identifier for the chromosome, which can also be used to look up the chromosome later in the simulation.<span class="Apple-converted-space">  </span>If <span class="s3">NULL</span> (the default) is passed for <span class="s3">symbol</span>, the chromosome’s default <span class="s3">symbol</span> value will be the <span class="s3">string</span> version of its <span class="s3">id</span> (<span class="s3">"7"</span> for an <span class="s3">id</span> of <span class="s3">7</span>, for example).<span class="Apple-converted-space">  </span>The chromosome’s <span class="s3">symbol</span> value may be used to identify the chromosome in some types of output, and in SLiMgui.<span class="Apple-converted-space">  </span>It must be non-empty (not <span class="s3">""</span>), no more than three characters long, and unique within the species.<span class="Apple-converted-space">  </span>Third, the <span class="s3">name</span> parameter can be any <span class="s3">string</span> value; if <span class="s3">NULL</span> (the default) is passed, the <span class="s3">name</span> value will be set to the chromosome’s <span class="s3">symbol</span>.<span class="Apple-converted-space">  </span>The chromosome name is used by SLiM as a full-length identifier for the chromosome in situations where that is needed; in particular, in VCF output and input it is used as the contig <span class="s3">ID</span> and the value of the <span class="s3">CHROM</span> column.<span class="Apple-converted-space">  </span>If it is used for such purposes, it is up to the user to ensure that it obeys any necessary naming restrictions imposed by those uses.<span class="Apple-converted-space">  </span>The chromosome’s <span class="s3">name</span> value must be non-empty (not <span class="s3">""</span>), and unique within the species.</p>
 <p class="p3">The <span class="s3">length</span> parameter sets the length, in base positions, of the chromosome, and must either be <span class="s3">NULL</span>, or an <span class="s3">integer</span> greater than or equal to <span class="s3">1</span>.<span class="Apple-converted-space">  </span>If <span class="s3">length</span> is <span class="s3">NULL</span>, the length of the chromosome will be calculated after all <span class="s3">initialize()</span> callbacks have been called, as the maximum position referenced by the chromosome’s genomic elements, recombination map, mutation rate map, and (in nucleotide-based models) hotspot map; in other words, the chromosome will be sized to encompass all of the things it contains (which is also the behavior of the implicitly defined chromosome if <span class="s3">initializeChromosome()</span> is not called).<span class="Apple-converted-space">  </span>Otherwise – if <span class="s3">length</span> is specified with an <span class="s3">integer</span> value – the chromosome’s length will be fixed at that value, and the last valid base position in the chromosome will be <span class="s3">length-1</span>.<span class="Apple-converted-space">  </span>Attempting to add a genomic element or a mutation after the last position will raise an error.<span class="Apple-converted-space">  </span>Similarly, the last position of the chromosome must match the last position specified for recombination, mutation, and hotspot maps for that chromosome, but not all positions on a chromosome have to actually be used in the model (i.e., not all positions must be covered by a genomic element).</p>
 <p class="p3">The <span class="s3">type</span> parameter specifies the type of chromosome to be created.<span class="Apple-converted-space">  </span>There are numerous options, and they are somewhat complex.<span class="Apple-converted-space">  </span>They are discussed in more detail in the documentation for class <span class="s3">Chromosome</span>, particularly their specific patterns of inheritance; but they are briefly summarized here for quick reference.<span class="Apple-converted-space">  </span>Note that “–“ below indicates a null haplosome.<span class="Apple-converted-space">  </span>First of all, in hermaphroditic models <span class="s3">type</span> will generally be one of:</p>
 <p class="p5"><span class="s3">"A"</span> (autosome), the default, specifying a diploid autosomal chromosome.</p>