Submodules — hepstats 0.2.1 documentation

# Submodules

## hepstats.modeling module

Module for algorithms and methods used to model distributions.

This module contains in particular:

> - Bayesian Blocks binning algorithm.

### Bayesian blocks

#### Bayesian Block implementation

Dynamic programming algorithm for finding the optimal adaptive-width histogram. Modified from the bayesian blocks python implementation found in astroML [VCIG12].

- Based on Scargle et al 2012 [SNJC13]

- Initial Python Implementation [BB_]

- Initial Examination in HEP context [PBS17]

class `hepstats.modeling.bayesian_blocks.` `Prior`(p0=0.05, gamma=None)

  Bases: `object`

  Helper class for calculating the prior on the fitness function.

  Methods

  calc |

  `calc`(self, N)

`hepstats.modeling.bayesian_blocks.` `bayesian_blocks`(data, weights=None, p0=0.05, gamma=None)

  Bayesian Blocks Implementation.

  This is a flexible implementation of the Bayesian Blocks algorithm described in Scargle 2012 [1]_. It has been modified to natively accept weighted events, for ease of use in HEP applications.

  Args:

    - data (array): Input data values (one dimensional, length N). Repeat values are allowed.

    - weights (array_like, optional): Weights for data (otherwise assume all data points have a weight of 1). Must be same length as data. Defaults to None.

    - p0 (float, optional): False-positive rate, between 0 and 1. A lower number places a stricter penalty against creating more bin edges, thus reducing the potential for false-positive bin edges. In general, the larger the number of bins, the small the p0 should be to prevent the creation of spurious, jagged bins. Defaults to 0.05.

    - gamma (float, optional): If specified, then use this gamma to compute the general prior form, p ~ gamma^N. If gamma is specified, p0 is ignored. Defaults to None.

  Returns:

    - edges (ndarray): Array containing the (N+1) bin edges

  Examples:

    Unweighted data:

        >>> d = np.random.normal(size=100)
        >>> bins = bayesian_blocks(d, p0=0.01)

    Unweighted data with repeats:

        >>> d = np.random.normal(size=100)
        >>> d[80:] = d[:20]
        >>> bins = bayesian_blocks(d, p0=0.01)

    Weighted data:

        >>> d = np.random.normal(size=100)
        >>> w = np.random.uniform(1,2, size=100)
        >>> bins = bayesian_blocks(d, w, p0=0.01)

## hepstats.hypotests module

Module for hypothesis tests, upper limits and confidence intervals calculations.

### Parameters

Module defining the parameter of interest classes, currently includes:

- POIarray

- POI

class `hepstats.hypotests.parameters.` `POI`(parameter, value)

  Bases: `hepstats.hypotests.parameters.POIarray`

  Class for single value parameter of interest:

  > Args:

  >   - parameter: the parameter of interest

  >   - values (float, int): value of the parameter of interest

  > Example with zfit:

  >       >>> Nsig = zfit.Parameter("Nsig")
  >       >>> poi = POI(Nsig, value=0)

  Attributes
    `ndim`

      Returns the number of dimension of the POIarray.

    `shape`

      Returns the shape of the POIarray.

    `value`

      Returns the value of the POI.

    `values`

      Returns the values of the POIarray.

  Methods

  `append`(self, values) | Append values in the POIarray.

  property `value`

    Returns the value of the POI.

class `hepstats.hypotests.parameters.` `POIarray`(parameter, values)

  Bases: `object`

  Class for parameters of interest with multiple values:

  > Args:

  >   - parameter: the parameter of interest

  >   - values (list(float),`numpy.array`): values of the parameter of interest

  > Example with zfit:

  >       >>> Nsig = zfit.Parameter("Nsig")
  >       >>> poi = POIarray(Nsig, value=np.linspace(0,10,10))

  Attributes
    `ndim`

      Returns the number of dimension of the POIarray.

    `shape`

      Returns the shape of the POIarray.

    `values`

      Returns the values of the POIarray.

  Methods

  `append`(self, values) | Append values in the POIarray.

  `append`(self, values)

    Append values in the POIarray.

    Args:

      - values (list(float),`numpy.array`): values to append

  property `ndim`

    Returns the number of dimension of the POIarray.

  property `shape`

    Returns the shape of the POIarray.

  property `values`

    Returns the values of the POIarray.

`hepstats.hypotests.parameters.` `asarray`(POI)

  Transforms a POI instance into a POIarray instance.

### Calculators

Module defining the base class for the calculators for statistical tests based on the likelyhood ratio.

Any calculator can be a subclass of BaseCalculator. Currently implemented:

> - AsymptoticCalculator: calculator using the asymptotic formulae of the likehood ratio.

Acronyms used in the code:

  - nll = negative log-likehood, the likehood being the loss attribute of a calculator;

  - obs = observed, i.e. measured on provided data.

class `hepstats.hypotests.calculators.basecalculator.` `BaseCalculator`(input, minimizer)

  Bases: `hepstats.hypotests.hypotests_object.HypotestsObject`

  Base class for calculator.

  Args:

    - input : loss or fit result

    - minimizer : minimizer to use to find the minimum of the loss function

  Example with zfit:

        >>> import zfit
        >>> from zfit.core.loss import UnbinnedNLL
        >>> from zfit.minimize import Minuit

        >>> obs = zfit.Space('x', limits=(0.1, 2.0))
        >>> data = zfit.data.Data.from_numpy(obs=obs, array=np.random.normal(1.2, 0.1, 10000))
        >>> mean = zfit.Parameter("mu", 1.2)
        >>> sigma = zfit.Parameter("sigma", 0.1)
        >>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
        >>> loss = UnbinnedNLL(model=model, data=data)

        >>> calc = BaseCalculator(input=loss, minimizer=Minuit())

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

  Methods

  `check_pois`(pois) | Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.
  `check_pois_compatibility`(poi1, poi2) | Checks compatibility between two lists of hepstats.parameters.POIarray instances.
  `expected_poi`(self, poinull, poialt, nsigma) | Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)
  `expected_pvalue`(self, poinull, poialt, nsigma) | Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)
  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `obs_nll`(self, pois) | Compute observed negative log-likelihood values for given parameters of interest.
  `pvalue`(self, poinull, poialt, NoneType] = None) | Computes pvalues for the null and alternative hypothesis.
  `q`(self, nll1, nll2, poi1, poi2[, onesided, …]) | Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).
  `qobs`(self, poinull[, onesided, …]) | Computes observed values of the \(\Delta\) log-likelihood test statistic.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values

  static `check_pois`(pois)

    Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

  static `check_pois_compatibility`(poi1, poi2)

    Checks compatibility between two lists of hepstats.parameters.POIarray instances.

  `expected_poi`(self, poinull: List[hepstats.hypotests.parameters.POI], poialt: List[hepstats.hypotests.parameters.POI], nsigma, alpha=0.05, CLs=False, qtilde=False, onesided=True, onesideddiscovery=False)

    Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)

    Args:

      - poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

      - poialt (List[hypotests.POI], optional): parameters of interest for the alternative hypothesis

      - nsigma (numpy.array): array of values of \(\sigma\) to compute the expected pvalue

      - alpha (float, default=0.05): significance level

      - CLs (bool, optional): if True uses pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\)

      - qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

      - onesided (bool, optional): if True (default) computes onesided pvalues

      - onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery

    Returns:

      numpy.array: array of expected POI values for each :math:`sigma value

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POI(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, 1.2)
          >>> nll = calc.expected_poi(poinull, poialt)

  `expected_pvalue`(self, poinull: List[hepstats.hypotests.parameters.POI], poialt: List[hepstats.hypotests.parameters.POI], nsigma, CLs=False, qtilde=False, onesided=True, onesideddiscovery=False) → Dict[int, <built-in function array>]

    Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)

    Args:

      - poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

      - poialt (List[hypotests.POI], optional): parameters of interest for the alternative hypothesis

      - nsigma (numpy.array): array of values of \(\sigma\) to compute the expected pvalue

      - CLs (bool, optional): if True computes pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\)

      - qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

      - onesided (bool, optional): if True (default) computes onesided pvalues

      - onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery

    Returns:

      numpy.array: array of expected pvalues for each \(\sigma\) value

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POI(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, 1.2)
          >>> nll = calc.expected_pvalue(poinull, poialt)

  `obs_nll`(self, pois) → numpy.ndarray

    Compute observed negative log-likelihood values for given parameters of interest.

    Args:

      - pois (List[hypotests.POI]): parameters of interest

    Returns:

      numpy.array: observed nll values

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poi = POI(mean, [1.1, 1.2, 1.0])
          >>> nll = calc.obs_nll(poi)

  `pvalue`(self, poinull: List[hepstats.hypotests.parameters.POI], poialt: Union[List[hepstats.hypotests.parameters.POI], NoneType] = None, qtilde=False, onesided=True, onesideddiscovery=False) → Tuple[numpy.ndarray, numpy.ndarray]

    Computes pvalues for the null and alternative hypothesis.

    Args:

      - poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

      - poialt (List[hypotests.POI], optional): parameters of interest for the alternative hypothesis

      - qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

      - onesided (bool, optional): if True (default) computes onesided pvalues

      - onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery test

    Returns:

      Tuple(numpy.array, numpy.array): pnull, palt

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POI(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, 1.2)
          >>> pvalues = calc.pavalue(poinull, poialt)

  `q`(self, nll1: <built-in function array>, nll2: <built-in function array>, poi1, poi2, onesided=True, onesideddiscovery=False) → numpy.ndarray

    Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).

    Args:

      - nll1 (numpy.array): array of nll values #1, evaluated with poi1

      - nll2 (numpy.array): array of nll values #2, evaluated with poi2

      - poi1 ((List[hypotests.POI])): list of POI’s #1

      - poi2 ((List[hypotests.POI])): list of POI’s #2

      - onesided (bool, optional, default=True)

      - onesideddiscovery (bool, optional, default=True)

    Returns:

      numpy.array: array of \(q\) values

  `qobs`(self, poinull: List[hepstats.hypotests.parameters.POI], onesided=True, onesideddiscovery=False, qtilde=False)

    Computes observed values of the \(\Delta\) log-likelihood test statistic.

    Args:

      - poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

      - qtilde (bool, optional): if True use the \(\tilde{q}\) test statistics else (default) use the \(q\) test statistic

      - onesided (bool, optional): if True (default) computes onesided pvalues

      - onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery test

    Returns:

      numpy.array: observed values of q

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poi = POI(mean, [1.1, 1.2, 1.0])
          >>> q = calc.qobs(poi)

class `hepstats.hypotests.calculators.basecalculator.` `BaseToysCalculator`(input, minimizer, sampler, sample)

  Bases: `hepstats.hypotests.calculators.basecalculator.BaseCalculator`

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

  Methods

  `check_pois`(pois) | Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.
  `check_pois_compatibility`(poi1, poi2) | Checks compatibility between two lists of hepstats.parameters.POIarray instances.
  `expected_poi`(self, poinull, poialt, nsigma) | Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)
  `expected_pvalue`(self, poinull, poialt, nsigma) | Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)
  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `obs_nll`(self, pois) | Compute observed negative log-likelihood values for given parameters of interest.
  `pvalue`(self, poinull, poialt, NoneType] = None) | Computes pvalues for the null and alternative hypothesis.
  `q`(self, nll1, nll2, poi1, poi2[, onesided, …]) | Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).
  `qobs`(self, poinull[, onesided, …]) | Computes observed values of the \(\Delta\) log-likelihood test statistic.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values

class `hepstats.hypotests.calculators.basecalculator.` `ToysCalculator`(input, minimizer, ntoysnull=100, ntoysalt=100, sampler=<function base_sampler>, sample=<function base_sample>)

  Bases: `hepstats.hypotests.calculators.basecalculator.BaseToysCalculator`, `hepstats.hypotests.toyutils.ToysManager`

  Class for calculators using toys.

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

    `ntoysalt`

      Returns the number of toys generated for the alternative hypothesis.

    `ntoysnull`

      Returns the number of toys generated for the null hypothesis.

  Methods

  `add_toyresult`(self, toy) | Add ToyResult to the manager.
  `check_pois`(pois) | Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.
  `check_pois_compatibility`(poi1, poi2) | Checks compatibility between two lists of hepstats.parameters.POIarray instances.
  `expected_poi`(self, poinull, poialt, nsigma) | Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)
  `expected_pvalue`(self, poinull, poialt, nsigma) | Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)
  `from_yaml`(filename, loss, minimizer[, …]) | ToysCalculator constructor with the toys loaded from a yaml file.
  `generate_and_fit_toys`(self, ntoys, poigen, …) | Generate and fit toys for at a given POI (poigen).
  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `get_toyresult`(self, poigen, poieval) | Getter function.
  `get_toys_alt`(self, poigen, poieval[, qtilde]) | Return the generated toys for the alternative hypothesis.
  `get_toys_null`(self, poigen, poieval[, qtilde]) | Return the generated toys for the null hypothesis.
  `keys`(self) | Returns keys of the ToysManager instance defined as key = (toy.poigen, toy.poieval) for a given ToyResult instance toy.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `ntoys`(self, poigen, poieval) | Return the number of toys generated from given value of a POI, and scanned/evaluated for given values_equal of the same POI.
  `obs_nll`(self, pois) | Compute observed negative log-likelihood values for given parameters of interest.
  `pvalue`(self, poinull, poialt, NoneType] = None) | Computes pvalues for the null and alternative hypothesis.
  `q`(self, nll1, nll2, poi1, poi2[, onesided, …]) | Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).
  `qobs`(self, poinull[, onesided, …]) | Computes observed values of the \(\Delta\) log-likelihood test statistic.
  `sample`(self, sampler, ntoys[, poi]) | Returns the samples generated from the sampler for a given value of a parameter of interest
  `sampler`(self[, floating_params]) | Create sampler with models.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values
  `to_yaml`(self, filename) | Save the toys into a yaml file under the key toys.
  `toyresults_to_dict`(self) | Returns a list of all the toy results converted into dictionnaries
  `toys_loss`(self, parameter_name) | Construct a loss function constructed with a sampler for a given floating parameter
  `toysresults_from_yaml`(self, filename) | Extract toy results from a yaml file.
  `values`(self) | Returns values of ToysManager instance that are ToyResult instances.

  classmethod `from_yaml`(filename, loss, minimizer, ntoysnull=100, ntoysalt=100, sampler=<function base_sampler at 0x129062560>, sample=<function base_sample at 0x1290628c0>)

    ToysCalculator constructor with the toys loaded from a yaml file.

    Args:

      - filename (str)

      - input : loss or fit result

      - minimizer : minimizer to use to find the minimum of the loss function

      - ntoysnull (int, default=100): minimum number of toys to generate for the null hypothesis

      - ntoysalt (int, default=100): minimum number of toys to generate for the alternative hypothesis

      - sampler : function used to create sampler with models, number of events and floating parameters in the sample Default is hepstats.fitutils.sampling.base_sampler.

      - sample : function used to get samples from the sampler. Default is hepstats.fitutils.sampling.base_sample.

    Returns

      ToysCalculator

  `get_toys_alt`(self, poigen, poieval, qtilde=False)

    Return the generated toys for the alternative hypothesis.

    Args:

      - poigen (POI): POI used to generate the toys

      - ntoys (int): number of toys to generate

      - poieval (POIarray): POI values to evaluate the loss function

      - qtilde (bool, optional): if True use the :math:` ilde{q}` test statistics else (default) use the \(q\) test statistic

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, 1.2)
          >>> calc.get_toys_alt(poialt, poieval=poinull)

  `get_toys_null`(self, poigen, poieval, qtilde=False)

    Return the generated toys for the null hypothesis.

    Args:

      - poigen (POI): POI used to generate the toys

      - ntoys (int): number of toys to generate

      - poieval (POIarray): POI values to evaluate the loss function

      - qtilde (bool, optional): if True use the :math:` ilde{q}` test statistics else (default) use the \(q\) test statistic

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, 1.2)
          >>> for p in poinull:
          ...     calc.get_toys_alt(p, poieval=poialt)

  property `ntoysalt`

    Returns the number of toys generated for the alternative hypothesis.

  property `ntoysnull`

    Returns the number of toys generated for the null hypothesis.

#### Asymptotic

class `hepstats.hypotests.calculators.asymptotic_calculator.` `AsymptoticCalculator`(input, minimizer, asimov_bins=100)

  Bases: `hepstats.hypotests.calculators.basecalculator.BaseCalculator`

  Class for asymptotic calculators. Can be used only with one parameter of interest.

  See G. Cowan, K. Cranmer, E. Gross and O. Vitells: Asymptotic formulae for likelihood- based tests of new physics. Eur. Phys. J., C71:1–19, 2011

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

  Methods

  `asimov_dataset`(self, poi) | Gets the Asimov dataset for a given alternative hypothesis.
  `asimov_loss`(self, poi) | Constructs a loss function using the Asimov dataset for a given alternative hypothesis.
  `asimov_nll`(self, pois, poialt) | Computes negative log-likelihood values for given parameters of interest using the Asimov dataset generated with a given alternative hypothesis.
  `check_pois`(pois) | Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.
  `check_pois_compatibility`(poi1, poi2) | Checks compatibility between two lists of hepstats.parameters.POIarray instances.
  `expected_poi`(self, poinull, poialt, nsigma) | Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)
  `expected_pvalue`(self, poinull, poialt, nsigma) | Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)
  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `obs_nll`(self, pois) | Compute observed negative log-likelihood values for given parameters of interest.
  `palt`(self, qobs, qalt[, onesided, …]) | Computes the pvalue for the alternative hypothesis.
  `pnull`(self, qobs[, qalt, onesided, …]) | Computes the pvalue for the null hypothesis.
  `pvalue`(self, poinull, poialt, NoneType] = None) | Computes pvalues for the null and alternative hypothesis.
  `q`(self, nll1, nll2, poi1, poi2[, onesided, …]) | Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).
  `qalt`(self, poinull, poialt, onesided, …) | Computes alternative hypothesis values of the \(\Delta\) log-likelihood test statistic using the asimov dataset.
  `qobs`(self, poinull[, onesided, …]) | Computes observed values of the \(\Delta\) log-likelihood test statistic.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values

  `asimov_dataset`(self, poi) → Tuple[numpy.ndarray, numpy.ndarray]

    Gets the Asimov dataset for a given alternative hypothesis.

    Args:

      - poi (POI): parameter of interest of the alternative hypothesis

    Returns:

      Dataset

    Example with zfit:

          >>> poialt = POI(mean, 1.2)
          >>> dataset = calc.asimov_dataset(poialt)

  `asimov_loss`(self, poi)

    Constructs a loss function using the Asimov dataset for a given alternative hypothesis.

    Args:

      - poi (POI): parameter of interest of the alternative hypothesis

    Returns:

      Loss function

    Example with zfit:

          >>> poialt = POI(mean, 1.2)
          >>> loss = calc.asimov_loss(poialt)

  `asimov_nll`(self, pois, poialt) → numpy.ndarray

    Computes negative log-likelihood values for given parameters of interest using the Asimov dataset generated with a given alternative hypothesis.

    Args:

      - pois (POIarray): parameters of interest

      - poialt (POI): parameter of interest of the alternative hypothesis

    Returns:

      numpy.array: alternative nll values

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, 1.2)
          >>> nll = calc.asimov_nll(poinull, poialt)

  static `check_pois`(pois)

    Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.

  `palt`(self, qobs, qalt, onesided=True, onesideddiscovery=False, qtilde=False) → numpy.ndarray

    Computes the pvalue for the alternative hypothesis.

    Args:

      - qobs (np.array): observed values of the test-statistic q

      - qalt (np.array): alternative values of the test-statistic q using the Asimov dataset

      - onesided (bool, optional): if True (default) computes onesided pvalues

      - onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery

      - qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

    Returns:

      numpy.array : array of the pvalues for the alternative hypothesis

  `pnull`(self, qobs, qalt=None, onesided=True, onesideddiscovery=False, qtilde=False, nsigma=0) → numpy.ndarray

    Computes the pvalue for the null hypothesis.

    Args:

      - qobs (numpy.array): observed values of the test-statistic q

      - qalt (numpy.array): alternative values of the test-statistic q using the asimov dataset

      - onesided (bool, optional): if True (default) computes onesided pvalues

      - onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery

      - qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

      - nsigma (float, optional): significance shift

    Returns:

      np.array : array of the pvalues for the null hypothesis

  `qalt`(self, poinull, poialt, onesided, onesideddiscovery) → numpy.ndarray

    Computes alternative hypothesis values of the \(\Delta\) log-likelihood test statistic using the asimov dataset.

    Args:

      - poinull (POIarray): parameters of interest for the null hypothesis

      - poialt (POIarray): parameters of interest for the alternative hypothesis

      - onesided (bool, optional): if True (default) computes onesided pvalues

      - onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery test

    Returns:

      numpy.array: observed values of q

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POI(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, [1.2])
          >>> q = calc.qalt([poinull], [poialt])

`hepstats.hypotests.calculators.asymptotic_calculator.` `generate_asimov_hist`(model, params, nbins=100)

  Generate the Asimov histogram using a model and dictionary of parameters.

  Args:

    - model : model used to generate the dataset

    - params (Dict) : values of the parameters of the models

    - nbins (int, optional) : number of bins

  Returns:

    (numpy.array, numpy.array) : hist, bin_edges

  Example with zfit:

        >>> obs = zfit.Space('x', limits=(0.1, 2.0))
        >>> mean = zfit.Parameter("mu", 1.2)
        >>> sigma = zfit.Parameter("sigma", 0.1)
        >>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
        >>> hist, bin_edges = generate_asimov_hist(model, {"mean": 1.2, "sigma": 0.1})

#### Frequentist

class `hepstats.hypotests.calculators.frequentist_calculator.` `FrequentistCalculator`(input, minimizer, ntoysnull=100, ntoysalt=100, sampler=<function base_sampler>, sample=<function base_sample>)

  Bases: `hepstats.hypotests.calculators.basecalculator.ToysCalculator`

  Frequentist calculator class.

  Args:

    - input : loss or fit result

    - minimizer : minimizer to use to find the minimum of the loss function

    - ntoysnull (int, default=100): minimum number of toys to generate for the null hypothesis

    - ntoysalt (int, default=100): minimum number of toys to generate for the alternative hypothesis

    - sampler : function used to create sampler with models, number of events and floating parameters in the sample. Default is hepstats.fitutils.sampling.base_sampler.

    - sample : function used to get samples from the sampler. Default is hepstats.fitutils.sampling.base_sample.

  Example with zfit:

        >>> import zfit
        >>> from zfit.core.loss import UnbinnedNLL
        >>> from zfit.minimize import MinuitMinimizer

        >>> obs = zfit.Space('x', limits=(0.1, 2.0))
        >>> data = zfit.data.Data.from_numpy(obs=obs, array=np.random.normal(1.2, 0.1, 10000))
        >>> mean = zfit.Parameter("mu", 1.2)
        >>> sigma = zfit.Parameter("sigma", 0.1)
        >>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
        >>> loss = UnbinnedNLL(model=[model], data=[data], fit_range=[obs])

        >>> calc = FrequentistCalculator(input=loss, minimizer=MinuitMinimizer(), ntoysnull=1000, ntoysalt=1000)

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

    `ntoysalt`

      Returns the number of toys generated for the alternative hypothesis.

    `ntoysnull`

      Returns the number of toys generated for the null hypothesis.

  Methods

  `add_toyresult`(self, toy) | Add ToyResult to the manager.
  `check_pois`(pois) | Checks if the parameters of interest are all hepstats.parameters.POI/POIarray instances.
  `check_pois_compatibility`(poi1, poi2) | Checks compatibility between two lists of hepstats.parameters.POIarray instances.
  `expected_poi`(self, poinull, poialt, nsigma) | Computes the expected parameter of interest values such that the expected p_values = \(lpha\) for different values of \(\sigma\) (0=expected/median)
  `expected_pvalue`(self, poinull, poialt, nsigma) | Computes the expected pvalues and error bands for different values of \(\sigma\) (0=expected/median)
  `from_yaml`(filename, loss, minimizer[, …]) | ToysCalculator constructor with the toys loaded from a yaml file.
  `generate_and_fit_toys`(self, ntoys, poigen, …) | Generate and fit toys for at a given POI (poigen).
  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `get_toyresult`(self, poigen, poieval) | Getter function.
  `get_toys_alt`(self, poigen, poieval[, qtilde]) | Return the generated toys for the alternative hypothesis.
  `get_toys_null`(self, poigen, poieval[, qtilde]) | Return the generated toys for the null hypothesis.
  `keys`(self) | Returns keys of the ToysManager instance defined as key = (toy.poigen, toy.poieval) for a given ToyResult instance toy.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `ntoys`(self, poigen, poieval) | Return the number of toys generated from given value of a POI, and scanned/evaluated for given values_equal of the same POI.
  `obs_nll`(self, pois) | Compute observed negative log-likelihood values for given parameters of interest.
  `pvalue`(self, poinull, poialt, NoneType] = None) | Computes pvalues for the null and alternative hypothesis.
  `q`(self, nll1, nll2, poi1, poi2[, onesided, …]) | Compute values of the test statistic q defined as the difference between negative log-likelihood values \(q = nll1 - nll2\).
  `qalt`(self, poinull, poialt, onesided, …[, …]) | Computes alternative hypothesis values of the \(\Delta\) log-likelihood test statistic.
  `qnull`(self, poinull, poialt, onesided, …) | Computes null hypothesis values of the \(\Delta\) log-likelihood test statistic.
  `qobs`(self, poinull[, onesided, …]) | Computes observed values of the \(\Delta\) log-likelihood test statistic.
  `sample`(self, sampler, ntoys[, poi]) | Returns the samples generated from the sampler for a given value of a parameter of interest
  `sampler`(self[, floating_params]) | Create sampler with models.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values
  `to_yaml`(self, filename) | Save the toys into a yaml file under the key toys.
  `toyresults_to_dict`(self) | Returns a list of all the toy results converted into dictionnaries
  `toys_loss`(self, parameter_name) | Construct a loss function constructed with a sampler for a given floating parameter
  `toysresults_from_yaml`(self, filename) | Extract toy results from a yaml file.
  `values`(self) | Returns values of ToysManager instance that are ToyResult instances.

  `qalt`(self, poinull, poialt, onesided, onesideddiscovery, qtilde=False)

    Computes alternative hypothesis values of the \(\Delta\) log-likelihood test statistic.

    Args:

      - poinull (POIarray): parameters of interest for the null hypothesis

      - poialt (POIarray): parameters of interest for the alternative hypothesis

      - onesided (bool): if True computes onesided pvalues

      - onesideddiscovery (bool, optional): if True (default) computes onesided pvalues for a discovery test

      - ** qtilde** (bool): if True use the \(\widetilde{q}\) test statistics else use the \(q\) test statistic

    Returns:

      numpy.array: observed values of q

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, 1.2)
          >>> q = calc.qalt(poinull, poialt)

  `qnull`(self, poinull, poialt, onesided, onesideddiscovery, qtilde=False)

    Computes null hypothesis values of the \(\Delta\) log-likelihood test statistic.

    Args:

      - poinull (POIarray): parameters of interest for the null hypothesis

      - poialt (POIarray): parameters of interest for the alternative hypothesis

      - onesided (bool): if True computes onesided pvalues

      - onesideddiscovery (bool): if True computes onesided pvalues for a discovery test

      - qtilde (bool): if True use the \(\widetilde{q}\) test statistics else use the \(q\) test statistic

    Returns:

      numpy.array: observed values of q

    Example with zfit:

          >>> mean = zfit.Parameter("mu", 1.2)
          >>> poinull = POIarray(mean, [1.1, 1.2, 1.0])
          >>> poialt = POI(mean, 1.2)
          >>> q = calc.qnull(poinull, poialt)

### Discovery test

class `hepstats.hypotests.core.discovery.` `Discovery`(calculator, poinull)

  Bases: `hepstats.hypotests.core.basetest.BaseTest`

  Class for discovery test.

  Args:

    - calculator (sktats.hypotests.BaseCalculator): calculator to use for computing the pvalues

    - poinull (POI): parameter of interest for the null hypothesis

  Example with zfit:

        >>> import zfit
        >>> from zfit.loss import ExtendedUnbinnedNLL
        >>> from zfit.minimize import Minuit

        >>> bounds = (0.1, 3.0)
        >>> zfit.Space('x', limits=bounds)

        >>> bkg = np.random.exponential(0.5, 300)
        >>> peak = np.random.normal(1.2, 0.1, 25)
        >>> data = np.concatenate((bkg, peak))
        >>> data = data[(data > bounds[0]) & (data < bounds[1])]
        >>> N = data.size
        >>> data = zfit.data.Data.from_numpy(obs=obs, array=data)

        >>> lambda_ = zfit.Parameter("lambda", -2.0, -4.0, -1.0)
        >>> Nsig = zfit.Parameter("Ns", 20., -20., N)
        >>> Nbkg = zfit.Parameter("Nbkg", N, 0., N*1.1)
        >>> signal = Nsig * zfit.pdf.Gauss(obs=obs, mu=1.2, sigma=0.1)
        >>> background = Nbkg * zfit.pdf.Exponential(obs=obs, lambda_=lambda_)
        >>> loss = ExtendedUnbinnedNLL(model=signal + background, data=data)

        >>> from hepstats.hypotests.calculators import AsymptoticCalculator
        >>> from hepstats.hypotests import Discovery
        >>> from hepstats.hypotests.parameters import POI

        >>> calculator = AsymptoticCalculator(loss, Minuit())
        >>> poinull = POI(Nsig, 0)
        >>> discovery_test = Discovery(calculator, poinull)
        >>> discovery_test.result()
        p_value for the Null hypothesis = 0.0007571045424956679
        Significance (in units of sigma) = 3.1719464825102244

  Attributes
    `calculator`

      Returns the calculator.

    `poialt`

      Returns the POI for the alternative hypothesis.

    `poinull`

      Returns the POI for the null hypothesis.

  Methods

  `result`(self[, printlevel]) | Returns the result of the discovery hypothesis test.

  `result`(self, printlevel=1)

    Returns the result of the discovery hypothesis test.

    > Args:

    >   - printlevel (int, default=1): if > 0 print the result

    > Returns:

    >   Tuple(float, float): pnull, significance

### Upper limit

class `hepstats.hypotests.core.upperlimit.` `UpperLimit`(calculator, poinull, poialt, qtilde=False)

  Bases: `hepstats.hypotests.core.basetest.BaseTest`

  Class for upper limit calculation.

  Args:

    - calculator (sktats.hypotests.BaseCalculator): calculator to use for computing the pvalues

    - poinull (List[hypotests.POI]): parameters of interest for the null hypothesis

    - poialt (List[hypotests.POI]): parameters of interest for the alternative hypothesis

    - qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

  Example with zfit:

        >>> import numpy as np
        >>> import zfit
        >>> from zfit.loss import ExtendedUnbinnedNLL
        >>> from zfit.minimize import Minuit

        >>> bounds = (0.1, 3.0)
        >>> zfit.Space('x', limits=bounds)

        >>> bkg = np.random.exponential(0.5, 300)
        >>> peak = np.random.normal(1.2, 0.1, 10)
        >>> data = np.concatenate((bkg, peak))
        >>> data = data[(data > bounds[0]) & (data < bounds[1])]
        >>> N = data.size
        >>> data = zfit.data.Data.from_numpy(obs=obs, array=data)

        >>> lambda_ = zfit.Parameter("lambda", -2.0, -4.0, -1.0)
        >>> Nsig = zfit.Parameter("Ns", 20., -20., N)
        >>> Nbkg = zfit.Parameter("Nbkg", N, 0., N*1.1)
        >>> signal = Nsig * zfit.pdf.Gauss(obs=obs, mu=1.2, sigma=0.1)
        >>> background = Nbkg * zfit.pdf.Exponential(obs=obs, lambda_=lambda_)
        >>> loss = ExtendedUnbinnedNLL(model=signal + background, data=data)

        >>> from hepstats.hypotests.calculators import AsymptoticCalculator
        >>> from hepstats.hypotests import UpperLimit
        >>> from hepstats.hypotests.parameters import POI, POIarray

        >>> calculator = AsymptoticCalculator(loss, Minuit())
        >>> poinull = POIarray(Nsig, np.linspace(0.0, 25, 20))
        >>> poialt = POI(Nsig, 0)
        >>> ul = UpperLimit(calculator, poinull, poialt)
        >>> ul.upperlimit(alpha=0.05, CLs=True)
        Observed upper limit: Nsig = 15.725784747406346
        Expected upper limit: Nsig = 11.927442041887158
        Expected upper limit +1 sigma: Nsig = 16.596396280677116
        Expected upper limit -1 sigma: Nsig = 8.592750403611896
        Expected upper limit +2 sigma: Nsig = 22.24864429383046
        Expected upper limit -2 sigma: Nsig = 6.400549971360598

  Attributes
    `calculator`

      Returns the calculator.

    `poialt`

      Returns the POI for the alternative hypothesis.

    `poinull`

      Returns the POI for the null hypothesis.

    `qtilde`

      Returns True if qtilde test statistic is used, else False.

  Methods

  `pvalues`(self[, CLs]) | Returns p-values scanned for the values of the parameters of interest in the null hypothesis.
  `upperlimit`(self[, alpha, CLs, printlevel]) | Returns the upper limit of the parameter of interest.

  `pvalues`(self, CLs=True)

    Returns p-values scanned for the values of the parameters of interest in the null hypothesis.

    Args:

      - CLs (bool, optional): if True uses pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\)

    Returns:

      pvalues (Dict): CLsb, CLs, expected (+/- sigma bands) p-values

  property `qtilde`

    Returns True if qtilde test statistic is used, else False.

  `upperlimit`(self, alpha=0.05, CLs=True, printlevel=1)

    Returns the upper limit of the parameter of interest.

    Args:

      - alpha (float, default=0.05): significance level

      - CLs (bool, optional): if True uses pvalues as \(p_{cls}=p_{null}/p_{alt}=p_{clsb}/p_{clb}\) else as \(p_{clsb} = p_{null}\)

      - printlevel (int, default=1): if > 0 print the result

    Returns:

      limits (Dict): observed, expected (+/- sigma bands) upper limits

### Confidence interval

class `hepstats.hypotests.core.confidence_interval.` `ConfidenceInterval`(calculator, poinull, qtilde=False)

  Bases: `hepstats.hypotests.core.basetest.BaseTest`

  Class for confidence interval calculation.

  Args:

    - calculator (sktats.hypotests.BaseCalculator): calculator to use for computing the pvalues

    - poinull (POIarray): parameters of interest for the null hypothesis

    - qtilde (bool, optional): if True use the \(\widetilde{q}\) test statistics else (default) use the \(q\) test statistic

  Example with zfit:

        >>> import numpy as np
        >>> import zfit
        >>> from zfit.loss import ExtendedUnbinnedNLL
        >>> from zfit.minimize import Minuit

        >>> bounds = (0.1, 3.0)
        >>> zfit.Space('x', limits=bounds)

        >>> bkg = np.random.exponential(0.5, 300)
        >>> peak = np.random.normal(1.2, 0.1, 80)
        >>> data = np.concatenate((bkg, peak))
        >>> data = data[(data > bounds[0]) & (data < bounds[1])]
        >>> N = data.size
        >>> data = zfit.data.Data.from_numpy(obs=obs, array=data)

        >>> mean = zfit.Parameter("mean", 1.2, 0.5, 2.0)
        >>> sigma = zfit.Parameter("sigma", 0.1, 0.02, 0.2)
        >>> lambda_ = zfit.Parameter("lambda", -2.0, -4.0, -1.0)
        >>> Nsig = zfit.Parameter("Ns", 20., -20., N)
        >>> Nbkg = zfit.Parameter("Nbkg", N, 0., N*1.1)
        >>> signal = Nsig * zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
        >>> background = Nbkg * zfit.pdf.Exponential(obs=obs, lambda_=lambda_)
        >>> loss = ExtendedUnbinnedNLL(model=signal + background, data=data)

        >>> from hepstats.hypotests.calculators import AsymptoticCalculator
        >>> from hepstats.hypotests import ConfidenceInterval
        >>> from hepstats.hypotests.parameters import POI, POIarray

        >>> calculator = AsymptoticCalculator(loss, Minuit())
        >>> poinull = POIarray(mean, np.linspace(1.15, 1.26, 100))
        >>> ci = ConfidenceInterval(calculator, poinull)
        >>> ci.interval()
        Confidence interval on mean:
            1.1810371356602791 < mean < 1.2156701172321935 at 68.0% C.L.

  Attributes
    `calculator`

      Returns the calculator.

    `poialt`

      Returns the POI for the alternative hypothesis.

    `poinull`

      Returns the POI for the null hypothesis.

    `qtilde`

      Returns True if qtilde test statistic is used, else False.

  Methods

  `interval`(self[, alpha, printlevel]) | Returns the confidence level on the parameter of interest.
  `pvalues`(self) | Returns p-values scanned for the values of the parameters of interest in the null hypothesis.

  `interval`(self, alpha=0.32, printlevel=1)

    Returns the confidence level on the parameter of interest.

    Args:

      - alpha (float, default=0.32/1 sigma): significance level,

      - printlevel (int, default=1): if > 0 print the result

    Returns:

      limits (Dict): central, upper and lower bounds on the parameter of interest

  `pvalues`(self)

    Returns p-values scanned for the values of the parameters of interest in the null hypothesis.

    Returns:

      pvalues (np.array): CLsb, CLs, expected (+/- sigma bands) p-values

  property `qtilde`

    Returns True if qtilde test statistic is used, else False.

### Hypotests objects

class `hepstats.hypotests.hypotests_object.` `HypotestsObject`(input, minimizer)

  Bases: `object`

  Base object in hepstats.hypotests to manipulate a loss function and a minimizer.

  Args:

    - input : loss or fit result

    - minimizer : minimizer to use to find the minimum of the loss function

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

  Methods

  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values

  property `bestfit`

    Returns the best fit values of the model parameters.

  property `constraints`

    Returns the constraints on the loss / likehood function.

  property `data`

    Returns the data.

  `get_parameter`(self, name)

    Returns the parameter in loss function with given input name.

    Args:

      name (str): name of the parameter to return

  property `loss`

    Returns the loss / likelihood function.

  `lossbuilder`(self, model, data, weights=None)

    Method to build a new loss function.

    Args:

      - model (List): The model or models to evaluate the data on

      - data (List): Data to use

      - weights (optional, List): the data weights

    Example with zfit:

          >>> data = zfit.data.Data.from_numpy(obs=obs, array=np.random.normal(1.2, 0.1, 10000))
          >>> mean = zfit.Parameter("mu", 1.2)
          >>> sigma = zfit.Parameter("sigma", 0.1)
          >>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
          >>> loss = calc.lossbuilder(model, data)

    Returns:

      Loss function

  property `minimizer`

    Returns the minimizer.

  property `model`

    Returns the model.

  `set_params_to_bestfit`(self)

    Set the values of the parameters in the models to the best fit values

class `hepstats.hypotests.hypotests_object.` `ToysObject`(input, minimizer, sampler, sample)

  Bases: `hepstats.hypotests.hypotests_object.HypotestsObject`

  Base object in hepstats.hypotests to manipulate a loss function, a minimizer and sample a model (within the loss function) to do toy experiments.

  > Args:

  >   - input : loss or fit result

  >   - minimizer : minimizer to use to find the minimum of the loss function

  >   - sampler : function used to create sampler with models, number of events and floating parameters in the sample.

  >   - sample : function used to get samples from the sampler.

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

  Methods

  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `sample`(self, sampler, ntoys[, poi]) | Returns the samples generated from the sampler for a given value of a parameter of interest
  `sampler`(self[, floating_params]) | Create sampler with models.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values
  `toys_loss`(self, parameter_name) | Construct a loss function constructed with a sampler for a given floating parameter

  `sample`(self, sampler, ntoys, poi=None)

    Returns the samples generated from the sampler for a given value of a parameter of interest

    Args:

      - sampler (list): generator of samples

      - ntoys (int): number of samples to generate

      - poi (POI, optional): in the sampler

    Example with zfit:

          >>> mean = zfit.Parameter("mean")
          >>> sampler = calc.sampler(floating_params=[mean])
          >>> sample = calc.sample(sampler, 1000, POI(mean, 1.2))

  `sampler`(self, floating_params=None)

    Create sampler with models.

    Args:

      - floating_params (list): floating parameters in the sampler

    Example with zfit:

          >>> sampler = calc.sampler(floating_params=[zfit.Parameter("mean")])

  `toys_loss`(self, parameter_name)

    Construct a loss function constructed with a sampler for a given floating parameter

    Args:

      - parameter_name: name floating parameter in the sampler

    Returns:

      Loss function

    Example with zfit:

          >>> loss = calc.toys_loss(zfit.Parameter("mean"))

### Toy utilities

class `hepstats.hypotests.hypotests_object.` `HypotestsObject`(input, minimizer)

  Bases: `object`

  Base object in hepstats.hypotests to manipulate a loss function and a minimizer.

  Args:

    - input : loss or fit result

    - minimizer : minimizer to use to find the minimum of the loss function

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

  Methods

  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values

  property `bestfit`

    Returns the best fit values of the model parameters.

  property `constraints`

    Returns the constraints on the loss / likehood function.

  property `data`

    Returns the data.

  `get_parameter`(self, name)

    Returns the parameter in loss function with given input name.

    Args:

      name (str): name of the parameter to return

  property `loss`

    Returns the loss / likelihood function.

  `lossbuilder`(self, model, data, weights=None)

    Method to build a new loss function.

    Args:

      - model (List): The model or models to evaluate the data on

      - data (List): Data to use

      - weights (optional, List): the data weights

    Example with zfit:

          >>> data = zfit.data.Data.from_numpy(obs=obs, array=np.random.normal(1.2, 0.1, 10000))
          >>> mean = zfit.Parameter("mu", 1.2)
          >>> sigma = zfit.Parameter("sigma", 0.1)
          >>> model = zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
          >>> loss = calc.lossbuilder(model, data)

    Returns:

      Loss function

  property `minimizer`

    Returns the minimizer.

  property `model`

    Returns the model.

  `set_params_to_bestfit`(self)

    Set the values of the parameters in the models to the best fit values

class `hepstats.hypotests.hypotests_object.` `ToysObject`(input, minimizer, sampler, sample)

  Bases: `hepstats.hypotests.hypotests_object.HypotestsObject`

  Base object in hepstats.hypotests to manipulate a loss function, a minimizer and sample a model (within the loss function) to do toy experiments.

  > Args:

  >   - input : loss or fit result

  >   - minimizer : minimizer to use to find the minimum of the loss function

  >   - sampler : function used to create sampler with models, number of events and floating parameters in the sample.

  >   - sample : function used to get samples from the sampler.

  Attributes
    `bestfit`

      Returns the best fit values of the model parameters.

    `constraints`

      Returns the constraints on the loss / likehood function.

    `data`

      Returns the data.

    `loss`

      Returns the loss / likelihood function.

    `minimizer`

      Returns the minimizer.

    `model`

      Returns the model.

  Methods

  `get_parameter`(self, name) | Returns the parameter in loss function with given input name.
  `lossbuilder`(self, model, data[, weights]) | Method to build a new loss function.
  `sample`(self, sampler, ntoys[, poi]) | Returns the samples generated from the sampler for a given value of a parameter of interest
  `sampler`(self[, floating_params]) | Create sampler with models.
  `set_params_to_bestfit`(self) | Set the values of the parameters in the models to the best fit values
  `toys_loss`(self, parameter_name) | Construct a loss function constructed with a sampler for a given floating parameter

  `sample`(self, sampler, ntoys, poi=None)

    Returns the samples generated from the sampler for a given value of a parameter of interest

    Args:

      - sampler (list): generator of samples

      - ntoys (int): number of samples to generate

      - poi (POI, optional): in the sampler

    Example with zfit:

          >>> mean = zfit.Parameter("mean")
          >>> sampler = calc.sampler(floating_params=[mean])
          >>> sample = calc.sample(sampler, 1000, POI(mean, 1.2))

  `sampler`(self, floating_params=None)

    Create sampler with models.

    Args:

      - floating_params (list): floating parameters in the sampler

    Example with zfit:

          >>> sampler = calc.sampler(floating_params=[zfit.Parameter("mean")])

  `toys_loss`(self, parameter_name)

    Construct a loss function constructed with a sampler for a given floating parameter

    Args:

      - parameter_name: name floating parameter in the sampler

    Returns:

      Loss function

    Example with zfit:

          >>> loss = calc.toys_loss(zfit.Parameter("mean"))

## hepstats.splot module

Module implementing the sPlot algorithm, see [PLD05].

### sWeights

`hepstats.splot.sweights.` `compute_sweights`(model, x)

  Computes sWeights from probability density functions for different components/species in a fit model (for instance signal and background) fitted on some data x.

  > i.e. model = Nsig * pdf_signal + Nbkg * pdf_bkg

  > Args:

  >   - model: sum of extended pdfs.

  >   - x (np.array): data on which model is fitted

  > Returns:

  >   - dict(`yield, np.array)`: dictionary with yield parameters as keys, and sWeights for correspoind species as values.

  > Example with zfit:

  >       >>> import numpy as np
  >       >>> import zfit
  >       >>> from zfit.loss import ExtendedUnbinnedNLL
  >       >>> from zfit.minimize import Minuit

  >       >>> bounds = (0.0, 3.0)
  >       >>> nbkg = 10000
  >       >>> nsig = 5000
  >       >>> zfit.Space('x', limits=bounds)

  >       >>> bkg = np.random.exponential(0.5, nbkg)
  >       >>> peak = np.random.normal(1.2, 0.1, nsig)
  >       >>> data = np.concatenate((bkg, peak))
  >       >>> data = data[(data > bounds[0]) & (data < bounds[1])]
  >       >>> N = data.size
  >       >>> data = zfit.data.Data.from_numpy(obs=obs, array=data)

  >       >>> mean = zfit.Parameter("mean", 1.2, 0.5, 2.0)
  >       >>> sigma = zfit.Parameter("sigma", 0.1, 0.02, 0.2)
  >       >>> lambda_ = zfit.Parameter("lambda", -2.0, -4.0, -1.0)
  >       >>> Nsig = zfit.Parameter("Nsig", nsig, 0., N)
  >       >>> Nbkg = zfit.Parameter("Nbkg", nbkg, 0., N)
  >       >>> signal = Nsig * zfit.pdf.Gauss(obs=obs, mu=mean, sigma=sigma)
  >       >>> background = Nbkg * zfit.pdf.Exponential(obs=obs, lambda_=lambda_)
  >       >>> loss = ExtendedUnbinnedNLL(model=signal + background, data=data)
  >       >>> minimizer = Minuit()
  >       >>> minimum = minimizer.minimize(loss)

  >       >>> from hepstats.splot import compute_sweights

  >       >>> sweights = compute_sweights(tot_model, data)

`hepstats.splot.sweights.` `is_sum_of_extended_pdfs`(model)