extend mutationEffect() callbacks with multi-trait frills

Author: bhaller

QtSLiM/QtSLiMScriptTextEdit.cpp

@@ -979,7 +979,7 @@ void QtSLiMTextEdit::updateStatusFieldFromSelection(void)
             else if (callName == "mutationEffect")
             {
                 static EidosCallSignature_CSP callbackSig = nullptr;
-                if (!callbackSig) callbackSig = EidosCallSignature_CSP((new EidosFunctionSignature("mutationEffect", nullptr, kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddObject_S("mutationType", gSLiM_MutationType_Class)->AddObject_OS("subpop", gSLiM_Subpopulation_Class, gStaticEidosValueNULLInvisible));
+                if (!callbackSig) callbackSig = EidosCallSignature_CSP((new EidosFunctionSignature("mutationEffect", nullptr, kEidosValueMaskNULL | kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddObject_S("mutationType", gSLiM_MutationType_Class)->AddObject_OS("subpop", gSLiM_Subpopulation_Class, gStaticEidosValueNULLInvisible)->AddString_OS("trait", gStaticEidosValueNULLInvisible));
                 signature = callbackSig;
             }
             else if (callName == "fitnessEffect")
@@ -2129,6 +2129,7 @@ void QtSLiMTextEdit::slimSpecificCompletion(QString completionScriptString, NSRa
                         case SLiMEidosBlockType::SLiMEidosMutationEffectCallback:
                             (*typeTable)->SetTypeForSymbol(gID_mut,				EidosTypeSpecifier{kEidosValueMaskObject, gSLiM_Mutation_Class});
                             (*typeTable)->SetTypeForSymbol(gID_homozygous,		EidosTypeSpecifier{kEidosValueMaskLogical, nullptr});
+                            (*typeTable)->SetTypeForSymbol(gID_trait,			EidosTypeSpecifier{kEidosValueMaskObject, gSLiM_Trait_Class});
                             (*typeTable)->SetTypeForSymbol(gID_effect,			EidosTypeSpecifier{kEidosValueMaskFloat, nullptr});
                             (*typeTable)->SetTypeForSymbol(gID_individual,		EidosTypeSpecifier{kEidosValueMaskObject, gSLiM_Individual_Class});
                             (*typeTable)->SetTypeForSymbol(gID_subpop,			EidosTypeSpecifier{kEidosValueMaskObject, gSLiM_Subpopulation_Class});

QtSLiM/help/SLiMHelpClasses.html

@@ -2721,15 +2721,15 @@ The optional parameter
 
 \f4\fs20 \cf2 Returns the sum of the effects of all mutations that are of the type specified by 
 \f3\fs18 mutType
-\f4\fs20 , out of all of the mutations in the haplosome, for the trait(s) specified by 
+\f4\fs20 , out of all of the mutations in the haplosome, for the trait specified by 
 \f3\fs18 trait
-\f4\fs20 .  The traits can be specified as 
+\f4\fs20 .  The trait can be specified as the 
 \f3\fs18 integer
-\f4\fs20  indices or 
+\f4\fs20  index or 
 \f3\fs18 string
-\f4\fs20  names of traits in the species, or directly as 
+\f4\fs20  name of a trait in the species, or directly as a 
 \f3\fs18 Trait
-\f4\fs20  objects; 
+\f4\fs20  object; 
 \f3\fs18 NULL
 \f4\fs20  can be used to represent the one defined trait in a single-trait species.\
 Historically, this method was often useful in models that used a particular mutation type to represent QTLs with additive effects; in that context, 
@@ -4526,15 +4526,15 @@ More specifically, this method uses the parental pedigree IDs from the pedigree
 
 \f4\fs20 \cf2 Returns the sum of the effects of all mutations that are of the type specified by 
 \f3\fs18 mutType
-\f4\fs20 , out of all of the mutations in the haplosomes of the individual, for the trait(s) specified by 
+\f4\fs20 , out of all of the mutations in the haplosomes of the individual, for the trait specified by 
 \f3\fs18 trait
-\f4\fs20 .  The traits can be specified as 
+\f4\fs20 .  The trait can be specified as the 
 \f3\fs18 integer
-\f4\fs20  indices or 
+\f4\fs20  index or 
 \f3\fs18 string
-\f4\fs20  names of traits in the species, or directly as 
+\f4\fs20  name of a trait in the species, or directly as a 
 \f3\fs18 Trait
-\f4\fs20  objects; 
+\f4\fs20  object; 
 \f3\fs18 NULL
 \f4\fs20  can be used to represent the one defined trait in a single-trait species.\
 Historically, this method was often useful in models that used a particular mutation type to represent QTLs with additive effects; in that context, 
@@ -7039,8 +7039,7 @@ Also note that dominance coefficients have a quirk: they are stored internally i
 \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 
+The remaining flags control which columns of data should be returned (for 
 \f3\fs18 kind
 \f4\fs20  options other than 
 \f3\fs18 "count"
@@ -11133,7 +11132,7 @@ After this call, the fitness values used for all purposes in SLiM will be the ne
 \f4\fs20  will be defined as a global variable immediately by this method, and will also be returned by this method.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
-\f3\fs18 \cf2 \kerning1\expnd0\expndtw0 \'96\'a0(object<SLiMEidosBlock>$)registerMutationEffectCallback(Nis$\'a0id, string$\'a0source, io<MutationType>$\'a0mutType, [Nio<Subpopulation>$\'a0subpop\'a0=\'a0NULL], [Ni$\'a0start\'a0=\'a0NULL], [Ni$\'a0end\'a0=\'a0NULL])\
+\f3\fs18 \cf2 \kerning1\expnd0\expndtw0 \'96\'a0(object<SLiMEidosBlock>$)registerMutationEffectCallback(Nis$\'a0id, string$\'a0source, io<MutationType>$\'a0mutType, [Nio<Subpopulation>$\'a0subpop\'a0=\'a0NULL], [Ni$\'a0start\'a0=\'a0NULL], [Ni$\'a0end\'a0=\'a0NULL], [Niso<Trait>$\'a0trait\'a0=\'a0NULL])\
 \pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 
 \f4\fs20 \cf2 Register a block of Eidos source code, represented as the 
@@ -11152,11 +11151,21 @@ After this call, the fitness values used for all purposes in SLiM will be the ne
 \f3\fs18 integer
 \f4\fs20  identifier, or 
 \f3\fs18 NULL
-\f4\fs20 , the default, to indicate all subpopulations), and optional 
+\f4\fs20 , the default, to indicate all subpopulations), optional 
 \f3\fs18 start
 \f4\fs20  and 
 \f3\fs18 end
-\f4\fs20  ticks all limiting its applicability.  The script block will be given identifier 
+\f4\fs20  ticks, and optional trait identifier 
+\f3\fs18 trait
+\f4\fs20  (which may be an 
+\f3\fs18 integer
+\f4\fs20  trait index, a 
+\f3\fs18 string
+\f4\fs20  trait name, a 
+\f3\fs18 Trait
+\f4\fs20  object, or 
+\f3\fs18 NULL
+\f4\fs20  if the species has only one defined trait anyway), all limiting its applicability.  The script block will be given identifier 
 \f3\fs18 id
 \f4\fs20  (specified as an 
 \f3\fs18 integer

SLiMgui/SLiMHelpClasses.rtf

@@ -3828,6 +3828,7 @@ - (BOOL)eidosTextView:(EidosTextView *)eidosTextView completionContextWithScript
 								case SLiMEidosBlockType::SLiMEidosMutationEffectCallback:
 									(*typeTable)->SetTypeForSymbol(gID_mut,				EidosTypeSpecifier{kEidosValueMaskObject, gSLiM_Mutation_Class});
 									(*typeTable)->SetTypeForSymbol(gID_homozygous,		EidosTypeSpecifier{kEidosValueMaskLogical, nullptr});
+									(*typeTable)->SetTypeForSymbol(gID_trait,			EidosTypeSpecifier{kEidosValueMaskObject, gSLiM_Trait_Class});
 									(*typeTable)->SetTypeForSymbol(gID_effect,			EidosTypeSpecifier{kEidosValueMaskFloat, nullptr});
 									(*typeTable)->SetTypeForSymbol(gID_individual,		EidosTypeSpecifier{kEidosValueMaskObject, gSLiM_Individual_Class});
 									(*typeTable)->SetTypeForSymbol(gID_subpop,			EidosTypeSpecifier{kEidosValueMaskObject, gSLiM_Subpopulation_Class});
@@ -4139,7 +4140,7 @@ - (void)updateStatusFieldFromSelection
 			static EidosCallSignature_CSP callbackSig = nullptr;
 
 			if (!callbackSig)
-				callbackSig = EidosCallSignature_CSP((new EidosFunctionSignature("mutationEffect", nullptr, kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddObject_S("mutationType", gSLiM_MutationType_Class)->AddObject_OS("subpop", gSLiM_Subpopulation_Class, gStaticEidosValueNULLInvisible));
+				callbackSig = EidosCallSignature_CSP((new EidosFunctionSignature("mutationEffect", nullptr, kEidosValueMaskNULL | kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddObject_S("mutationType", gSLiM_MutationType_Class)->AddObject_OS("subpop", gSLiM_Subpopulation_Class, gStaticEidosValueNULLInvisible)->AddString_OS("trait", gStaticEidosValueNULLInvisible));
 
 			sig = callbackSig.get();
 		}

SLiMgui/SLiMWindowController.mm

@@ -140,6 +140,11 @@ multitrait branch:
 		- (void)logMutationData(logical$ enable, [logical$ autogeneratedOnly = T], [logical$ meanOnly = F], <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
+	add optional [Ns$ trait = NULL] specifier to the mutationEffect() callback syntax, allowing mutationEffect() callbacks to be defined as specific to a particular trait
+		note that if this new specifier is absent or NULL, the callback will be called separately for each trait; that preserves backward compatibility
+		add trait pseudo-parameter to mutationEffect() callbacks
+		add [Niso<Trait>$ trait = NULL] parameter to registerMutationEffectCallback() to allow the trait specifier to be given (defaults to NULL for backward compatibility)
+	add a new return option for mutationEffect() callbacks: NULL now indicates neutrality for the focal trait, meaning either 1.0 (multiplicative) or 0.0 (additive)
 
 
 version 5.1 (Eidos version 4.1):

VERSIONS

@@ -1318,14 +1318,8 @@ EidosValue_SP Haplosome::ExecuteMethod_sumOfMutationsOfType(EidosGlobalStringID
 	Species &species = individual_->subpopulation_->species_;
 	MutationType *mutation_type_ptr = SLiM_ExtractMutationTypeFromEidosValue_io(mutType_value, 0, &species.community_, &species, "sumOfMutationsOfType()");		// SPECIES CONSISTENCY CHECK
 
-	// get the trait indices, with bounds-checking
-	std::vector<slim_trait_index_t> trait_indices;
-	species.GetTraitIndicesFromEidosValue(trait_indices, trait_value, "sumOfMutationsOfType");
-	
-	if (trait_indices.size() != 1)
-		EIDOS_TERMINATION << "ERROR (Haplosome::ExecuteMethod_sumOfMutationsOfType): sumOfMutationsOfType() requires exactly one trait to be specified." << EidosTerminate();
-	
-	const slim_trait_index_t trait_index = trait_indices[0];
+	// get the trait index, with bounds-checking
+	const slim_trait_index_t trait_index = species.GetTraitIndexFromEidosValue(trait_value, "sumOfMutationsOfType");
 
 	// Sum the selection coefficients of mutations of the given type
 	MutationBlock *mutation_block = species.SpeciesMutationBlock();
@@ -2291,7 +2285,7 @@ const std::vector<EidosMethodSignature_CSP> *Haplosome_Class::Methods(void) cons
 		methods->emplace_back((EidosClassMethodSignature *)(new EidosClassMethodSignature(gStr_outputHaplosomesToMS, kEidosValueMaskVOID))->AddString_OSN(gEidosStr_filePath, gStaticEidosValueNULL)->AddLogical_OS("append", gStaticEidosValue_LogicalF)->AddLogical_OS("filterMonomorphic", gStaticEidosValue_LogicalF));
 		methods->emplace_back((EidosClassMethodSignature *)(new EidosClassMethodSignature(gStr_outputHaplosomesToVCF, kEidosValueMaskVOID))->AddString_OSN(gEidosStr_filePath, gStaticEidosValueNULL)->AddLogical_OS("outputMultiallelics", gStaticEidosValue_LogicalT)->AddLogical_OS("append", gStaticEidosValue_LogicalF)->AddLogical_OS("simplifyNucleotides", gStaticEidosValue_LogicalF)->AddLogical_OS("outputNonnucleotides", gStaticEidosValue_LogicalT)->AddLogical_OS("groupAsIndividuals", gStaticEidosValue_LogicalT));
 		methods->emplace_back((EidosClassMethodSignature *)(new EidosClassMethodSignature(gStr_outputHaplosomes, kEidosValueMaskVOID))->AddString_OSN(gEidosStr_filePath, gStaticEidosValueNULL)->AddLogical_OS("append", gStaticEidosValue_LogicalF)->AddLogical_OS("objectTags", gStaticEidosValue_LogicalF));
-		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_sumOfMutationsOfType, kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddIntObject_S("mutType", gSLiM_MutationType_Class)->AddIntStringObject_OSN("trait", gSLiM_Trait_Class, gStaticEidosValueNULL));
+		methods->emplace_back((EidosInstanceMethodSignature *)(new EidosInstanceMethodSignature(gStr_sumOfMutationsOfType, kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddIntObject_S("mutType", gSLiM_MutationType_Class)->AddIntStringObject_OSN(gStr_trait, gSLiM_Trait_Class, gStaticEidosValueNULL));
 
 		std::sort(methods->begin(), methods->end(), CompareEidosCallSignatures);
 	}