change policy on the default symbol for an implicit chromosome

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -130,7 +130,7 @@
 <p class="p3">species =&gt; (object&lt;Species&gt;$)</p>
 <p class="p6"><span class="s3">The species to which the target object belongs.</span></p>
 <p class="p5">symbol =&gt; (string$)</p>
-<p class="p6">The symbol for the chromosome, as given to <span class="s1">initializeChromosome()</span>.<span class="Apple-converted-space">  </span>For an implicitly defined chromosome, the <span class="s1">symbol</span> will be <span class="s1">"1"</span>.<span class="Apple-converted-space">  </span>The <span class="s1">symbol</span> can be used to refer to the chromosome; see also <span class="s1">id</span>.</p>
+<p class="p6">The symbol for the chromosome, as given to <span class="s1">initializeChromosome()</span>; see the documentation for that function.<span class="Apple-converted-space">  </span>For an implicitly defined chromosome, the symbol is <span class="s1">"A"</span> for non-sexual models, and for sexual models (for historical reasons) is determined by the model type passed to <span class="s1">initializeSex()</span> as documented there.<span class="Apple-converted-space">  </span>The <span class="s1">symbol</span> can be used to refer to the chromosome; see also <span class="s1">id</span>.</p>
 <p class="p3">tag &lt;–&gt; (integer$)</p>
 <p class="p4">A user-defined <span class="s1">integer</span> value.<span class="Apple-converted-space">  </span>The value of <span class="s1">tag</span> is initially undefined<span class="s7">, and it is an error to try to read it</span>; if you wish it to have a defined value, you must arrange that yourself by explicitly setting its value prior to using it elsewhere in your code.<span class="Apple-converted-space">  </span>The value of <span class="s1">tag</span> is not used by SLiM; it is free for you to use.</p>
 <p class="p5">type =&gt; (string$)</p>

QtSLiM/help/SLiMHelpFunctions.html

@@ -111,9 +111,9 @@
 <p class="p3">There are two ways to call this function.<span class="Apple-converted-space">  </span>If the optional <span class="s3">ends</span> parameter is <span class="s3">NULL</span> (the default), then <span class="s3">rates</span> must be a singleton value that specifies a single recombination rate to be used along the entire chromosome.<span class="Apple-converted-space">  </span>If, on the other hand, <span class="s3">ends</span> is supplied, then <span class="s3">rates</span> and <span class="s3">ends</span> must be the same length, and the values in <span class="s3">ends</span> must be specified in ascending order.<span class="Apple-converted-space">  </span>In that case, <span class="s3">rates</span> and <span class="s3">ends</span> taken together specify the recombination rates to be used along successive contiguous stretches of the chromosome, from beginning to end; the last position specified in <span class="s3">ends</span> should extend to the end of the chromosome (i.e. at least to the end of the last genomic element, if not further).</p>
 <p class="p3">If the optional <span class="s3">sex</span> parameter is <span class="s3">"*"</span> (the default), then the supplied recombination rate map will be used for both sexes (which is the only option for hermaphroditic simulations).<span class="Apple-converted-space">  </span>In sexual simulations <span class="s3">sex</span> may be <span class="s3">"M"</span> or <span class="s3">"F"</span> instead, in which case the supplied recombination map is used only for that sex.<span class="Apple-converted-space">  </span>In this case, two calls must be made to <span class="s3">initializeRecombinationRate()</span>, one for each sex, even if a rate of zero is desired for the other sex; no default recombination map is supplied.</p>
 <p class="p4">(void)initializeSex([Ns$ chromosomeType = NULL])</p>
-<p class="p3">Enable sex in the simulation.<span class="Apple-converted-space">  </span>Beginning in SLiM 5, this method should generally be passed <span class="s3">NULL</span>, simply indicating that sex should be enabled: individuals will be male and female (rather than hermaphroditic), biparental crosses will be required to be between a female first parent and a male second parent, and selfing will not be allowed.<span class="Apple-converted-space">  </span>There is no way to disable sex once it has been enabled; if you don’t want to have sex, don’t call this function.</p>
-<p class="p3">In this new configuration style, if a sexual simulation involving sex chromosomes is desired, the new <span class="s3">initializeChromosome()</span> call should be used to configure the chromosome setup for the simulation (see the <span class="s3">initializeChromosome()</span> documentation in section 25.1).</p>
-<p class="p3">For backward compatibility, the old style of configuring a sexual simulation is still supported, however.<span class="Apple-converted-space">  </span>In this style, the argument <span class="s3">chromosomeType</span> gives the type of chromosome to be simulated; this should be <span class="s3">"A"</span>, <span class="s3">"X"</span>, or <span class="s3">"Y"</span>.<span class="Apple-converted-space">  </span>These correspond to the new chromosome types <span class="s3">"A"</span>, <span class="s3">"X"</span>, and <span class="s3">"-Y"</span> (not <span class="s3">"Y"</span>), respectively, when using <span class="s3">initializeChromosome()</span>.<span class="Apple-converted-space">  </span>This old style of chromosome configuration is much less flexible, however, allowing fewer chromosome types, and only allowing a single chromosome to be set up.<span class="Apple-converted-space">  </span>This backward compatibility mode may be removed for SLiM in the future, and should be considered deprecated.</p>
+<p class="p3">Enable sex in the simulation.<span class="Apple-converted-space">  </span>Beginning in SLiM 5, this method should generally be passed <span class="s3">NULL</span>, simply indicating that sex should be enabled: individuals will then be male and female (rather than hermaphroditic), biparental crosses will be required to be between a female first parent and a male second parent, and selfing will not be allowed.<span class="Apple-converted-space">  </span>In this new configuration style, if a sexual simulation involving sex chromosomes is desired, the new <span class="s3">initializeChromosome()</span> call should be used to configure the chromosome setup for the simulation.</p>
+<p class="p3">For backward compatibility, the old style of configuring a sexual simulation is still supported, however.<span class="Apple-converted-space">  </span>This implicitly defines a single chromosome, without a call to <span class="s3">initializeChromosome()</span>.<span class="Apple-converted-space">  </span>With this old configuration approach, the <span class="s3">chromosomeType</span> parameter to <span class="s3">initializeSex()</span> gives the type of chromosome that should be simulated; this should be <span class="s3">"A"</span>, <span class="s3">"X"</span>, or <span class="s3">"Y"</span>, and this <span class="s3">chromosomeType</span> value will be used as the symbol (<span class="s3">"A"</span>, <span class="s3">"X"</span>, or <span class="s3">"Y"</span>) for the implicit chromosome.<span class="Apple-converted-space">  </span>These legacy chromosome types correspond to the new chromosome types <span class="s3">"A"</span>, <span class="s3">"X"</span>, and <span class="s3">"-Y"</span> respectively (note that it is <i>not</i> <span class="s3">"Y"</span>), when using <span class="s3">initializeChromosome()</span>.<span class="Apple-converted-space">  </span>The implicit chromosome’s <span class="s3">id</span> property is always <span class="s3">1</span>.<span class="Apple-converted-space">  </span>This old style of chromosome configuration is much less flexible, however, allowing only these three chromosome types, and only allowing a single chromosome to be set up.<span class="Apple-converted-space">  </span>This backward compatibility mode may be removed for SLiM in the future, and should be considered deprecated; new models should call <span class="s3">initializeChromosome()</span> explicitly instead.</p>
+<p class="p3">There is no way to disable sex once it has been enabled; if you don’t want to have sex, don’t call this function.<span class="Apple-converted-space">  </span>If you require more flexibility with mating types and reproductive strategies than SLiM’s built-in support for sex provides, do not call <span class="s3">initializeSex()</span>; instead, track the sex or mating type of individuals yourself in script (with the <span class="s3">tag</span> property of <span class="s3">Individual</span>, for example), and manage the consequences of that in your script yourself, in terms of which individuals can mate with which, and exactly how the offspring is produced.</p>
 <p class="p9"><span class="s8"><b>The </b></span><span class="s9"><b>xDominanceCoeff</b></span><span class="s8"><b> parameter has been deprecated and removed.</b><span class="Apple-converted-space">  </span>In SLiM 5 and later, use the </span><span class="s9">hemizygousDominanceCoeff</span><span class="s8"> property of </span><span class="s9">MutationType</span><span class="s8"> instead.<span class="Apple-converted-space">  </span></span>If the <span class="s3">chromosomeType</span> is <span class="s3">"X"</span>, the optional <span class="s3">xDominanceCoeff</span> parameter can supply the dominance coefficient used when a mutation is present in an XY male, and is thus “heterozygous” (but in a different sense than the heterozygosity of an XX female with one copy of the mutation).</p>
 <p class="p2">(void)initializeSLiMModelType(string$ modelType)</p>
 <p class="p3"><span class="s1">Configure the type of SLiM model used for the simulation.<span class="Apple-converted-space">  </span>At present, one of two model types may be selected.<span class="Apple-converted-space">  </span>If </span><span class="s2">modelType</span><span class="s1"> is </span><span class="s2">"WF"</span><span class="s1">, SLiM will use a Wright-Fisher (WF) model; this is the model type that has always been supported by SLiM, and is the model type used if </span><span class="s2">initializeSLiMModelType()</span><span class="s1"> is not called.<span class="Apple-converted-space">  </span>If </span><span class="s2">modelType</span><span class="s1"> is </span><span class="s2">"nonWF"</span><span class="s1">, SLiM will use a non-Wright-Fisher (nonWF) model instead; this is a new model type supported by SLiM 3.0 and above.</span></p>

SLiMgui/SLiMHelpClasses.rtf

@@ -397,11 +397,11 @@ The species to which the target object belongs.\
 
 \f4\fs20 \cf2 The symbol for the chromosome, as given to 
 \f3\fs18 initializeChromosome()
-\f4\fs20 .  For an implicitly defined chromosome, the 
-\f3\fs18 symbol
-\f4\fs20  will be 
-\f3\fs18 "1"
-\f4\fs20 .  The 
+\f4\fs20 ; see the documentation for that function.  For an implicitly defined chromosome, the symbol is 
+\f3\fs18 "A"
+\f4\fs20  for non-sexual models, and for sexual models (for historical reasons) is determined by the model type passed to 
+\f3\fs18 initializeSex()
+\f4\fs20  as documented there.  The 
 \f3\fs18 symbol
 \f4\fs20  can be used to refer to the chromosome; see also 
 \f3\fs18 id

SLiMgui/SLiMHelpFunctions.rtf

@@ -939,31 +939,55 @@ If the optional
 
 \f2\fs20 \cf2 Enable sex in the simulation.  Beginning in SLiM 5, this method should generally be passed 
 \f1\fs18 NULL
-\f2\fs20 , simply indicating that sex should be enabled: individuals will be male and female (rather than hermaphroditic), biparental crosses will be required to be between a female first parent and a male second parent, and selfing will not be allowed.  There is no way to disable sex once it has been enabled; if you don\'92t want to have sex, don\'92t call this function.\
-In this new configuration style, if a sexual simulation involving sex chromosomes is desired, the new 
+\f2\fs20 , simply indicating that sex should be enabled: individuals will then be male and female (rather than hermaphroditic), biparental crosses will be required to be between a female first parent and a male second parent, and selfing will not be allowed.  In this new configuration style, if a sexual simulation involving sex chromosomes is desired, the new 
 \f1\fs18 initializeChromosome()
-\f2\fs20  call should be used to configure the chromosome setup for the simulation (see the 
+\f2\fs20  call should be used to configure the chromosome setup for the simulation.\
+For backward compatibility, the old style of configuring a sexual simulation is still supported, however.  This implicitly defines a single chromosome, without a call to 
 \f1\fs18 initializeChromosome()
-\f2\fs20  documentation in section 25.1).\
-For backward compatibility, the old style of configuring a sexual simulation is still supported, however.  In this style, the argument 
+\f2\fs20 .  With this old configuration approach, the 
 \f1\fs18 chromosomeType
-\f2\fs20  gives the type of chromosome to be simulated; this should be 
+\f2\fs20  parameter to 
+\f1\fs18 initializeSex()
+\f2\fs20  gives the type of chromosome that should be simulated; this should be 
+\f1\fs18 "A"
+\f2\fs20 , 
+\f1\fs18 "X"
+\f2\fs20 , or 
+\f1\fs18 "Y"
+\f2\fs20 , and this 
+\f1\fs18 chromosomeType
+\f2\fs20  value will be used as the symbol (
 \f1\fs18 "A"
 \f2\fs20 , 
 \f1\fs18 "X"
 \f2\fs20 , or 
 \f1\fs18 "Y"
-\f2\fs20 .  These correspond to the new chromosome types 
+\f2\fs20 ) for the implicit chromosome.  These legacy chromosome types correspond to the new chromosome types 
 \f1\fs18 "A"
 \f2\fs20 , 
 \f1\fs18 "X"
 \f2\fs20 , and 
 \f1\fs18 "-Y"
-\f2\fs20  (not 
+\f2\fs20  respectively (note that it is 
+\f3\i not
+\f2\i0  
 \f1\fs18 "Y"
-\f2\fs20 ), respectively, when using 
+\f2\fs20 ), when using 
 \f1\fs18 initializeChromosome()
-\f2\fs20 .  This old style of chromosome configuration is much less flexible, however, allowing fewer chromosome types, and only allowing a single chromosome to be set up.  This backward compatibility mode may be removed for SLiM in the future, and should be considered deprecated.\
+\f2\fs20 .  The implicit chromosome\'92s 
+\f1\fs18 id
+\f2\fs20  property is always 
+\f1\fs18 1
+\f2\fs20 .  This old style of chromosome configuration is much less flexible, however, allowing only these three chromosome types, and only allowing a single chromosome to be set up.  This backward compatibility mode may be removed for SLiM in the future, and should be considered deprecated; new models should call 
+\f1\fs18 initializeChromosome()
+\f2\fs20  explicitly instead.\
+There is no way to disable sex once it has been enabled; if you don\'92t want to have sex, don\'92t call this function.  If you require more flexibility with mating types and reproductive strategies than SLiM\'92s built-in support for sex provides, do not call 
+\f1\fs18 initializeSex()
+\f2\fs20 ; instead, track the sex or mating type of individuals yourself in script (with the 
+\f1\fs18 tag
+\f2\fs20  property of 
+\f1\fs18 Individual
+\f2\fs20 , for example), and manage the consequences of that in your script yourself, in terms of which individuals can mate with which, and exactly how the offspring is produced.\
 \pard\pardeftab397\li547\ri720\sb60\sa60\partightenfactor0
 
 \f0\b \cf2 The 
@@ -1136,7 +1160,6 @@ If
 \f1\fs18 initializeChromosome()
 \f2\fs20 , allowing a different mutation run count to be specified for each chromosome in multi-chromosome models.\expnd0\expndtw0\kerning0
 \
-\pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 \cf0 \kerning1\expnd0\expndtw0 If 
 \f1\fs18 preventIncidentalSelfing
 \f2\fs20  is 
@@ -1203,7 +1226,6 @@ If
 \f2\fs20 , the order of individuals returned will be non-random (regardless of the setting of this option); you should use 
 \f1\fs18 sample()
 \f2\fs20  to shuffle the order of the individuals vector if necessary to avoid order-dependency issues in your script.\
-\pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 \cf0 This function will likely be extended with further options in the future, added on to the end of the argument list.  Using named arguments with this call is recommended for readability.  Note that turning on optional features may increase the runtime and memory footprint of SLiM.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 

VERSIONS

@@ -110,6 +110,7 @@ development head (in the master branch):
 		recombination() callbacks can now be optionally declared with a chromosome specifier (id or symbol), to apply to just one chromosome
 			registerRecombinationCallback() now takes an optional chromosome parameter to specify that focal chromosome
 		fix up the calc...() functions for multiple chromosomes, and to be robust to the case of zero mutations (existing at all, or within the supplied haplosomes), and to improve error-checking and documentation
+		the default symbol for implicit chromosomes should be "A", "X", or "Y", so output formats don't change for legacy models
 
 
 version 4.3 (Eidos version 3.3):

core/species.cpp

@@ -317,8 +317,22 @@ void Species::MakeImplicitChromosome(ChromosomeType p_type)
 	if (num_chromosome_inits_ != 0)
 		EIDOS_TERMINATION << "ERROR (Species::MakeImplicitChromosome): (internal error) explicit chromosome already exists." << EidosTerminate();
 
+	// Only these three chromosome types are supported for an implicitly defined chromosome.  The symbols used
+	// here match the symbols that were output for chromosome types in various built-in output methods prior to
+	// SLiM 5, for backward compatibility.
+	std::string chromosome_symbol;
+	
+	if (p_type == ChromosomeType::kA_DiploidAutosome)
+		chromosome_symbol = "A";
+	else if (p_type == ChromosomeType::kX_XSexChromosome)
+		chromosome_symbol = "X";
+	else if (p_type == ChromosomeType::kNullY_YSexChromosomeWithNull)
+		chromosome_symbol = "Y";
+	else
+		EIDOS_TERMINATION << "ERROR (Species::MakeImplicitChromosome): (internal error) unsupported implicit chromosome type." << EidosTerminate();
+	
 	// Create an implicit Chromosome object with a retain on it from EidosDictionaryRetained::EidosDictionaryRetained()
-	Chromosome *chromosome = new Chromosome(*this, p_type, 1, "1", /* p_index */ 0, /* p_preferred_mutcount */ 0);
+	Chromosome *chromosome = new Chromosome(*this, p_type, 1, chromosome_symbol, /* p_index */ 0, /* p_preferred_mutcount */ 0);
 
 	// Add it to our registry; AddChromosome() takes its retain count
 	AddChromosome(chromosome);