adding outputIndividualsVCF() method

QtSLiM/QtSLiMWindow.cpp

@@ -5882,7 +5882,7 @@ void QtSLiMWindow::dumpPopulationClicked(void)
             slim_tick_t species_cycle = displaySpecies->Cycle();
 
             // dump the population: output spatial positions and ages if available, but not ancestral sequence or tags
-			Individual::PrintIndividuals(SLIM_OUTSTREAM, nullptr, 0, *displaySpecies, true, true, false, false, false, /* p_focal_chromosome */ nullptr);
+			Individual::PrintIndividuals_SLiM(SLIM_OUTSTREAM, nullptr, 0, *displaySpecies, true, true, false, false, false, /* p_focal_chromosome */ nullptr);
 
             // dump fixed substitutions also; so the dump in SLiMgui is like outputFull() + outputFixedMutations()
             SLIM_OUTSTREAM << std::endl;

QtSLiM/help/SLiMHelpClasses.html

@@ -450,14 +450,19 @@
 <p class="p6">Returns a vector containing the haplosomes of the target individual that correspond to the chromosomes passed in <span class="s1">chromosomes</span> (following the order of <span class="s1">chromosomes</span>).<span class="Apple-converted-space">  </span>Chromosomes can be specified by id (<span class="s1">integer</span>), by symbol (<span class="s1">string</span>) or by the <span class="s1">Chromosome</span> objects themselves; if <span class="s1">NULL</span> is passed (the default), all chromosomes defined for the species are used, in the order in which they were defined.</p>
 <p class="p6">For chromosomes that can be diploid (types <span class="s1">"A"</span>, <span class="s1">"X"</span>, and <span class="s1">"Z"</span>), <span class="s1">index</span> can be <span class="s1">0</span> or <span class="s1">1</span>, requesting only the first or second haplosome, respectively, for that chromosome; for other chromosome types, <span class="s1">index</span> is ignored.<span class="Apple-converted-space">  </span>If <span class="s1">includeNulls</span> is <span class="s1">T</span> (the default), any null haplosomes corresponding to the specified chromosomes are included in the result; if it is <span class="s1">F</span>, null haplosomes are excluded.<span class="Apple-converted-space">  </span>See also the properties <span class="s1">haplosomes</span>, <span class="s1">haplosomesNonNull</span>, <span class="s1">haploidGenome1</span>, <span class="s1">haploidGenome1NonNull</span>, <span class="s1">haploidGenome2</span>, and <span class="s1">haploidGenome2NonNull</span>.</p>
 <p class="p5">+ (void)outputIndividuals([Ns$ filePath = NULL], [logical$ append = F], [Niso&lt;Chromosome&gt;$ chromosome = NULL], [logical$ spatialPositions = T], [logical$ ages = T], [logical$ ancestralNucleotides = F], [logical$ pedigreeIDs = F], [logical$ individualTags = F])</p>
-<p class="p6">Output the state of the target vector of individuals.<span class="Apple-converted-space">  </span>If the optional parameter <span class="s1">filePath</span> is <span class="s1">NULL</span> (the default), output will be sent to Eidos’s output stream.<span class="Apple-converted-space">  </span>Otherwise, output will be sent to the filesystem path specified by <span class="s1">filePath</span>, overwriting that file if <span class="s1">append</span> if <span class="s1">F</span>, or appending to the end of it if <span class="s1">append</span> is <span class="s1">T</span>.<span class="Apple-converted-space">  </span>This method is quite similar to the <span class="s1">Species</span> method <span class="s1">outputFull()</span>, but (1) it can produce output for any vector of individuals, not always for the entire population; (2) it does not support output in a binary format; (3) it can produce output regarding the genetics for all chromosomes or for just one focal chromosome; and (4) there is no corresponding read method, as r<span class="s1">eadFromPopulationFile()</span> can read the data saved by <span class="s1">outputFull()</span>.</p>
+<p class="p6">Output the state of the target vector of individuals in SLiM's own format.<span class="Apple-converted-space">  </span>If the optional parameter <span class="s1">filePath</span> is <span class="s1">NULL</span> (the default), output will be sent to Eidos’s output stream.<span class="Apple-converted-space">  </span>Otherwise, output will be sent to the filesystem path specified by <span class="s1">filePath</span>, overwriting that file if <span class="s1">append</span> if <span class="s1">F</span>, or appending to the end of it if <span class="s1">append</span> is <span class="s1">T</span>.<span class="Apple-converted-space">  </span>This method is quite similar to the <span class="s1">Species</span> method <span class="s1">outputFull()</span>, but (1) it can produce output for any vector of individuals, not always for the entire population; (2) it does not support output in a binary format; (3) it can produce output regarding the genetics for all chromosomes or for just one focal chromosome; and (4) there is no corresponding read method, as r<span class="s1">eadFromPopulationFile()</span> can read the data saved by <span class="s1">outputFull()</span>.</p>
 <p class="p6">The <span class="s1">chromosome</span> parameter specifies a focal chromosome for which the genetics of the target individuals will be output.<span class="Apple-converted-space">  </span>If <span class="s1">chromosome</span> is <span class="s1">NULL</span>, all chromosomes will be output; otherwise, <span class="s1">chromosome</span> may specify the focal chromosome with an <span class="s1">integer</span> chromosome id, a <span class="s1">string</span> chromosome symbol, or a <span class="s1">Chromosome</span> object.</p>
 <p class="p6">The <span class="s1">spatialPositions</span> parameter may be used to control the output of the spatial positions of individuals in species for which continuous space has been enabled using the <span class="s1">dimensionality</span> option of <span class="s1">initializeSLiMOptions()</span>.<span class="Apple-converted-space">  </span>If <span class="s1">spatialPositions</span> is <span class="s1">F</span>, the output will not contain spatial positions.<span class="Apple-converted-space">  </span>If <span class="s1">spatialPositions</span> is <span class="s1">T</span>, spatial position information will be output if it is available.<span class="Apple-converted-space">  </span>If the species does not have continuous space enabled, the <span class="s1">spatialPositions</span> parameter will be ignored.</p>
-<p class="p6">The <span class="s1">ages</span> parameter may be used to control the output of the ages of individuals in nonWF simulations.<span class="Apple-converted-space">  </span>If <span class="s1">ages</span> is <span class="s1">F</span>, the output will not contain ages.<span class="Apple-converted-space">  </span>If <span class="s1">ages</span> is <span class="s1">T</span>, ages will be output for nonWF models.<span class="Apple-converted-space">  </span>In WF simulations, the ages parameter will be ignored.</p>
-<p class="p6">The <span class="s1">ancestralNucleotides</span> parameter may be used to control the output of the ancestral nucleotide sequence in nucleotide-based models.<span class="Apple-converted-space">  </span>If <span class="s1">ancestralNucleotides</span> is <span class="s1">F</span>, the output will not contain ancestral nucleotide information.<span class="Apple-converted-space">  </span>This option is provided because the ancestral sequence may be quite large, for models with a long chromosome.<span class="Apple-converted-space">  </span>If the model is not nucleotide-based (as enabled with the <span class="s1">nucleotideBased</span> parameter to <span class="s1">initializeSLiMOptions()</span>), the <span class="s1">ancestralNucleotides</span> parameter will be ignored.<span class="Apple-converted-space">  </span>Note that in nucleotide-based models the output format will always include the nucleotides associated with any nucleotide-based mutations; the <span class="s1">ancestralNucleotides</span> flag governs only the ancestral sequence.</p>
+<p class="p6">The <span class="s1">ages</span> parameter may be used to control the output of the ages of individuals in nonWF simulations.<span class="Apple-converted-space">  </span>If <span class="s1">ages</span> is <span class="s1">F</span>, the output will not contain ages.<span class="Apple-converted-space">  </span>If <span class="s1">ages</span> is <span class="s1">T</span>, ages will be output for nonWF models.<span class="Apple-converted-space">  </span>In WF simulations, the <span class="s1">ages</span> parameter will be ignored.</p>
+<p class="p6">The <span class="s1">ancestralNucleotides</span> parameter may be used to control the output of the ancestral nucleotide sequence in nucleotide-based models.<span class="Apple-converted-space">  </span>If <span class="s1">ancestralNucleotides</span> is <span class="s1">F</span>, the output will not contain ancestral nucleotide information.<span class="Apple-converted-space">  </span>This option is provided because the ancestral sequence may be quite large, for models with a long chromosome.<span class="Apple-converted-space">  </span>If the model is not nucleotide-based (as enabled with the <span class="s1">nucleotideBased</span> parameter to <span class="s1">initializeSLiMOptions()</span>), the <span class="s1">ancestralNucleotides</span> parameter will be ignored.<span class="Apple-converted-space">  </span>Note that in nucleotide-based models the output format will <i>always</i> include the nucleotides associated with any nucleotide-based mutations; the <span class="s1">ancestralNucleotides</span> flag governs only the ancestral sequence.</p>
 <p class="p6">The <span class="s1">pedigreeIDs</span> parameter may be used to request that pedigree IDs be written out.<span class="Apple-converted-space">  </span>This option is turned off (<span class="s1">F</span>) by default, for brevity.<span class="Apple-converted-space">  </span>This option may only be used if SLiM’s optional pedigree tracking has been enabled with <span class="s1">initializeSLiMOptions(keepPedigrees=T)</span>.</p>
 <p class="p6">Finally, the <span class="s1">individualTags</span> parameter may be used to request that tag values for all individuals be written out (and read in by <span class="s1">readFromPopulationFile()</span>, subsequently).<span class="Apple-converted-space">  </span>This option is turned off (<span class="s1">F</span>) by default, for brevity; if it turned on (<span class="s1">T</span>), the values of all tags for all individuals (specifically, the <span class="s1">tag</span>, <span class="s1">tagF</span>, <span class="s1">tagL0</span>, <span class="s1">tagL1</span>, <span class="s1">tagL2</span>, <span class="s1">tagL3</span>, and <span class="s1">tagL4</span> properties) will be written.</p>
 <p class="p6">Output is generally done in a <span class="s1">late()</span> event, so that the output reflects the state of the simulation at the end of a tick.</p>
+<p class="p5">+ (void)outputIndividualsVCF([Ns$ filePath = NULL], [logical$ append = F], [Niso&lt;Chromosome&gt;$ chromosome = NULL], [logical$ outputMultiallelics = T], [logical$ simplifyNucleotides = F], [logical$ outputNonnucleotides = T])</p>
+<p class="p6">Output the state of the target vector of individuals in VCF format.<span class="Apple-converted-space">  </span>If the optional parameter <span class="s1">filePath</span> is <span class="s1">NULL</span> (the default), output will be sent to Eidos’s output stream.<span class="Apple-converted-space">  </span>Otherwise, output will be sent to the filesystem path specified by <span class="s1">filePath</span>, overwriting that file if <span class="s1">append</span> if <span class="s1">F</span>, or appending to the end of it if <span class="s1">append</span> is <span class="s1">T</span>.<span class="Apple-converted-space">  </span>This method is quite similar to the <span class="s1">Subpopulation</span> method <span class="s1">outputVCFSample()</span>, but (1) it can produce output for any vector of individuals, rather than sampling from a single population; (2) it can produce output regarding the genetics for all chromosomes or for just one focal chromosome, whereas <span class="s1">outputVCFSample()</span> can only output data for a single chromosome; and (3) because it can output genetic information for more than one chromosome, the <span class="s1">groupAsIndividuals</span> option provided by <span class="s1">outputVCFSample()</span> is not available for <span class="s1">outputIndividualsVCF()</span>; each VCF sample has to correspond directly to one individual.</p>
+<p class="p6">The <span class="s1">chromosome</span> parameter specifies a focal chromosome for which the genetics of the target individuals will be output.<span class="Apple-converted-space">  </span>If <span class="s1">chromosome</span> is <span class="s1">NULL</span>, all chromosomes will be output (distinguished in the VCF output by the chromosome symbol output in the <span class="s1">CHROM</span> column); otherwise, <span class="s1">chromosome</span> may specify the focal chromosome with an <span class="s1">integer</span> chromosome id, a <span class="s1">string</span> chromosome symbol, or a <span class="s1">Chromosome</span> object.</p>
+<p class="p6">The parameters <span class="s1">outputMultiallelics</span>, <span class="s1">simplifyNucleotides</span>, and <span class="s1">outputNonnucleotides</span> affect the format of the output produced.</p>
+<p class="p6">Output is generally done in a <span class="s1">late()</span> event, so that the output reflects the state of the simulation at the end of a tick.</p>
 <p class="p3">–<span class="s9"> </span>(float)relatedness(object&lt;Individual&gt;<span class="s9"> </span>individuals)</p>
 <p class="p6">Returns a vector containing the degrees of relatedness between the receiver and each of the individuals in <span class="s1">individuals</span>.<span class="Apple-converted-space">  </span>The relatedness between <span class="s1">A</span> and <span class="s1">B</span> is always <span class="s1">1.0</span> if <span class="s1">A</span> and <span class="s1">B</span> are actually the same individual; this facility works even if SLiM’s optional pedigree tracking is not enabled (in which case all other relatedness values will be <span class="s1">0.0</span>).<span class="Apple-converted-space">  </span>Otherwise, if pedigree tracking is turned on with <span class="s1">initializeSLiMOptions(keepPedigrees=T)</span>, this method will use the pedigree information to construct a relatedness estimate.</p>
 <p class="p6">More specifically, this method uses all available pedigree information from the grandparental and parental pedigree records of <span class="s1">A</span> and <span class="s1">B</span> to compute an estimate of the degree of consanguinity between <span class="s1">A</span> and <span class="s1">B</span>.<span class="Apple-converted-space">  </span>Siblings have a relatedness of <span class="s1">0.5</span>, as do parents to their children and vice versa; cousins have a relatedness of <span class="s1">0.125</span>; and so forth.<span class="Apple-converted-space">  </span>If, according to the pedigree information available, <span class="s1">A</span> and <span class="s1">B</span> have no blood relationship, the value returned is <span class="s1">0.0</span>.<span class="Apple-converted-space">  </span>Note that the value returned by <span class="s1">relatedness()</span> is what is called the “coefficient of relationship” between the two individuals (Wright, 1922; <a href="https://doi.org/10.1086/279872"><span class="s12">https://doi.org/10.1086/279872</span></a>), and ranges from <span class="s1">0.0</span> to <span class="s1">1.0</span>.</p>