fix #524: add [s$ sex] to initializeRecombinationRateFromFile()

Author: bhaller

QtSLiM/help/SLiMHelpFunctions.html

@@ -117,9 +117,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="p3">The <span class="s3">initializeRecombinationRateFromFile()</span> function is a useful convenience function if you wish to read the recombination rate map from a file.</p>
-<p class="p4">(void)initializeRecombinationRateFromFile(string$ path, integer$ lastPosition, [float$ scale = 1.0e-08], [string$ sep = "\t"], [string$ dec = "."])</p>
+<p class="p4">(void)initializeRecombinationRateFromFile(string$ path, integer$ lastPosition, [float$ scale = 1.0e-08], [string$ sep = "\t"], [string$ dec = "."], [string$ sex = "*"])</p>
 <p class="p3">Set a recombination rate map from data read from the file at <span class="s3">path</span>.<span class="Apple-converted-space">  </span>This function is essentially a wrapper for <span class="s3">initializeRecombinationRate()</span> that uses <span class="s3">readCSV()</span> and passes the data through.<span class="Apple-converted-space">  </span>The file is expected to contain two columns of data.<span class="Apple-converted-space">  </span>The first column must be <span class="s3">integer</span> start positions for rate map regions; the first region should start at position <span class="s3">0</span> if the map’s positions are <span class="s3">0</span>-based, or at position <span class="s3">1</span> if the map’s positions are <span class="s3">1</span>-based; in the latter case, <span class="s3">1</span> will be subtracted from every position since SLiM uses <span class="s3">0</span>-based positions.<span class="Apple-converted-space">  </span>The second column must be <span class="s3">float</span> rates, relative to the scaling factor specified in <span class="s3">scale</span>; for example, if a given rate is <span class="s3">1.2</span> and <span class="s3">scale</span> is <span class="s3">1e-8</span> (the default), the rate used will be <span class="s3">1.2e-8</span>.<span class="Apple-converted-space">  </span>No column header line should be present; the file should start immediately with numerical data.<span class="Apple-converted-space">  </span>The expected separator between columns is a tab character by default, but may be passed in <span class="s3">sep</span>; the expected decimal separator is a period by default, but may be passed in <span class="s3">dec</span>.<span class="Apple-converted-space">  </span>Once read, the map is converted into a rate map specified with end positions, rather than start positions, and the position given by <span class="s3">lastPosition</span> is used as the end of the last rate region; it should be the last position of the chromosome.</p>
-<p class="p3">See <span class="s3">readCSV()</span> for further details on <span class="s3">sep</span> and <span class="s3">dec</span>, which are passed through to it; and see <span class="s3">initializeRecombinationRate()</span> for details on how the rate map is validated and used.</p>
+<p class="p3">See <span class="s3">readCSV()</span> for further details on <span class="s3">sep</span> and <span class="s3">dec</span>, which are passed through to it; and see <span class="s3">initializeRecombinationRate()</span> for details on how the rate map is validated and used, and how the <span class="s3">sex</span> parameter is used.</p>
 <p class="p3">This function is written in Eidos, and its source code can be viewed with <span class="s3">functionSource()</span>, so you can copy and modify its code if you need to modify its functionality.</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 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>

SLiMgui/SLiMHelpFunctions.rtf

@@ -931,7 +931,8 @@ This function is written in Eidos, and its source code can be viewed with
 \f2\fs20 , in which case the ellipsis should supply a 
 \f1\fs18 string$
 \f2\fs20  Eidos script parameter.  The global symbol for the new mutation type is immediately available; the return value also provides the new object.\
-\expnd0\expndtw0\kerning0
+\pard\pardeftab543\li547\ri720\sb60\sa60\partightenfactor0
+\cf2 \expnd0\expndtw0\kerning0
 Note that by default in WF models, all mutations of a given mutation type will be converted into 
 \f1\fs18 Substitution
 \f2\fs20  objects when they reach fixation, for efficiency reasons.  If you need to disable this conversion, to keep mutations of a given type active in the simulation even after they have fixed, you can do so by setting the 
@@ -1043,7 +1044,7 @@ The
 \f2\fs20  function is a useful convenience function if you wish to read the recombination rate map from a file.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
-\f1\fs18 \cf2 (void)initializeRecombinationRateFromFile(string$\'a0path, integer$\'a0lastPosition, [float$\'a0scale\'a0=\'a01.0e-08], [string$\'a0sep\'a0=\'a0"\\t"], [string$\'a0dec\'a0=\'a0"."])\
+\f1\fs18 \cf2 (void)initializeRecombinationRateFromFile(string$\'a0path, integer$\'a0lastPosition, [float$\'a0scale\'a0=\'a01.0e-08], [string$\'a0sep\'a0=\'a0"\\t"], [string$\'a0dec\'a0=\'a0"."], [string$\'a0sex\'a0=\'a0"*"])\
 \pard\pardeftab397\li547\ri720\sb60\sa60\partightenfactor0
 
 \f2\fs20 \cf2 Set a recombination rate map from data read from the file at 
@@ -1093,7 +1094,9 @@ See
 \f1\fs18 dec
 \f2\fs20 , which are passed through to it; and see 
 \f1\fs18 initializeRecombinationRate()
-\f2\fs20  for details on how the rate map is validated and used.\
+\f2\fs20  for details on how the rate map is validated and used, and how the 
+\f1\fs18 sex
+\f2\fs20  parameter is used.\
 This function is written in Eidos, and its source code can be viewed with 
 \f1\fs18 functionSource()
 \f2\fs20 , so you can copy and modify its code if you need to modify its functionality.\
@@ -1325,6 +1328,7 @@ 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 
@@ -1391,6 +1395,7 @@ 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

@@ -8,6 +8,7 @@ Note that not every commit will be logged here; that is what the Github commit h
 development head (in the master branch):
 	add recipe 16.11, life-long monogamous mating
 	add the ability to suppress the header line of a LogFile, with a new [logical$ header = T] parameter to createLogFile() (#516), and adding [Nl$ header = NULL] for setFilePath()
+	add [string$ sex = "*"] parameter to initializeRecombinationRateFromFile(), passed through to initializeRecombinationRate(); fixing an oversight
 
 
 version 5.0 (Eidos version 4.0):

core/slim_functions.cpp

@@ -88,7 +88,7 @@ const std::vector<EidosFunctionSignature_CSP> *Community::SLiMFunctionSignatures
 		sim_func_signatures_.emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("treeSeqMetadata", SLiM_ExecuteFunction_treeSeqMetadata, kEidosValueMaskObject | kEidosValueMaskSingleton, gEidosDictionaryRetained_Class, "SLiM"))->AddString_S("filePath")->AddLogical_OS("userData", gStaticEidosValue_LogicalT));
 
 		sim_func_signatures_.emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("initializeMutationRateFromFile", gSLiMSourceCode_initializeMutationRateFromFile, kEidosValueMaskVOID, "SLiM"))->AddString_S("path")->AddInt_S("lastPosition")->AddFloat_OS("scale", EidosValue_Float_SP(new (gEidosValuePool->AllocateChunk()) EidosValue_Float(1e-8)))->AddString_OS("sep", gStaticEidosValue_StringTab)->AddString_OS("dec", gStaticEidosValue_StringPeriod));
-		sim_func_signatures_.emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("initializeRecombinationRateFromFile", gSLiMSourceCode_initializeRecombinationRateFromFile, kEidosValueMaskVOID, "SLiM"))->AddString_S("path")->AddInt_S("lastPosition")->AddFloat_OS("scale", EidosValue_Float_SP(new (gEidosValuePool->AllocateChunk()) EidosValue_Float(1e-8)))->AddString_OS("sep", gStaticEidosValue_StringTab)->AddString_OS("dec", gStaticEidosValue_StringPeriod));
+		sim_func_signatures_.emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("initializeRecombinationRateFromFile", gSLiMSourceCode_initializeRecombinationRateFromFile, kEidosValueMaskVOID, "SLiM"))->AddString_S("path")->AddInt_S("lastPosition")->AddFloat_OS("scale", EidosValue_Float_SP(new (gEidosValuePool->AllocateChunk()) EidosValue_Float(1e-8)))->AddString_OS("sep", gStaticEidosValue_StringTab)->AddString_OS("dec", gStaticEidosValue_StringPeriod)->AddString_OS("sex", gStaticEidosValue_StringAsterisk));
 
 		// Internal SLiM functions
 		sim_func_signatures_.emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("_startBenchmark", SLiM_ExecuteFunction__startBenchmark, kEidosValueMaskVOID, "SLiM"))->AddString_S(gEidosStr_type));
@@ -842,7 +842,7 @@ R"V0G0N({
 	initializeMutationRate(rates * scale, ends);
 })V0G0N";
 
-#pragma mark (void)initializeRecombinationRateFromFile(s$ path, i$ lastPosition, [f$ scale=1e-8], [s$ sep="\t"], [s$ dec="."])
+#pragma mark (void)initializeRecombinationRateFromFile(s$ path, i$ lastPosition, [f$ scale=1e-8], [s$ sep="\t"], [s$ dec="."], [string$ sex = "*"])
 const char *gSLiMSourceCode_initializeRecombinationRateFromFile = 
 R"V0G0N({
 	errbase = "ERROR (initializeRecombinationRateFromFile): ";
@@ -879,7 +879,7 @@ R"V0G0N({
 	else
 		ends = c(ends[1:(size(ends)-1)] - base - 1, lastPosition);
 	
-	initializeRecombinationRate(rates * scale, ends);
+	initializeRecombinationRate(rates * scale, ends, sex);
 })V0G0N";