fix #607, add logging of new-mutation info

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -800,6 +800,15 @@
 <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">– (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>
+<p class="p6">Next are parameters that control which mutation properties will be logged: <span class="s1">id</span> controls the <span class="s1">id</span> property; <span class="s1">mutationTypeID</span> controls the <span class="s1">id</span> property of the mutation’s mutation type (this will be the same for all mutations logged by a given <span class="s1">MutationType</span>, it can be useful if you combine datasets from more than one mutation type later); <span class="s1">chromosomeID</span> controls the <span class="s1">id</span> property of the mutation’s associated chromosome; <span class="s1">position</span> controls the <span class="s1">position</span> property; <span class="s1">nucleotideValue</span> controls the <span class="s1">nucleotideValue</span> property; <span class="s1">originTick</span> controls the <span class="s1">originTick</span> property; <span class="s1">subpopID</span> controls the <span class="s1">subpopID</span> property; and <span class="s1">tag</span> controls the <span class="s1">tag</span> property.<span class="Apple-converted-space">  </span>Data columns will be added in the order of these parameters; the <span class="s1">id</span> column will be first, if requested, for example.</p>
+<p class="p6">Last come parameters that control the logging of trait-associated data for the new mutations.<span class="Apple-converted-space">  </span>The <span class="s1">trait</span> parameter controls which traits will be logged.<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>For each specified trait, the <span class="s1">effect</span> parameter controls logging of the effect size, the <span class="s1">dominance</span> parameter controls the dominance, and the <span class="s1">hemizygousDominance</span> parameter controls the hemizygous dominance.<span class="Apple-converted-space">  </span>Data columns for this trait-associated data will be grouped by trait; for example, if two traits named <span class="s1">height</span> and <span class="s1">weight</span> are specified, and the <span class="s1">effect=T</span> and <span class="s1">dominance=T</span> flags are specified, then columns <span class="s1">heightEffect</span>, <span class="s1">heightDominance</span>, <span class="s1">weightEffect</span>, and <span class="s1">weightDominance</span> will be added, in that order.</p>
+<p class="p6">Note that logging occurs after all <span class="s1">mutation()</span> callbacks have been called, at the point when the new mutation is actually added to the simulation.<span class="Apple-converted-space">  </span>If addition of a new mutation is prevented, by a <span class="s1">mutation()</span> callback or by the current stacking policy, that mutation will not be logged.<span class="Apple-converted-space">  </span>The information logged will be the mutation’s properties at the moment that it is added; a <span class="s1">tag</span> value set by a <span class="s1">mutation()</span> callback will therefore be captured in the logged data, for example.<span class="Apple-converted-space">  </span>Changes to mutations made after that point will not be preserved in the log; the log is a snapshot of the moment of each mutation’s addition to the simulation.</p>
 <p class="p5">– (void)setDefaultDominanceForTrait(Niso&lt;Trait&gt; trait, float dominance)</p>
 <p class="p6">Set the default dominance coefficient for a specified trait or traits, for the target mutation type.<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 value of <span class="s1">dominance</span> must either be singleton (in which case it is set as the default dominance for all specified traits), or must match the number of specified traits (in which case one element of <span class="s1">defaultDominance</span> is used for each corresponding trait).</p>
 <p class="p6">As for <span class="s1">initializeMutationType()</span>, a <span class="s1">dominance</span> value of <span class="s1">NAN</span> for a given trait configures the mutation type to use “independent dominance” for that trait in new mutations of that type; see the class <span class="s1">Trait</span> documentation for discussion of independent dominance.<span class="Apple-converted-space">  </span>A mutation type may be configured to use independent dominance for some traits and not for others; a mixed configuration is allowed.</p>