new pseudo-autosomal region (PAR) recipe using multichrom

EidosScribe/EidosHelpClasses.rtf

@@ -918,11 +918,13 @@ Note that if
 
 \f4\fs20 \cf2 Returns a serialized form of the dictionary\'92s contents as a 
 \f3\fs18 string
-\f4\fs20  singleton or vector.  Four formats are supported at present, as chosen with the 
+\f4\fs20  singleton or vector.  Five formats are supported at present, as chosen with the 
 \f3\fs18 format
 \f4\fs20  parameter: 
 \f3\fs18 "slim"
-\f4\fs20  and 
+\f4\fs20 , 
+\f3\fs18 "pretty"
+\f4\fs20 , and 
 \f3\fs18 "json"
 \f4\fs20  produce a singleton string, whereas 
 \f3\fs18 "csv"

QtSLiM/help/EidosHelpClasses.html

@@ -99,7 +99,7 @@
 <p class="p4">Returns <span class="s1">T</span> if the target <span class="s1">Dictionary</span> is equal to <span class="s1">x</span> in all respects – containing the same keys, with values that are identical in the sense defined by the <span class="s1">identical()</span> function in Eidos – or returns <span class="s1">F</span> otherwise.</p>
 <p class="p4">Note that if <span class="s1">Dictionary</span> objects are contained, as values, by the dictionaries being tested for equality, they will be compared according to the standards of <span class="s1">identical()</span>, and must therefore actually be the <i>same</i> <span class="s1">Dictionary</span> object, shared by both dictionaries, for <span class="s1">isEqual()</span> to return <span class="s1">T</span>.</p>
 <p class="p3">– (string)serialize([string$ format = "slim"])</p>
-<p class="p4">Returns a serialized form of the dictionary’s contents as a <span class="s1">string</span> singleton or vector.<span class="Apple-converted-space">  </span>Four formats are supported at present, as chosen with the <span class="s1">format</span> parameter: <span class="s1">"slim"</span> and <span class="s1">"json"</span> produce a singleton string, whereas <span class="s1">"csv"</span> and <span class="s1">"tsv"</span> produce a <span class="s1">string</span> vector.<span class="Apple-converted-space">  </span>These serializations can be written to disk with <span class="s1">writeFile()</span> or <span class="s1">writeTempFile()</span>, written to the output stream with <span class="s1">cat()</span>, or used in any other way.</p>
+<p class="p4">Returns a serialized form of the dictionary’s contents as a <span class="s1">string</span> singleton or vector.<span class="Apple-converted-space">  </span>Five formats are supported at present, as chosen with the <span class="s1">format</span> parameter: <span class="s1">"slim"</span>, <span class="s1">"pretty"</span>, and <span class="s1">"json"</span> produce a singleton string, whereas <span class="s1">"csv"</span> and <span class="s1">"tsv"</span> produce a <span class="s1">string</span> vector.<span class="Apple-converted-space">  </span>These serializations can be written to disk with <span class="s1">writeFile()</span> or <span class="s1">writeTempFile()</span>, written to the output stream with <span class="s1">cat()</span>, or used in any other way.</p>
 <p class="p4">The default <span class="s1">"slim"</span> format is intended for simple, informal use where a very easily parseable string is desired.<span class="Apple-converted-space">  </span>For a simple dictionary containing only keys with singleton non-object values, this will be a semicolon-delimited string like <span class="s1">'"string1"=value1;"string2"=value2;'</span> or <span class="s1">'int1=value1;int2=value2;'</span>.<span class="Apple-converted-space">  </span>Values of type <span class="s1">string</span> will be quoted, and will be escaped with backslash escape sequences, including <span class="s1">\\</span>, <span class="s1">\"</span>, <span class="s1">\'</span>, <span class="s1">\t</span>, <span class="s1">\r</span>, and <span class="s1">\n</span>.<span class="Apple-converted-space">  </span>Values that are not singleton will be separated by spaces, such as <span class="s1">'"string1"=1 2 3;'</span>, while values that are themselves dictionaries will be delimited by braces, such as <span class="s1">'"string1"={int1=value1;int2=value2;};'</span>.<span class="Apple-converted-space">  </span>Keys that are of type <span class="s1">string</span> will be quoted (always; note that this is a change in behavior starting in SLiM 4.1) and backslash-escaped (as needed, as for <span class="s1">string</span> values); keys that are of type <span class="s1">integer</span> are not quoted.<span class="Apple-converted-space">  </span>No facility for parsing <span class="s1">"slim"</span> serializations back into Eidos is presently provided.</p>
 <p class="p4">For a more extended example, here is an input <span class="s1">Dictionary</span>, assigned into a variable <span class="s1">x</span>:</p>
 <p class="p5">x = Dictionary("a", 17, "b", 1:5, "c", c("foo", "bar"),<br>

QtSLiM/help/SLiMHelpClasses.html

@@ -285,10 +285,12 @@
 <p class="p4">Returns the number of mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the haplosome.<span class="Apple-converted-space">  </span>If you need a vector of the matching <span class="s1">Mutation</span> objects, rather than just a count, use <span class="s1">-mutationsOfType()</span><span class="s2">.</span><span class="Apple-converted-space">  </span>This method is provided for speed; it is much faster than the corresponding Eidos code.</p>
 <p class="p5">+ (integer)mutationCountsInHaplosomes([No&lt;Mutation&gt; mutations = NULL])</p>
 <p class="p6">Return an <span class="s1">integer</span> vector with the frequency counts of all of the <span class="s1">Mutation</span> objects passed in <span class="s1">mutations</span>, within the target <span class="s1">Haplosome</span> vector.<span class="Apple-converted-space">  </span>If the optional <span class="s1">mutations</span> argument is <span class="s1">NULL</span> (the default), frequency counts will be returned for all of the active <span class="s1">Mutation</span> objects in the species – the same <span class="s1">Mutation</span> objects, and in the same order, as would be returned by the <span class="s1">mutations</span> property of <span class="s1">sim</span>, in other words.</p>
-<p class="p6">See the <span class="s1">+mutationFrequenciesInHaplosomes()</span> method to obtain <span class="s1">float</span> frequencies instead of <span class="s1">integer</span> counts.<span class="Apple-converted-space">  </span>See also the <span class="s1">Species</span> methods <span class="s1">mutationCounts()</span> and <span class="s1">mutationFrequencies()</span>, which may be more efficient for getting counts/frequencies for whole subpopulations or for the whole species.</p>
+<p class="p6">In multispecies models, you might often wish to obtain counts only for mutations associated with one particular chromosome.<span class="Apple-converted-space">  </span>In that case, you would probably want to pass a vector of the mutations associated with that specific chromosome, as obtained from the <span class="s1">subsetMutations()</span> method of <span class="s1">Species</span>, rather than passing <span class="s1">NULL</span>.<span class="Apple-converted-space">  </span>(Passing <span class="s1">NULL</span> in that scenario would give you counts of <span class="s1">0</span> for all of the mutations associated with other chromosomes in the model.)</p>
+<p class="p6">See the <span class="s1">+mutationFrequenciesInHaplosomes()</span> method to obtain <span class="s1">float</span> frequencies instead of <span class="s1">integer</span> counts.<span class="Apple-converted-space">  </span>See also the <span class="s1">Species</span> methods <span class="s1">mutationCounts()</span> and <span class="s1">mutationFrequencies()</span>, which might be more efficient for getting counts/frequencies for whole subpopulations or for the whole species.</p>
 <p class="p5">+ (float)mutationFrequenciesInHaplosomes([No&lt;Mutation&gt; mutations = NULL])</p>
 <p class="p6">Return a <span class="s1">float</span> vector with the frequencies of all of the <span class="s1">Mutation</span> objects passed in <span class="s1">mutations</span>, within the target <span class="s1">Haplosome</span> vector.<span class="Apple-converted-space">  </span>If the optional <span class="s1">mutations</span> argument is <span class="s1">NULL</span> (the default), frequencies will be returned for all of the active <span class="s1">Mutation</span> objects in the species – the same <span class="s1">Mutation</span> objects, and in the same order, as would be returned by the <span class="s1">mutations</span> property of <span class="s1">sim</span>, in other words.</p>
-<p class="p6">See the <span class="s1">+mutationCountsInHaplosomes()</span> method to obtain <span class="s1">integer</span> counts instead of <span class="s1">float</span> frequencies.<span class="Apple-converted-space">  </span>See also the <span class="s1">Species</span> methods <span class="s1">mutationCounts()</span> and <span class="s1">mutationFrequencies()</span>, which may be more efficient for getting counts/frequencies for whole subpopulations or for the whole species.</p>
+<p class="p6">In multispecies models, the frequency of each mutation is assessed within the subset of target haplosomes that are associated with the same chromosome.<span class="Apple-converted-space">  </span>In other words, if a mutation is associated with chromosome 1, and the target haplosomes are associated with both chromosomes 1 and 2, the frequency of the mutation will be calculated only within the haplosomes for chromosome 1 (as you would expect).<span class="Apple-converted-space">  </span>However, you might often wish to obtain frequencies only for mutations associated with one particular chromosome.<span class="Apple-converted-space">  </span>In that case, you would probably want to pass a vector of the mutations associated with that specific chromosome, as obtained from the <span class="s1">subsetMutations()</span> method of <span class="s1">Species</span>, rather than passing <span class="s1">NULL</span>.<span class="Apple-converted-space">  </span>(Passing <span class="s1">NULL</span> in that scenario would give you frequencies of <span class="s1">0</span> for all of the mutations associated with other chromosomes in the model.)</p>
+<p class="p6">See the <span class="s1">+mutationCountsInHaplosomes()</span> method to obtain <span class="s1">integer</span> counts instead of <span class="s1">float</span> frequencies.<span class="Apple-converted-space">  </span>See also the <span class="s1">Species</span> methods <span class="s1">mutationCounts()</span> and <span class="s1">mutationFrequencies()</span>, which might be more efficient for getting counts/frequencies for whole subpopulations or for the whole species.</p>
 <p class="p3">–<span class="s9"> </span>(object&lt;Mutation&gt;)mutationsOfType(io&lt;MutationType&gt;$ mutType)</p>
 <p class="p4">Returns an <span class="s1">object</span> vector of all the mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the haplosome.<span class="Apple-converted-space">  </span>If you just need a count of the matching <span class="s1">Mutation</span> objects, rather than a vector of the matches, use <span class="s1">-countOfMutationsOfType()</span>; if you need just the positions of matching <span class="s1">Mutation</span> objects, use <span class="s1">-positionsOfMutationsOfType()</span>; and if you are aiming for a sum of the selection coefficients of matching <span class="s1">Mutation</span> objects, use <span class="s1">-sumOfMutationsOfType()</span><span class="s2">.</span><span class="Apple-converted-space">  </span>This method is provided for speed; it is much faster than the corresponding Eidos code.</p>
 <p class="p5"><span class="s3">– (is)nucleotides([Ni$ start = NULL], [Ni$ end = NULL], [string$ format = "string"])</span></p>

QtSLiM/help/SLiMHelpFunctions.html

@@ -199,6 +199,7 @@
 <p class="p3">The implementation of <span class="s3">calcFST()</span>, viewable with <span class="s3">functionSource()</span>, treats every mutation in <span class="s3">muts</span> as independent in the heterozygosity calculations; in other words, if mutations are stacked, the heterozygosity calculated is <i>by mutation</i>, not <i>by site</i>.<span class="Apple-converted-space">  </span>Similarly, if multiple <span class="s3">Mutation</span> objects exist in different haplosomes at the same site (whether representing different genetic states, or multiple mutational lineages for the same genetic state), each <span class="s3">Mutation</span> object is treated separately for purposes of the heterozygosity calculation, just as if they were at different sites.<span class="Apple-converted-space">  </span>One could regard these choices as embodying an infinite-sites interpretation of the segregating mutations.<span class="Apple-converted-space">  </span>In most biologically realistic models, such genetic states will be quite rare, and so the impact of these choices will be negligible; however, in some models these distinctions may be important.</p>
 <p class="p4">(float$)calcHeterozygosity(object&lt;Haplosome&gt; haplosomes, [No&lt;Mutation&gt; muts = NULL], [Ni$ start = NULL], [Ni$ end = NULL])</p>
 <p class="p3">Calculates the heterozygosity for a vector of haplosomes, based upon the frequencies of mutations in the haplosomes.<span class="Apple-converted-space">  </span>The result is the <i>expected</i> heterozygosity, for the individuals to which the haplosomes belong, assuming that they are under Hardy-Weinberg equilibrium; this can be compared to the <i>observed</i> heterozygosity of an individual, as calculated by <span class="s3">calcPairHeterozygosity()</span>.<span class="Apple-converted-space">  </span>Often <span class="s3">haplosomes</span> will be all of the haplosomes in a subpopulation, or in the entire population, but any haplosome vector may be used.<span class="Apple-converted-space">  </span>By default, with <span class="s3">muts=NULL</span>, the calculation is based upon all mutations in the simulation; the calculation can instead be based upon a subset of mutations, such as mutations of a specific mutation type, by passing the desired vector of mutations for <span class="s3">muts</span>.</p>
+<p class="p3">In multi-chromosome models, all of the haplosomes and mutations passed in <span class="s3">haplosomes</span> and <span class="s3">muts</span> must all be associated with the same single chromosome.<span class="Apple-converted-space">  </span>If you wish to calculate heterozygosity across multiple chromosomes, you can simply write a <span class="s3">for</span> loop that calculates it for each chromosome and combines the results; but it is not entirely clear how to weight the chromosomes to produce a single number, especially when sex chromosomes and other chromosomes of variable ploidy might be represented in <span class="s3">haplosomes</span>, so it is not done automatically by this function.</p>
 <p class="p3">The calculation can be narrowed to apply to only a window – a subrange of the full chromosome – by passing the interval bounds [<span class="s3">start</span>, <span class="s3">end</span>] for the desired window.<span class="Apple-converted-space">  </span>In this case, the vector of mutations used for the calculation will be subset to include only mutations within the specified window.<span class="Apple-converted-space">  </span>The default behavior, with <span class="s3">start</span> and <span class="s3">end</span> of <span class="s3">NULL</span>, provides the haplosome-wide heterozygosity.</p>
 <p class="p3">The implementation of <span class="s3">calcHeterozygosity()</span>, viewable with <span class="s3">functionSource()</span>, treats every mutation as independent in the heterozygosity calculations.<span class="Apple-converted-space">  </span>One could regard this choice as embodying an infinite-sites interpretation of the segregating mutations.<span class="Apple-converted-space">  </span>In most biologically realistic models, such genetic states will be quite rare, and so the impact of this choice will be negligible; however, in some models this distinction may be important.<span class="Apple-converted-space">  </span>See <span class="s3">calcPairHeterozygosity()</span> for further discussion.</p>
 <p class="p4">(float$)calcInbreedingLoad(object&lt;Haplosome&gt; haplosomes, [No&lt;MutationType&gt;$ mutType = NULL])</p>

QtSLiM/recipes.qrc

@@ -102,7 +102,6 @@
         <file>recipes/Recipe 14.3 - Reading initial simulation state from an MS output file I.txt</file>
         <file>recipes/Recipe 14.3 - Reading initial simulation state from an MS output file II.txt</file>
         <file>recipes/Recipe 14.4 - Modeling chromosomal inversions with a recombination() callback.txt</file>
-        <file>recipes/Recipe 14.5 - Modeling both X and Y Chromosomes with a Pseudo-Autosomal Region (PAR).txt</file>
         <file>recipes/Recipe 14.6 - Estimating model parameters with ABC.txt</file>
         <file>recipes/Recipe 14.7 - Tracking local ancestry along the chromosome.txt</file>
         <file>recipes/Recipe 14.8 - Live plotting with R using system().txt</file>
@@ -141,6 +140,7 @@
         <file>recipes/Recipe 15.20 - Tracking separate sexes in script, nonWF style.txt</file>
         <file>recipes/Recipe 15.21 - Modeling haplodiploidy with addRecombinant().txt</file>
         <file>recipes/Recipe 15.22 - Complex multi-chromosome inheritance with addMultiRecombinant().txt</file>
+        <file>recipes/Recipe 15.23 - Modeling pseudo-autosomal regions (PARs) with addMultiRecombinant().txt</file>
         <file>recipes/Recipe 16.1 - A simple 2D continuous-space model.txt</file>
         <file>recipes/Recipe 16.2 - Spatial competition.txt</file>
         <file>recipes/Recipe 16.3 - Boundaries and boundary conditions I (stopping boundaries).txt</file>