From 2ef60101216941ea56cd0ae0ce077dc5744fee82 Mon Sep 17 00:00:00 2001 From: Ben Haller Date: Mon, 4 Dec 2023 22:44:45 -0500 Subject: [PATCH] a little final cleanup for 4.1 --- QtSLiM/help/SLiMHelpClasses.html | 8 ++++---- SLiMgui/SLiMHelpClasses.rtf | 8 ++++---- core/subpopulation.cpp | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/QtSLiM/help/SLiMHelpClasses.html b/QtSLiM/help/SLiMHelpClasses.html index f44dcd5a..2eda9fbc 100644 --- a/QtSLiM/help/SLiMHelpClasses.html +++ b/QtSLiM/help/SLiMHelpClasses.html @@ -955,7 +955,7 @@

Generates a new offspring individual from the given parent by clonal reproduction, queues it for addition to the target subpopulation, and returns it.  The new offspring will not be visible as a member of the target subpopulation until the end of the offspring generation tick cycle stage.  The subpopulation of parent will be used to locate applicable mutation() and modifyChild() callbacks governing the generation of the offspring individual.

Beginning in SLiM 4.1, the count parameter dictates how many offspring will be generated (previously, exactly one offspring was generated).  Each offspring is generated independently, based upon the given parameters.  The returned vector contains all generated offspring, except those that were rejected by a modifyChild() callback.  If all offspring are rejected, object<Individual>(0) is returned, which is a zero-length object vector of class Individual; note that this is a change in behavior from earlier versions, which would return NULL.

Beginning in SLiM 4.1, passing T for defer will defer the generation of the genomes of the produced offspring until the end of the reproduction phase.  Genome generation can only be deferred if there are no active mutation() callbacks; otherwise, an error will result.  Furthermore, when genome generation is deferred the mutations of the genomes of the generated offspring may not be accessed until reproduction is complete (whether from a modifyChild() callback or otherwise).  There is little or no advantage to deferring genome generation when running single-threaded; in that case, the default of F for defer is generally preferable since it has fewer restrictions.  When running multi-threaded, deferring genome generation allows that task to be done in parallel (which is the reason this option exists).

-

Also beginning in SLiM 4.1, in spatial models the spatial position of the offspring will be inherited (i.e., copied) from parent; more specifically, the x property will be inherited in all spatial models (1D/2D/3D), the y property in 2D/3D models, and the z property in 3D models.  Properties not inherited will be left uninitialized, as they were prior to SLiM 5.  The parent’s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to pointDeviated().

+

Also beginning in SLiM 4.1, in spatial models the spatial position of the offspring will be inherited (i.e., copied) from parent; more specifically, the x property will be inherited in all spatial models (1D/2D/3D), the y property in 2D/3D models, and the z property in 3D models.  Properties not inherited will be left uninitialized, as they were prior to SLiM 4.1.  The parent’s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to pointDeviated().

Note that this method is only for use in nonWF models.  See addCrossed() for further general notes on the addition of new offspring individuals.

– (object<Individual>)addCrossed(object<Individual>$ parent1, object<Individual>$ parent2, [Nfs$ sex = NULL], [integer$ count = 1], [logical$ defer = F])

Generates a new offspring individual from the given parents by biparental sexual reproduction, queues it for addition to the target subpopulation, and returns it.  The new offspring will not be visible as a member of the target subpopulation until the end of the offspring generation tick cycle stage.  Attempting to use a newly generated offspring individual as a mate, or to reference it as a member of the target subpopulation in any other way, will result in an error.  In most models the returned individual is not used, but it is provided for maximal generality and flexibility.

@@ -965,7 +965,7 @@

If the modifyChild() callback process results in rejection of the proposed child (see section 26.5), a new offspring individual is not be generated.  To force the generation of an offspring individual from a given pair of parents, you could loop until addCrossed() succeeds, but note that if your modifyChild() callback rejects all proposed children from those particular parents, your model will then hang, so care must be taken with this approach.  Usually, nonWF models do not force generation of offspring in this manner; rejection of a proposed offspring by a modifyChild() callback typically represents a phenomenon such as post-mating reproductive isolation or lethal genetic incompatibilities that would reduce the expected litter size, so the default behavior is typically desirable.

Beginning in SLiM 4.1, the count parameter dictates how many offspring will be generated (previously, exactly one offspring was generated).  Each offspring is generated independently, based upon the given parameters.  The returned vector contains all generated offspring, except those that were rejected by a modifyChild() callback.  If all offspring are rejected, object<Individual>(0) is returned, which is a zero-length object vector of class Individual; note that this is a change in behavior from earlier versions, which would return NULL.

Beginning in SLiM 4.1, passing T for defer will defer the generation of the genomes of the produced offspring until the end of the reproduction phase.  Genome generation can only be deferred if there are no active mutation() or recombination() callbacks; otherwise, an error will result.  Furthermore, when genome generation is deferred the mutations of the genomes of the generated offspring may not be accessed until reproduction is complete (whether from a modifyChild() callback or otherwise).  There is little or no advantage to deferring genome generation when running single-threaded; in that case, the default of F for defer is generally preferable since it has fewer restrictions.  When running multi-threaded, deferring genome generation allows that task to be done in parallel (which is the reason this option exists).

-

Also beginning in SLiM 4.1, in spatial models the spatial position of the offspring will be inherited (i.e., copied) from parent1; more specifically, the x property will be inherited in all spatial models (1D/2D/3D), the y property in 2D/3D models, and the z property in 3D models.  Properties not inherited will be left uninitialized, as they were prior to SLiM 5.  The parent’s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to pointDeviated().

+

Also beginning in SLiM 4.1, in spatial models the spatial position of the offspring will be inherited (i.e., copied) from parent1; more specifically, the x property will be inherited in all spatial models (1D/2D/3D), the y property in 2D/3D models, and the z property in 3D models.  Properties not inherited will be left uninitialized, as they were prior to SLiM 4.1.  The parent’s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to pointDeviated().

Note that this method is only for use in nonWF models, in which offspring generation is managed manually by the model script; in such models, addCrossed() must be called only from reproduction() callbacks, and may not be called at any other time.  In WF models, offspring generation is managed automatically by the SLiM core.

– (object<Individual>)addEmpty([Nfs$ sex = NULL], [Nl$ genome1Null = NULL], [Nl$ genome2Null = NULL], [integer$ count = 1])

Generates a new offspring individual with empty genomes (i.e., containing no mutations), queues it for addition to the target subpopulation, and returns it.  The new offspring will not be visible as a member of the target subpopulation until the end of the offspring generation tick cycle stage.  No recombination() or mutation() callbacks will be called.  The target subpopulation will be used to locate applicable modifyChild() callbacks governing the generation of the offspring individual (unlike the other addX() methods, because there is no parental individual to reference).  The offspring is considered to have no parents for the purposes of pedigree tracking.  The sex parameter is treated as in addCrossed().

@@ -983,14 +983,14 @@

Note that gene conversion tracts are not explicitly supported by this method; the breaks vectors provide crossover breakpoints, which may be used to implement crossovers or simple gene conversion tracts.  There is no way to specify complex gene conversion tracts with heteroduplex mismatch repair.

Beginning in SLiM 4.1, the count parameter dictates how many offspring will be generated (previously, exactly one offspring was generated).  Each offspring is generated independently, based upon the given parameters.  The returned vector contains all generated offspring, except those that were rejected by a modifyChild() callback.  If all offspring are rejected, object<Individual>(0) is returned, which is a zero-length object vector of class Individual; note that this is a change in behavior from earlier versions, which would return NULL.

Beginning in SLiM 4.1, passing T for defer will defer the generation of the genomes of the produced offspring until the end of the reproduction phase.  Genome generation can only be deferred if there are no active mutation() callbacks; otherwise, an error will result.  Furthermore, when genome generation is deferred the mutations of the genomes of the generated offspring may not be accessed until reproduction is complete (whether from a modifyChild() callback or otherwise).  There is little or no advantage to deferring genome generation when running single-threaded; in that case, the default of F for defer is generally preferable since it has fewer restrictions.  When running multi-threaded, deferring genome generation allows that task to be done in parallel (which is the reason this option exists).

-

Also beginning in SLiM 4.1, in spatial models the spatial position of the offspring will be inherited (i.e., copied) from parent1; more specifically, the x property will be inherited in all spatial models (1D/2D/3D), the y property in 2D/3D models, and the z property in 3D models.  Properties not inherited will be left uninitialized, as they were prior to SLiM 5.  The parent’s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to pointDeviated().  If parent1 is NULL (the default), parent2 will be used; if it is also NULL, no spatial position will be inherited.

+

Also beginning in SLiM 4.1, in spatial models the spatial position of the offspring will be inherited (i.e., copied) from parent1; more specifically, the x property will be inherited in all spatial models (1D/2D/3D), the y property in 2D/3D models, and the z property in 3D models.  Properties not inherited will be left uninitialized, as they were prior to SLiM 4.1.  The parent’s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to pointDeviated().  If parent1 is NULL (the default), parent2 will be used; if it is also NULL, no spatial position will be inherited.

Note that this method is only for use in nonWF models.  See addCrossed() for further general notes on the addition of new offspring individuals.

– (object<Individual>)addSelfed(object<Individual>$ parent, [integer$ count = 1], [logical$ defer = F])

Generates a new offspring individual from the given parent by selfing, queues it for addition to the target subpopulation, and returns it.  The new offspring will not be visible as a member of the target subpopulation until the end of the offspring generation tick cycle stage.  The subpopulation of parent will be used to locate applicable mutation(), recombination(), and modifyChild() callbacks governing the generation of the offspring individual.

Since selfing requires that parent act as a source of both a male and a female gamete, this method may be called only in hermaphroditic models; calling it in sexual models will result in an error.  This method represents a non-incidental selfing event, so the preventIncidentalSelfing flag of initializeSLiMOptions() has no effect on this method (in contrast to the behavior of addCrossed(), where selfing is assumed to be incidental).

Beginning in SLiM 4.1, the count parameter dictates how many offspring will be generated (previously, exactly one offspring was generated).  Each offspring is generated independently, based upon the given parameters.  The returned vector contains all generated offspring, except those that were rejected by a modifyChild() callback.  If all offspring are rejected, object<Individual>(0) is returned, which is a zero-length object vector of class Individual; note that this is a change in behavior from earlier versions, which would return NULL.

Beginning in SLiM 4.1, passing T for defer will defer the generation of the genomes of the produced offspring until the end of the reproduction phase.  Genome generation can only be deferred if there are no active mutation() or recombination() callbacks; otherwise, an error will result.  Furthermore, when genome generation is deferred the mutations of the genomes of the generated offspring may not be accessed until reproduction is complete (whether from a modifyChild() callback or otherwise).  There is little or no advantage to deferring genome generation when running single-threaded; in that case, the default of F for defer is generally preferable since it has fewer restrictions.  When running multi-threaded, deferring genome generation allows that task to be done in parallel (which is the reason this option exists).

-

Also beginning in SLiM 4.1, in spatial models the spatial position of the offspring will be inherited (i.e., copied) from parent; more specifically, the x property will be inherited in all spatial models (1D/2D/3D), the y property in 2D/3D models, and the z property in 3D models.  Properties not inherited will be left uninitialized, as they were prior to SLiM 5.  The parent’s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to pointDeviated().

+

Also beginning in SLiM 4.1, in spatial models the spatial position of the offspring will be inherited (i.e., copied) from parent; more specifically, the x property will be inherited in all spatial models (1D/2D/3D), the y property in 2D/3D models, and the z property in 3D models.  Properties not inherited will be left uninitialized, as they were prior to SLiM 4.1.  The parent’s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to pointDeviated().

Note that this method is only for use in nonWF models.  See addCrossed() for further general notes on the addition of new offspring individuals.

– (void)addSpatialMap(object<SpatialMap>$ map)

Adds the given SpatialMap object, map, to the subpopulation.  (The spatial map would have been previously created with a call to defineSpatialMap() on a different subpopulation; addSpatialMap() can then be used to add that existing spatial map with other subpopulations, sharing the map between subpopulations.)  If the map is already added to the target subpopulation, this method does nothing; if a different map with the same name is already added to the subpopulation, an error results (because map names must be unique within each subpopulation).  The map being added must be compatible with the target subpopulation; in particular, the spatial bounds utilized by the map must exactly match the corresponding spatial bounds for the subpopulation, and the dimensionality of the subpopulation must encompass the spatiality of the map.  For example, if the map has a spatiality of "xz" then the subpopulation must have a dimensionality of "xyz" so that it encompasses both "x" and "z", and the subpopulation’s spatial bounds for "x" and "z" must match those for the map (but the spatial bounds for "y" are unimportant, since the map does not use that dimension).

diff --git a/SLiMgui/SLiMHelpClasses.rtf b/SLiMgui/SLiMHelpClasses.rtf index 1d8ef655..5031e384 100644 --- a/SLiMgui/SLiMHelpClasses.rtf +++ b/SLiMgui/SLiMHelpClasses.rtf @@ -8450,7 +8450,7 @@ Also beginning in SLiM 4.1, in spatial models the spatial position of the offspr \f3\fs18 y \f4\fs20 property in 2D/3D models, and the \f3\fs18 z -\f4\fs20 property in 3D models. Properties not inherited will be left uninitialized, as they were prior to SLiM 5. The parent\'92s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to +\f4\fs20 property in 3D models. Properties not inherited will be left uninitialized, as they were prior to SLiM 4.1. The parent\'92s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to \f3\fs18 pointDeviated() \f4\fs20 .\ Note that this method is only for use in nonWF models. See @@ -8589,7 +8589,7 @@ Also beginning in SLiM 4.1, in spatial models the spatial position of the offspr \f3\fs18 y \f4\fs20 property in 2D/3D models, and the \f3\fs18 z -\f4\fs20 property in 3D models. Properties not inherited will be left uninitialized, as they were prior to SLiM 5. The parent\'92s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to +\f4\fs20 property in 3D models. Properties not inherited will be left uninitialized, as they were prior to SLiM 4.1. The parent\'92s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to \f3\fs18 pointDeviated() \f4\fs20 .\ Note that this method is only for use in nonWF models, in which offspring generation is managed manually by the model script; in such models, @@ -8926,7 +8926,7 @@ Also beginning in SLiM 4.1, in spatial models the spatial position of the offspr \f3\fs18 y \f4\fs20 property in 2D/3D models, and the \f3\fs18 z -\f4\fs20 property in 3D models. Properties not inherited will be left uninitialized, as they were prior to SLiM 5. The parent\'92s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to +\f4\fs20 property in 3D models. Properties not inherited will be left uninitialized, as they were prior to SLiM 4.1. The parent\'92s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to \f3\fs18 pointDeviated() \f4\fs20 . If \f3\fs18 parent1 @@ -9001,7 +9001,7 @@ Also beginning in SLiM 4.1, in spatial models the spatial position of the offspr \f3\fs18 y \f4\fs20 property in 2D/3D models, and the \f3\fs18 z -\f4\fs20 property in 3D models. Properties not inherited will be left uninitialized, as they were prior to SLiM 5. The parent\'92s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to +\f4\fs20 property in 3D models. Properties not inherited will be left uninitialized, as they were prior to SLiM 4.1. The parent\'92s spatial position is probably not desirable in itself; the intention here is to make it easy to model the natal dispersal of all the new offspring for a given tick with a single vectorized call to \f3\fs18 pointDeviated() \f4\fs20 .\ Note that this method is only for use in nonWF models. See diff --git a/core/subpopulation.cpp b/core/subpopulation.cpp index 7014d6f6..72ccbe5d 100644 --- a/core/subpopulation.cpp +++ b/core/subpopulation.cpp @@ -7905,7 +7905,7 @@ EidosValue_SP Subpopulation::ExecuteMethod_spatialMapValue(EidosGlobalStringID p // We want to un-clog the Subpopulation API, so specialized functionality of SpatialMap should not be mirrored // there. However, spatialMapValue() is the core functionality, and it is a nice convenience to be able to // do it through Subpopulation without having to keep track of the SpatialMap object, just as was done before - // SLiM 5. In addition, using this API has some code safety benefits: the Subpopulation will check itself for + // SLiM 4.1. In addition, using this API has some code safety benefits: the Subpopulation will check itself for // compatibility with the spatial map, and SLiMgui will display the spatial map correctly (which would not // be the case if it had not been added to the target subpopulation at all). Nevertheless, the new SpatialMap // method -mapValue() is also available, and can be used instead of this. This redundancy seems worthwhile.