a bit of cleanup for loggedData()

bhaller · bhaller · commit df9dd54f34ff · 2026-01-12T10:26:34.000-06:00
diff --git a/QtSLiM/help/SLiMHelpClasses.html b/QtSLiM/help/SLiMHelpClasses.html
@@ -800,9 +800,9 @@
 <p class="p6">Returns the parameters that configure the distribution of effects for the specified trait or traits.<span class="Apple-converted-space">  </span>The traits can be specified as <span class="s1">integer</span> indices or <span class="s1">string</span> names of traits in the species, or directly as <span class="s1">Trait</span> objects; <span class="s1">NULL</span> represents all of the traits in the species.<span class="Apple-converted-space">  </span>The distribution parameters will be of type <span class="s1">string</span> for DES type <span class="s1">"s"</span>, and type <span class="s1">float</span> for all other DES types.</p>
 <p class="p5">– (string)effectDistributionTypeForTrait([Niso&lt;Trait&gt; trait = NULL])</p>
 <p class="p6">Returns the type of distribution of effects for the specified trait or traits.<span class="Apple-converted-space">  </span>The traits can be specified as <span class="s1">integer</span> indices or <span class="s1">string</span> names of traits in the species, or directly as <span class="s1">Trait</span> objects; <span class="s1">NULL</span> represents all of the traits in the species.<span class="Apple-converted-space">  </span>The distribution type will be one of <span class="s1">"f"</span>, <span class="s1">"g"</span>, <span class="s1">"e"</span>, <span class="s1">"n"</span>, <span class="s1">"p"</span>, <span class="s1">"w"</span>, or <span class="s1">"s"</span> , as discussed in the <span class="s1">MutationType</span> class documentation.</p>
-<p class="p5">– (fo&lt;DataFrame&gt;)loggedData(string$ kind, [logical$ id = F], [logical$ mutationTypeID = F], [logical$ chromosomeID = F], [logical$ position = F], [logical$ nucleotideValue = F], [logical$ originTick = F], [logical$ subpopID = F], [logical$ tag = F], [Niso&lt;Trait&gt; trait = NULL], [logical$ effect = F], [logical$ dominance = F], [logical$ hemizygousDominance = F])</p>
-<p class="p6">Returns mutation data produced by the mutation type’s logging facility, as configured by <span class="s1">logMutationData()</span>.<span class="Apple-converted-space">  </span>The data returned can be in the form of means across all logged mutations (for <span class="s1">kind="mean"</span>), standard deviations across all logged mutations (for <span class="s1">kind="sd"</span>), or separate values for each mutation (for <span class="s1">kind="values"</span>).<span class="Apple-converted-space">  </span>If logging only of means was enabled (with the <span class="s1">meanOnly=T</span> option to <span class="s1">logMutationData()</span>), only <span class="s1">kind="mean"</span> is allowed, since separate values for each mutation are then not logged.</p>
-<p class="p6">The remaining flags control which columns of data should be returned; see <span class="s1">logMutationData()</span> for a summary of the mutation properties they refer to.<span class="Apple-converted-space">  </span>If only one data column is specified by the flags, a vector of values (or a mean or standard deviation) will be returned for that one specified data column.<span class="Apple-converted-space">  </span>If more than one flag is set to <span class="s1">T</span>, a <span class="s1">DataFrame</span> object will be returned with named columns of values (or means, or standard deviations) for each specified data column.<span class="Apple-converted-space">  </span>The <span class="s1">trait</span> property specifies which traits values should be returned for, with respect to the <span class="s1">effect</span>, <span class="s1">dominance</span>, and <span class="s1">hemizygousDominance</span> flags; see <span class="s1">logMutationData()</span> for further description.<span class="Apple-converted-space">  </span>If <i>all</i> of these flags are <span class="s1">F</span> (the default), that is taken to mean that <i>all</i> logged data should be returned; in that case, a vector will be returned if only one column of data was logged, otherwise a <span class="s1">DataFrame</span> object will be returned, the same as when flags are specified explicitly.<span class="Apple-converted-space">  </span>Flags set to <span class="s1">T</span> for data columns that were not actually logged will simply be ignored; similarly, traits specified by <span class="s1">trait</span> that were not actually logged will simply be ignored.<span class="Apple-converted-space">  </span>See the Eidos manual for the <span class="s1">DataFrame</span> class documentation.</p>
+<p class="p5">– (ifo&lt;DataFrame&gt;)loggedData(string$ kind, [logical$ id = F], [logical$ mutationTypeID = F], [logical$ chromosomeID = F], [logical$ position = F], [logical$ nucleotideValue = F], [logical$ originTick = F], [logical$ subpopID = F], [logical$ tag = F], [Niso&lt;Trait&gt; trait = NULL], [logical$ effect = F], [logical$ dominance = F], [logical$ hemizygousDominance = F])</p>
+<p class="p6">Returns mutation data produced by the mutation type’s logging facility, as configured by <span class="s1">logMutationData()</span>.<span class="Apple-converted-space">  </span>The data returned can be in the form of means across all logged mutations (for <span class="s1">kind="mean"</span>), standard deviations across all logged mutations (for <span class="s1">kind="sd"</span>), or separate values for each mutation (for <span class="s1">kind="values"</span>); <span class="s1">kind="count"</span> is also allowed, and simply returns a singleton <span class="s1">integer</span> providing the number of entries (i.e., the number of mutations) that have been recorded.<span class="Apple-converted-space">  </span>If logging only of means was enabled (with the <span class="s1">meanOnly=T</span> option to <span class="s1">logMutationData()</span>), only <span class="s1">kind="mean"</span> and <span class="s1">kind="count"</span> are allowed, since separate values for each mutation are then not logged.</p>
+<p class="p6">The remaining flags control which columns of data should be returned (for <span class="s1">kind</span> options other than <span class="s1">"count"</span>); see <span class="s1">logMutationData()</span> for a summary of the mutation properties they refer to.<span class="Apple-converted-space">  </span>If only one data column is specified by the flags, a vector of values (or a mean or standard deviation) will be returned for that one specified data column.<span class="Apple-converted-space">  </span>If more than one flag is set to <span class="s1">T</span>, a <span class="s1">DataFrame</span> object will be returned with named columns of values (or means, or standard deviations) for each specified data column.<span class="Apple-converted-space">  </span>The <span class="s1">trait</span> property specifies which traits values should be returned for, with respect to the <span class="s1">effect</span>, <span class="s1">dominance</span>, and <span class="s1">hemizygousDominance</span> flags; see <span class="s1">logMutationData()</span> for further description.<span class="Apple-converted-space">  </span>Flags set to <span class="s1">T</span> for data columns that were not actually logged will simply be ignored; similarly, traits specified by <span class="s1">trait</span> that were not actually logged will simply be ignored.<span class="Apple-converted-space">  </span>See the Eidos manual for the <span class="s1">DataFrame</span> class documentation.</p>
 <p class="p5">– (void)logMutationData(logical$ enable, [logical$ autogeneratedOnly = T], [logical$ meanOnly = F], [logical$ id = F], [logical$ mutationTypeID = F], [logical$ chromosomeID = F], [logical$ position = F], [logical$ nucleotideValue = F], [logical$ originTick = F], [logical$ subpopID = F], [logical$ tag = F], [Niso&lt;Trait&gt; trait = NULL], [logical$ effect = F], [logical$ dominance = F], [logical$ hemizygousDominance = F])</p>
 <p class="p6">Starts or ends logging of data about new mutations belonging to the target mutation type.<span class="Apple-converted-space">  </span>If <span class="s1">autogeneratedOnly</span> is <span class="s1">T</span> (the default), only new mutations generated automatically by SLiM will be logged (including mutations that are substituted in for an auto-generated mutation using a <span class="s1">mutation()</span> callback; that is still considered part of the auto-generation process).<span class="Apple-converted-space">  </span>If <span class="s1">autogeneratedOnly</span> is <span class="s1">F</span>, mutations generated in script, such as with <span class="s1">addNewMutation()</span>, <span class="s1">addNewDrawnMutation()</span>, and reading from files such as VCF, MS, or <span class="s1">.trees</span>, will also be logged.<span class="Apple-converted-space">  </span>The logged information can be obtained later with the <span class="s1">loggedData()</span> method.<span class="Apple-converted-space">  </span>Once logging has been started with <span class="s1">enable=T</span> it cannot be modified, only stopped with <span class="s1">enable=F</span>; and if logging is subsequently resumed with <span class="s1">enable=T</span>, any previously logged data will be discarded.<span class="Apple-converted-space">  </span>(This can be useful if you wish to limit the size of the in-memory data while continuing to log new data: periodically write the accumulated data to a file and then disable and re-enable logging to discard the old data.)</p>
 <p class="p6">If <span class="s1">meanOnly</span> is <span class="s1">F</span> (the default), values for each new mutation will be kept separately.<span class="Apple-converted-space">  </span>Beware: the memory usage entailed by this option can be extremely large!<span class="Apple-converted-space">  </span>Alternatively, if <span class="s1">meanOnly</span> is <span class="s1">T</span>, only a running sum, used to compute a mean, will be kept for each type of data; the memory usage for this option will be small and constant, but of course a mean is more useful for some columns of data than others.<span class="Apple-converted-space">  </span>If per-mutation data is desired for any one column, use <span class="s1">meanOnly=F</span>; this option cannot be controlled independently for the various columns of data being logged.</p>
diff --git a/SLiMgui/SLiMHelpClasses.rtf b/SLiMgui/SLiMHelpClasses.rtf
@@ -7015,7 +7015,7 @@ Also note that dominance coefficients have a quirk: they are stored internally i
 \f4\fs20  class documentation.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
-\f3\fs18 \cf2 \'96\'a0(fo<DataFrame>)loggedData(string$\'a0kind, [logical$\'a0id\'a0=\'a0F], [logical$\'a0mutationTypeID\'a0=\'a0F], [logical$\'a0chromosomeID\'a0=\'a0F], [logical$\'a0position\'a0=\'a0F], [logical$\'a0nucleotideValue\'a0=\'a0F], [logical$\'a0originTick\'a0=\'a0F], [logical$\'a0subpopID\'a0=\'a0F], [logical$\'a0tag\'a0=\'a0F], [Niso<Trait>\'a0trait\'a0=\'a0NULL], [logical$\'a0effect\'a0=\'a0F], [logical$\'a0dominance\'a0=\'a0F], [logical$\'a0hemizygousDominance\'a0=\'a0F])\
+\f3\fs18 \cf2 \'96\'a0(ifo<DataFrame>)loggedData(string$\'a0kind, [logical$\'a0id\'a0=\'a0F], [logical$\'a0mutationTypeID\'a0=\'a0F], [logical$\'a0chromosomeID\'a0=\'a0F], [logical$\'a0position\'a0=\'a0F], [logical$\'a0nucleotideValue\'a0=\'a0F], [logical$\'a0originTick\'a0=\'a0F], [logical$\'a0subpopID\'a0=\'a0F], [logical$\'a0tag\'a0=\'a0F], [Niso<Trait>\'a0trait\'a0=\'a0NULL], [logical$\'a0effect\'a0=\'a0F], [logical$\'a0dominance\'a0=\'a0F], [logical$\'a0hemizygousDominance\'a0=\'a0F])\
 \pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 
 \f4\fs20 \cf2 Returns mutation data produced by the mutation type\'92s logging facility, as configured by 
@@ -7026,14 +7026,25 @@ Also note that dominance coefficients have a quirk: they are stored internally i
 \f3\fs18 kind="sd"
 \f4\fs20 ), or separate values for each mutation (for 
 \f3\fs18 kind="values"
-\f4\fs20 ).  If logging only of means was enabled (with the 
+\f4\fs20 ); 
+\f3\fs18 kind="count"
+\f4\fs20  is also allowed, and simply returns a singleton 
+\f3\fs18 integer
+\f4\fs20  providing the number of entries (i.e., the number of mutations) that have been recorded.  If logging only of means was enabled (with the 
 \f3\fs18 meanOnly=T
 \f4\fs20  option to 
 \f3\fs18 logMutationData()
 \f4\fs20 ), only 
 \f3\fs18 kind="mean"
-\f4\fs20  is allowed, since separate values for each mutation are then not logged.\
-The remaining flags control which columns of data should be returned; see 
+\f4\fs20  and 
+\f3\fs18 kind="count"
+\f4\fs20  are allowed, since separate values for each mutation are then not logged.\
+\pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
+\cf2 The remaining flags control which columns of data should be returned (for 
+\f3\fs18 kind
+\f4\fs20  options other than 
+\f3\fs18 "count"
+\f4\fs20 ); see 
 \f3\fs18 logMutationData()
 \f4\fs20  for a summary of the mutation properties they refer to.  If only one data column is specified by the flags, a vector of values (or a mean or standard deviation) will be returned for that one specified data column.  If more than one flag is set to 
 \f3\fs18 T
@@ -7049,15 +7060,7 @@ The remaining flags control which columns of data should be returned; see
 \f3\fs18 hemizygousDominance
 \f4\fs20  flags; see 
 \f3\fs18 logMutationData()
-\f4\fs20  for further description.  If 
-\f1\i all
-\f4\i0  of these flags are 
-\f3\fs18 F
-\f4\fs20  (the default), that is taken to mean that 
-\f1\i all
-\f4\i0  logged data should be returned; in that case, a vector will be returned if only one column of data was logged, otherwise a 
-\f3\fs18 DataFrame
-\f4\fs20  object will be returned, the same as when flags are specified explicitly.  Flags set to 
+\f4\fs20  for further description.  Flags set to 
 \f3\fs18 T
 \f4\fs20  for data columns that were not actually logged will simply be ignored; similarly, traits specified by 
 \f3\fs18 trait
@@ -7094,8 +7097,7 @@ The remaining flags control which columns of data should be returned; see
 \f4\fs20 ; and if logging is subsequently resumed with 
 \f3\fs18 enable=T
 \f4\fs20 , any previously logged data will be discarded.  (This can be useful if you wish to limit the size of the in-memory data while continuing to log new data: periodically write the accumulated data to a file and then disable and re-enable logging to discard the old data.)\
-\pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
-\cf2 If 
+If 
 \f3\fs18 meanOnly
 \f4\fs20  is 
 \f3\fs18 F
diff --git a/VERSIONS b/VERSIONS
@@ -138,7 +138,7 @@ multitrait branch:
 	add a Species demandPhenotype() method, and change the Individual method demandPhenotype() to demandPhenotypeForIndividuals(); the Species method is generally preferred for speed
 	add data logging capabilities to MutationType for easier assessment of requested vs. realized DFEs, etc.
 		- (void)logMutationData(logical$ enable, [logical$ autogeneratedOnly = T], [logical$ meanOnly = F], <flags>)
-		- (fo<DataFrame>)loggedData(string$ kind, <flags>)
+		- (ifo<DataFrame>)loggedData(string$ kind, <flags>)
 	policy change: mean(integer(0)) or mean(float(0)) now returns NAN rather than NULL, to match R; I just noticed this, and NAN does seem better
 
 
diff --git a/core/mutation_type.cpp b/core/mutation_type.cpp
@@ -1053,7 +1053,8 @@ EidosValue_SP MutationType::ExecuteMethod_loggedData(EidosGlobalStringID p_metho
 	
 	// kind
 	typedef enum class _KindEnum {
-		kMean = 1,
+		kCount = 0,
+		kMean,
 		kSD,
 		kValues
 	} KindEnum;
@@ -1062,15 +1063,22 @@ EidosValue_SP MutationType::ExecuteMethod_loggedData(EidosGlobalStringID p_metho
 	const std::string &kind_str = kind_value_string->StringRefAtIndex_NOCAST(0, nullptr);
 	KindEnum kind;
 	
-	if		(kind_str == "mean")	kind = KindEnum::kMean;
+	if		(kind_str == "count")	kind = KindEnum::kCount;
+	else if	(kind_str == "mean")	kind = KindEnum::kMean;
 	else if	(kind_str == "sd")		kind = KindEnum::kSD;
 	else if	(kind_str == "values")	kind = KindEnum::kValues;
 	else
-		EIDOS_TERMINATION << "ERROR (MutationType::ExecuteMethod_loggedData): loggedData() requires that kind be 'mean', 'sd', or 'values'." << EidosTerminate(nullptr);
+		EIDOS_TERMINATION << "ERROR (MutationType::ExecuteMethod_loggedData): loggedData() requires that kind be 'count', 'mean', 'sd', or 'values'." << EidosTerminate(nullptr);
 	
 	if (log_meanOnly_ && (kind != KindEnum::kMean))
 		EIDOS_TERMINATION << "ERROR (MutationType::ExecuteMethod_loggedData): loggedData() can only return means (kind='mean'), since meanOnly=T was set in logMutationData()." << EidosTerminate(nullptr);
 	
+	if (kind == KindEnum::kCount)
+	{
+		// for "count" the remaining flags are ignored; we just return the singleton count of mutations recorded
+		return EidosValue_SP(new EidosValue_Int((int64_t)log_size_));
+	}
+	
 	// trait
 	std::vector<slim_trait_index_t> trait_indices;
 	species_.GetTraitIndicesFromEidosValue(trait_indices, trait_value, "loggedData");
@@ -1138,6 +1146,9 @@ EidosValue_SP MutationType::ExecuteMethod_loggedData(EidosGlobalStringID p_metho
 		(int)get_nucleotideValue + (int)get_originTick + (int)get_subpopID + (int)get_tag +
 		((int)get_effect) * trait_count + ((int)get_dominance) * trait_count + ((int)get_hemizygousDominance) * trait_count;
 	
+	if (requested_count == 0)
+		return gStaticEidosValueNULL;
+	
 	EidosDataFrame *dataframe = nullptr;
 	EidosValue_SP result_SP;
 	
@@ -1613,7 +1624,7 @@ const std::vector<EidosMethodSignature_CSP> *MutationType_Class::Methods(void) c
 		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_effectDistributionTypeForTrait, kEidosValueMaskString))->AddIntStringObject_ON("trait", gSLiM_Trait_Class, gStaticEidosValueNULL));
 		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_drawEffectForTrait, kEidosValueMaskFloat))->AddIntStringObject_ON("trait", gSLiM_Trait_Class, gStaticEidosValueNULL)->AddInt_OS("n", gStaticEidosValue_Integer1));
 		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_setDefaultDominanceForTrait, kEidosValueMaskVOID))->AddIntStringObject_N("trait", gSLiM_Trait_Class)->AddFloat("dominance"));
-		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_loggedData, kEidosValueMaskFloat | kEidosValueMaskObject, gEidosDataFrame_Class))
+		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_loggedData, kEidosValueMaskInt | kEidosValueMaskFloat | kEidosValueMaskObject, gEidosDataFrame_Class))
 							  ->AddString_S("kind")
 							  ->AddLogical_OS("id", gStaticEidosValue_LogicalF)
 							  ->AddLogical_OS("mutationTypeID", gStaticEidosValue_LogicalF)
diff --git a/core/slim_test_genetics.cpp b/core/slim_test_genetics.cpp
@@ -146,6 +146,30 @@ void _RunMutationTypeTests(void)
 	SLiMAssertScriptStop(gen1_setup + "1 early() { m1.setEffectDistributionForTrait(NULL, 'w', 3.1, 7.5); if (abs(mean(m1.drawEffectForTrait(NULL, 2000)) - 2.910106) < 0.1) stop(); }", __LINE__);
 	SLiMAssertScriptSuccess(gen1_setup + "1 early() { m1.setEffectDistributionForTrait(NULL, 's', 'rbinom(1, 4, 0.5);'); m1.drawEffectForTrait(); }", __LINE__);
 	SLiMAssertScriptStop(gen1_setup + "1 early() { m1.setEffectDistributionForTrait(NULL, 's', 'rbinom(1, 4, 0.5);'); if (abs(mean(m1.drawEffectForTrait(NULL, 5000)) - 2.0) < 0.1) stop(); }", __LINE__);
+	
+	// test mutation date recording with logMutationData() and loggedData()
+	std::string data_recording =
+	R"V0G0N(
+		initialize() {
+			initializeMutationRate(1e-7);
+			initializeMutationType("m1", 0.5, "f", 0.0);
+			m1.logMutationData(T, chromosomeID=T, position=T);
+			initializeGenomicElementType("g1", m1, 1.0);
+			initializeGenomicElement(g1, 0, 999999);
+			initializeRecombinationRate(1e-8);
+		}
+		1 early() { sim.addSubpop("p1", 50); }
+		100 late() {
+			count = m1.loggedData(kind="count");
+			pos = m1.loggedData(kind="values", position=T);
+			df = m1.loggedData(kind="values", chromosomeID=T, position=T);
+			
+			if ((count == 0) | (count != length(pos)) | (count != df.nrow))
+				stop("MutationType data recording problem");
+		}
+	)V0G0N";
+	
+	SLiMAssertScriptSuccess(data_recording);
 }
 
 #pragma mark GenomicElementType tests
