3030
3131
3232class StatisticalModel :
33- """Class that defines a statistical model.
33+ """Base class for defining a statistical model with a likelihood and data generation method .
3434
35- - The statisical model contains two parts that you must define yourself:
35+ - The statistical model contains two parts that you must define yourself:
3636 - a likelihood function
3737 ll(self, parameter_1, parameter_2... parameter_n):
3838 A function of a set of named parameters which
39- return a float expressing the loglikelihood for observed data given these parameters.
39+ return a float expressing the log-likelihood for observed data given these parameters.
4040 - a data generation function
4141 generate_data(self, parameter_1, parameter_2... parameter_n):
4242 A function of the same set of named parameters return a full data set.
@@ -154,7 +154,7 @@ def _check_ll_and_generate_data_signature(self):
154154 raise AssertionError ("ll and generate_data must have the same signature (parameters)" )
155155
156156 def _ll (self , ** kwargs ) -> float :
157- """Likelihood function, return the loglikelihood for the given parameters."""
157+ """Likelihood function, return the log-likelihood for the given parameters."""
158158 raise NotImplementedError (
159159 "You must write a likelihood function (_ll) for your statistical model"
160160 " or use a subclass where it is written for you"
@@ -169,9 +169,10 @@ def _generate_data(self, **kwargs):
169169
170170 @_needs_data
171171 def ll (self , ** kwargs ) -> float :
172- """Likelihod function, returns the loglikelihood for the given parameters. The parameters
173- are passed as keyword arguments, positional arguments are not possible. If a parameter is
174- not given, the default value is used.
172+ """Return the log-likelihood for the given parameters.
173+
174+ Parameters are passed as keyword arguments; positional arguments are not supported.
175+ If a parameter is not given, the default value is used.
175176
176177 Keyword Args:
177178 kwargs: keyword arguments for the parameters
@@ -184,9 +185,10 @@ def ll(self, **kwargs) -> float:
184185 return self ._ll (** parameters )
185186
186187 def generate_data (self , ** kwargs ) -> Union [dict , list ]:
187- """Generate data for the given parameters. The parameters are passed as keyword arguments,
188- positional arguments are not possible. If a parameter is not given, the default value is
189- used.
188+ """Generate data for the given parameters.
189+
190+ Parameters are passed as keyword arguments; positional arguments are not supported.
191+ If a parameter is not given, the default value is used.
190192
191193 Raises:
192194 ValueError: If the parameters are not within the fit limits
@@ -205,10 +207,10 @@ def generate_data(self, **kwargs) -> Union[dict, list]:
205207
206208 @property
207209 def data (self ):
208- """Simple getter for a data-set-- mainly here so it can be over-ridden for special needs.
210+ """Return the dataset, overridable for special needs.
209211
210- Data-sets are expected to be in the form of a list of one or more structured arrays,
211- representing the data-sets of one or more likelihood terms.
212+ Datasets are expected to be in the form of a list of one or more structured arrays,
213+ representing the datasets of one or more likelihood terms.
212214
213215 """
214216 if self ._data is None :
@@ -228,10 +230,9 @@ def store_data(
228230 data_name_list : Optional [List [str ]] = None ,
229231 metadata : Optional [dict ] = None ,
230232 ):
231- """
232- Store a list of datasets.
233- (each on the form of a list of one or more structured arrays or dicts)
234- Using inference_interface, but included here to allow over-writing.
233+ """Store a list of datasets to a file using inference_interface.
234+
235+ Each dataset is in the form of a list of one or more structured arrays or dicts.
235236 The structure would be: ``[[datasets1], [datasets2], ..., [datasetsn]]``,
236237 where each of datasets is a list of structured arrays.
237238 If you specify, it is set, if not it will read from ``self.get_likelihood_term_names``.
@@ -244,6 +245,7 @@ def store_data(
244245 If None, it will be read from self.get_likelihood_term_names
245246 metadata (dict, optional (default=None)): metadata to store with the data.
246247 If None, no metadata is stored.
248+
247249 """
248250 if all ([isinstance (d , dict ) for d in data_list ]) or all (
249251 [isinstance (d , ReadOnlyDict ) for d in data_list ]
@@ -337,10 +339,11 @@ def cost(args):
337339 def fit (
338340 self , verbose : Optional [bool ] = False , fit_strategy : Optional [dict ] = None , ** kwargs
339341 ) -> Tuple [dict , float ]:
340- """Fit the model to the data by maximizing the likelihood. Return a dict containing best-fit
341- values of each parameter, and the value of the likelihood evaluated there. While the
342- optimization is a minimization, the likelihood returned is the __maximum__ of the
343- likelihood.
342+ """Fit the model to the data by maximizing the likelihood.
343+
344+ Returns a dict of best-fit parameter values and the maximum log-likelihood value.
345+ While the optimization is a minimization internally, the likelihood returned
346+ is the maximum.
344347
345348 Args:
346349 verbose (bool): if True, print the Minuit object
@@ -590,10 +593,13 @@ def confidence_interval(
590593 asymptotic_dof : Optional [int ] = None ,
591594 fit_strategy : Optional [dict ] = None ,
592595 ) -> Tuple [float , float ]:
593- """Uses self.fit to compute confidence intervals for a certain named parameter. If the
594- parameter is a rate parameter, and the model has expectation values implemented, the bounds
595- will be interpreted as bounds on the expectation value, so that the range in the fit is
596- parameter_interval_bounds/mus. Otherwise the bound is taken as-is.
596+ """Compute confidence intervals for the parameter of interest (POI).
597+
598+ Finds the intersection between the profile log-likelihood curve and the
599+ critical value curve to determine the confidence interval edges.
600+ If the parameter is a rate parameter and the model has expectation values implemented,
601+ the bounds will be interpreted as bounds on the expectation value, so that the range
602+ in the fit is parameter_interval_bounds/mus. Otherwise the bound is taken as-is.
597603
598604 Args:
599605 poi_name (str): name of the parameter of interest
@@ -720,8 +726,9 @@ def get_model_from_name(statistical_model: str):
720726
721727
722728class MinuitWrap :
723- """Wrapper for functions to be called by Minuit. Initialized with a function f and a Parameters
724- instance.
729+ """Wrapper for functions to be called by Minuit.
730+
731+ Initialized with a function f and a Parameters instance.
725732
726733 Attributes:
727734 func: function wrapped
![pre-commit-ci[bot]](https://avatars.githubusercontent.com/in/68672?v=4&size=40){kind=avatar}
0 commit comments