fixed evaluationType docstrings

WolfgangWaltenberger · WolfgangWaltenberger · commit 793f05015263 · 2025-11-12T21:49:45.000+01:00
diff --git a/smodels/experiment/datasetObj.py b/smodels/experiment/datasetObj.py
@@ -358,10 +358,10 @@ def getUpperLimitFor(self, sms=None, evaluationType=False, txnames=None,
         :param sms: SMS object (only for UL-type results)
         :param mass: Mass array  (only for UL-type results)
         :param alpha: Can be used to change the C.L. value. The default value is 0.05
-                      (= 95% C.L.) (only for  efficiency-map results)
+        (= 95% C.L.) (only for  efficiency-map results)
         :param deltas_rel: relative uncertainty in signal (float). Default value is 20%.
-        :param expected: Compute evaluationType limit, i.e. Nobserved = NexpectedBG
-                         (only for efficiency-map results)
+        :param evaluationType: one of: observed, apriori, aposteriori
+        (only for efficiency-map results)
         :param compute: If True, the upper limit will be computed
                         from expected and observed number of events.
                         If False, the value listed in the database will be used
@@ -419,9 +419,9 @@ def getSRUpperLimit(self,evaluationType : NllEvalType = observed ):
         Returns the 95% upper limit on the signal*efficiency for a given dataset (signal region).
         Only to be used for efficiency map type results.
 
-        :param expected: If True, return the evaluationType limit ( i.e. Nobserved = NexpectedBG )
+        :param evaluationType: one of: observed, apriori, aposteriori
 
-        :return: upper limit value
+        :returns: upper limit value
         """
 
         if not self.getType() == 'efficiencyMap':
diff --git a/smodels/experiment/expResultObj.py b/smodels/experiment/expResultObj.py
@@ -258,9 +258,9 @@ def getUpperLimitFor(self, dataID=None, alpha=0.05, evaluationType=False,
 
         :param dataID: dataset ID (string) (only for efficiency-map type results)
         :param alpha: Can be used to change the C.L. value. The default value is 0.05
-                      (= 95% C.L.) (only for  efficiency-map results)
-        :param expected: Compute evaluationType limit, i.e. Nobserved = NexpectedBG
-                         (only for efficiency-map results)
+        (= 95% C.L.) (only for efficiency-map results)
+        :param evaluationType: Compute <evaluationType> limit, e.g. Nobserved = NexpectedBG
+        for a priori (only for efficiency-map results)
         :param txname: TxName object or txname string (only for UL-type results)
         :param sms: SMS object
         :param mass: Mass array
diff --git a/smodels/experiment/txnameObj.py b/smodels/experiment/txnameObj.py
@@ -820,7 +820,7 @@ def getULFor(self, sms, evaluationType : NllEvalType = observed, mass=None):
 
 
         :param sms: SMS object or mass array (with units)
-        :param expected: look in self.txnameDataExp, not self.txnameData
+        :param evaluationType: if apriori, look in self.txnameDataExp, not self.txnameData
         """
 
         if not self.dataType == 'upperLimit':
diff --git a/smodels/matching/theoryPrediction.py b/smodels/matching/theoryPrediction.py
@@ -201,7 +201,7 @@ def getUpperLimit(self, evaluationType : NllEvalType = observed ) -> UnitXSec:
         For combined results, returns the upper limit on the
         total sigma*eff (for all signal regions/datasets).
 
-        :param expected: return evaluationType Upper Limit, instead of observed.
+        :param evaluationType: one of: observed, apriori, aposteriori
         :return: upper limit (Unum object)
         """
         if self.dataType() == "efficiencyMap":
@@ -360,7 +360,7 @@ def computeStatistics(self, evaluationType : NllEvalType = observed ):
         Compute the likelihoods, and upper limit for this theory prediction.
         The resulting values are stored as the likelihood, lmax, and lsm
         attributes.
-        :param expected: computed evaluationType quantities, not observed
+        :param evaluationType: one of: observed, apriori, aposteriori
         """
         # Compute likelihoods and related parameters:
         llhdDict = self.statsComputer.get_five_values(
@@ -533,7 +533,7 @@ def getLlhds(self,muvals,evaluationType : bool = False,
 
         :param muvals: List with values for the signal strenth for which
         the likelihoods must be evaluated.
-        :param expected: If True returns the evaluationType likelihood values.
+        :param evaluationType: returns the observed/priori expected/posteriori expected likelihood values.
         :param normalize: If True normalizes the likelihood by its integral
         over muvals.
         """
@@ -897,7 +897,7 @@ def _getBestResult(dataSetResults):
             raise SModelSError(txt)
         pred = predList[0]
         xsec = pred.xsection
-        expectedR = (xsec/dataset.getSRUpperLimit(evaluationType=True)).asNumber()
+        expectedR = (xsec/dataset.getSRUpperLimit(evaluationType=apriori)).asNumber()
         if expectedR > bestExpectedR or (expectedR == bestExpectedR and xsec > bestXsec):
             bestExpectedR = expectedR
             bestPred = pred
diff --git a/smodels/statistics/analysesCombinations.py b/smodels/statistics/analysesCombinations.py
@@ -52,7 +52,7 @@ def nll(
         just a proxy method to ease transition of codes that depend on SModelS.
 
         :param mu: signal strength
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param asimov: if not None, compute llhd for asimov data with mu=asimov
         """
         return self.likelihood ( mu, evaluationType, return_nll=True, asimov=asimov )
@@ -69,7 +69,7 @@ def likelihood(
         Compute the likelihood at a given mu
 
         :param mu: signal strength
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param return_nll: if True, return negative log likelihood, else likelihood
         :param asimov: if not None, compute llhd for asimov data with mu=asimov
         """
@@ -107,7 +107,7 @@ def lmax(
         """find muhat and lmax.
 
         :param allowNegativeSignals: if true, then also allow for negative values
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param return_nll: if true, return negative log max likelihood instead of lmax
         :returns: mu_hat, i.e. the maximum likelihood estimate of mu, if extended \
                   output is requested, it returns a dictionary with mu_hat, \
@@ -229,7 +229,7 @@ def getUpperLimitOnMu(self, evaluationType : NllEvalType=observed, allowNegative
         """get upper limit on signal strength multiplier, i.e. value for mu for \
            which CLs = 0.95
 
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :returns: upper limit on signal strength multiplier mu
         """
         mu_hat, sigma_mu, clsRoot = self.getCLsRootFunc(evaluationType=evaluationType,
@@ -247,7 +247,7 @@ def getUpperLimitOnSigmaTimesEff(self, evaluationType : NllEvalType=observed, al
             for each signal region/dataset), by using
             the q_mu test statistic from the CCGV paper (arXiv:1007.1727).
 
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :returns: upper limit on fiducial cross section
         """
         ul = self.getUpperLimitOnMu(evaluationType=evaluationType,
@@ -266,7 +266,7 @@ def getCLsRootFunc(self, evaluationType : NllEvalType=observed,
         Obtain the function "CLs-alpha[0.05]" whose root defines the upper limit,
         plus mu_hat and sigma_mu
 
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         """
         fmh = self.lmax(evaluationType=evaluationType, allowNegativeSignals=allowNegativeSignals)
         mu_hat, sigma_mu, _ = fmh["muhat"], fmh["sigma_mu"], fmh["lmax"]
@@ -301,7 +301,7 @@ def CLs( self, mu : float = 1., evaluationType : NllEvalType=observed,
         Compute the exclusion confidence level of the model
 
         :param mu: compute for the parameter of interest mu
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param return_type: (Text) can be "CLs-alpha", "1-CLs", "CLs" \
                         CLs-alpha: returns CLs - 0.05 \
                         alpha-CLs: returns 0.05 - CLs \
@@ -322,7 +322,7 @@ def getLlhds(self,muvals,evaluationType : NllEvalType=observed,
 
         :param muvals: List with values for the signal strenth for which the likelihoods must
                        be evaluated.
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param normalize: If True normalizes the likelihood by its integral over muvals.
         """
 
diff --git a/smodels/statistics/pyhfInterface.py b/smodels/statistics/pyhfInterface.py
@@ -378,7 +378,7 @@ def __init__(self, data, cl=0.95, lumi=None ):
         :ivar nWS: number of workspaces = number of json files
         :ivar patches: list of patches to be applied to the inputJsons as python dictionary instances
         :ivar workspaces: list of workspaces resulting from the patched inputJsons
-        :ivar workspaces_expected: list of patched workspaces with observation yields replaced by the evaluationType ones
+        :ivar workspaces_expected: list of patched workspaces with observation yields replaced by the expected eones
         :ivar cl: created from cl
         :ivar scale: scale that is applied to the signal predictions, dynamically changes throughout the upper limit calculation
         :ivar alreadyBeenThere: boolean flag that identifies when nsignals accidentally passes twice at two identical values
@@ -685,7 +685,7 @@ def likelihood( self, mu : float = 1.0,
         :param workspace_index: supply index of workspace to use. If None, \
                                 choose index of best combo
         :param return_nll: if true, return nll, not llhd
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         """
         logger.debug("Calling likelihood")
         if type(workspace_index) == float:
@@ -856,7 +856,7 @@ def lmax( self, workspace_index=None, return_nll=False, evaluationType : NllEval
         :param return_nll: if true, return nll, not llhd
         :param workspace_index: supply index of workspace to use. If None, \
             choose index of best combo
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param allowNegativeSignals: if False, then negative nsigs are replaced \
             with 0.
         """
@@ -957,7 +957,7 @@ def updateWorkspace(self, workspace_index=None, evaluationType : NllEvalType=obs
         Small method used to return the appropriate workspace
 
         :param workspace_index: the index of the workspace to retrieve from the corresponding list
-        :param expected: if False, retuns the unmodified (but patched) workspace. Used for computing observed or aposteriori evaluationType limits.
+        :param evaluationType: if False, retuns the unmodified (but patched) workspace. Used for computing observed or aposteriori evaluationType limits.
                         if True, retuns the modified (and patched) workspace, where obs = sum(bkg). Used for computing apriori evaluationType limit.
         """
         if self.nWS == 1:
@@ -980,7 +980,7 @@ def getUpperLimitOnSigmaTimesEff(self, evaluationType : NllEvalType=observed, wo
             - if workspace_index is specified, self.workspace[workspace_index]
               (useful for computation of the best upper limit)
 
-        :param expected:  - if set to apriori: uses evaluationType SM backgrounds as signals
+        :param evaluationType:  - if set to apriori: uses evaluationType SM backgrounds as signals
                           - else: uses 'self.nsignals'
         :param workspace_index: - if different from 'None': index of the workspace to use
                                   for upper limit
@@ -1033,7 +1033,7 @@ def CLs( self, mu : float, evaluationType : NllEvalType,
         _absolute_ mu
 
         :param mu: compute for the parameter of interest mu
-        :param expected: if observed, compute observed, apriori: compute a priori expected
+        :param evaluationType: if observed, compute observed, apriori: compute a priori expected
         :param return_type: (Text) can be one of:
         "CLs-alpha", "1-CLs", "CLs" "alpha-CLs"
         CLs-alpha: returns CLs - 0.05
@@ -1050,7 +1050,7 @@ def _CLs( self, mu_rel : float, evaluationType : NllEvalType,
         This is our internal method to compute CLs.
 
         :param mu_rel: compute for the parameter of interest mu_rel
-        :param expected: one of: observed, apriori, aposteriori
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param return_type: (Text) can be one of:
         "CLs-alpha", "1-CLs", "CLs" "alpha-CLs"
         CLs-alpha: returns CLs - 0.05
@@ -1136,7 +1136,7 @@ def getUpperLimitOnMu(self, evaluationType : NllEvalType=observed, workspace_ind
             - if workspace_index is specified, self.workspace[workspace_index]
               (useful for computation of the best upper limit)
 
-        :param expected:  - if set to apriori: uses evaluationType SM backgrounds as signals
+        :param evaluationType:  - if set to apriori: uses evaluationType SM backgrounds as signals
                           - else: uses 'self.nsignals'
         :param workspace_index: - if different from 'None': index of the workspace to use
                                   for upper limit
diff --git a/smodels/statistics/simplifiedLikelihoods.py b/smodels/statistics/simplifiedLikelihoods.py
@@ -555,7 +555,7 @@ def llhdOfTheta(self, theta, nll = True ):
             self.mu. notice, by default it returns nll
 
         :param theta: nuisance parameters
-        :params nll: if True, compute negative log likelihood
+        :param nll: if True, compute negative log likelihood
         """
         model = self.model
         # theta = array ( thetaA )
@@ -995,8 +995,8 @@ def getUpperLimitOnSigmaTimesEff(
             for each signal region/dataset), by using
             the q_mu test statistic from the CCGV paper (arXiv:1007.1727).
 
-        :params expected: one of: observed, apriori, aposteriori
-        :params trylasttime: if True, then dont try extra
+        :param evaluationType: one of: observed, apriori, aposteriori
+        :param trylasttime: if True, then dont try extra
         :returns: upper limit on fiducial cross section
         """
         model = self.likelihoodComputer.model
@@ -1021,8 +1021,7 @@ def getCLsRootFunc(
         plus mu_hat and sigma_mu
 
         :param model: statistical model
-        :param expected: false: compute observed, true: compute a priori evaluationType, \
-            "posteriori": compute a posteriori expected
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param trylasttime: if True, then dont try extra
         :return: mu_hat, sigma_mu, CLs-alpha
         """
@@ -1086,8 +1085,8 @@ def getUpperLimitOnMu(
         for each signal regio/dataset), by using
         the q_mu test statistic from the CCGV paper (arXiv:1007.1727).
 
-        :params expected: one of: observed, apriori, aposteriori
-        :params trylasttime: if True, then dont try extra
+        :param evaluationType: one of: observed, apriori, aposteriori
+        :param trylasttime: if True, then dont try extra
         :returns: upper limit on the signal strength multiplier mu
         """
         mu_hat, sigma_mu, clsRoot = self.getCLsRootFunc(
@@ -1114,9 +1113,7 @@ def CLs(
         Compute the exclusion confidence level of the model (1-CLs).
 
         :param model: statistical model
-        :param expected: if false, compute observed,
-                         true: compute a priori evaluationType, "posteriori":
-                         compute a posteriori expected
+        :param evaluationType: one of: observed, apriori, aposteriori
         :param trylasttime: if True, then dont try extra
         :param return_type: (Text) can be "CLs-alpha", "1-CLs", "CLs"
                             CLs-alpha: returns CLs - 0.05 (alpha)
