HistogramPDF#

class zfit.pdf.HistogramPDF(data, extended=None, norm=None, name='HistogramPDF', label=None)[source]#

Bases: BaseBinnedPDF

Binned PDF resembling a histogram.

Simple histogram PDF that can be used to model a histogram as a PDF.

Parameters:

  • data (Union[PlottableHistogram, Iterable[PlottableHistogram]]) – Histogram to be used as PDF.

  • extended (Union[bool, TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter]), None]) – ​The overall yield of the PDF. If this is parameter-like, it will be used as the yield, the expected number of events, and the PDF will be extended. An extended PDF has additional functionality, such as the ext_* methods and the counts (for binned PDFs).​​If True, the PDF will be extended automatically if the PDF is extended using the total number of events in the histogram. This is the default.​

  • norm (Optional[Space]) – ​Normalization of the PDF. By default, this is the same as the default space of the PDF.​

  • name (str) – ​Name of the PDF. Maybe has implications on the serialization and deserialization of the PDF. For a human-readable name, use the label.​

  • label (str | None) – ​Human-readable name or label of the PDF for a better description, to be used with plots etc. Has no programmatical functional purpose as identification.​

add_cache_deps(cache_deps, allow_non_cachable=True)#

Add dependencies that render the cache invalid if they change.

Parameters:

  • cache_deps

  • allow_non_cachable – If True, allow cache_dependents to be non-cachables. If False, any cache_dependents that is not a ZfitGraphCachable will raise an error.

Raises:

TypeError – if one of the cache_dependents is not a ZfitGraphCachable _and_ allow_non_cachable if False.

counts(x=None, norm=None, *, params=None)#

Calculate the number of events in each bin.

This is the integrals of the PDF in each bin.

Parameters:

  • x (Union[PlottableHistogram, Iterable[PlottableHistogram]]) – ​Data for the binned PDF. The returned counts correspond to the binned axis in x.​

  • norm (Optional[Space]) – ​Normalization of the counts. This normalizes the counts so that the actual sum of all counts is equal to the yield.​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

A histogram with the number of events in each bin.

Return type:

ZfitBinnedData

create_sampler(n=None, limits=None, *, params=None, fixed_params=True)#

Create a SamplerData that acts as Data but can be resampled, also with changed parameters and n.

If limits is not specified, space is used (if the space contains limits). If n is None and the model is an extended pdf, ‘extended’ is used by default.

Parameters:

  • n (Union[int, Tensor, str]) –

    The number of samples to be generated. Can be a Tensor that will be or a valid string. Currently implemented:

    • ’extended’: samples poisson(yield) from each pdf that is extended.

  • limits (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – From which space to sample.

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

  • fixed_params (bool | list[ZfitParameter] | tuple[ZfitParameter]) – A list of Parameters that will be fixed during several resample calls. If True, all are fixed, if False, all are floating. If a Parameter is not fixed and its value gets updated (e.g. by a Parameter.set_value() call), this will be reflected in resample. If fixed, the Parameter will still have the same value as the SamplerData has been created with when it resamples.

Return type:

BinnedSamplerData

Returns:

BinnedSampler

Raises:

  • NotExtendedPDFError – if ‘extended’ is chosen (implicitly by default or explicitly) as an option for n but the pdf itself is not extended.

  • ValueError – if n is an invalid string option.

  • InvalidArgumentError – if n is not specified and pdf is not extended.

property dtype: DType#

The dtype of the object.

ext_integrate(limits, norm=None, *, options=None, params=None)#

Extended integral of the PDF, i.e. the expected counts or the integral scaled by the yield.

Parameters:

  • limits (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Limits of the integration.​

  • norm (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Normalization of the integration. By default, this is the same as the default space of the PDF. False means no normalization and returns the unnormed integral.​

  • options –

    ​Options for the integration. Additional options for the integration. Currently supported options are:

    • type: one of (bins) This hints that bins are integrated. A method that is vectorizable, non-dynamic and therefore less suitable for complicated functions is chosen.

    Other options may be available in the future.​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Return type:

Union[float, Tensor]

Returns:

Scalar integration value.

ext_log_pdf(x, norm=None, *, params=None)#

Log probability density function scaled by yield, evaluated at x or in the bins of x

Parameters:

  • x (Union[float, Tensor]) – ​Values to evaluate the PDF at. If this is a ZfitBinnedData-like object, a histogram of densities will be returned. If x is a ZfitUnbinnedData-like object, the densities will be evaluated at the points of x.​

  • norm (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Normalization of the function. By default, this is the norm of the PDF (which by default is the same as the space of the PDF).​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

binnedpdf.out.problike| If the input was unbinned, it returns an array

of shape (nevents,). If the input was binned, the dimensions and ordering of the axes corresponds to the input axes.​

Return type:

|@doc

ext_normalization(norm, *, options=None, params=None)#

Calculate the normalization of the extended PDF, for a binned PDF this is the sum of the counts.

Parameters:

  • norm (Optional[Space]) – |@doc:pdf.normalization.norm| Normalization of the function. By default, this is the norm of the PDF (which by default is the same as the space of the PDF). |@docend:pdf.normalization.norm|

  • options –

    |@doc:pdf.normalization.options| Additional options for the normalization. Currently supported options are: - type: one of (bins)

    This hints that bins are integrated. A method that is vectorizable, non-dynamic and therefore less suitable for complicated functions is chosen. |@docend:pdf.normalization.options|

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

The normalization of the extended PDF.

Return type:

Scalar-like

ext_pdf(x, norm=None, *, params=None)#

Probability density function scaled by yield, evaluated at x or in the bins of x

Parameters:

  • x (Union[float, Tensor]) – ​Values to evaluate the PDF at. If this is a ZfitBinnedData-like object, a histogram of densities will be returned. If x is a ZfitUnbinnedData-like object, the densities will be evaluated at the points of x.​

  • norm (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Normalization of the function. By default, this is the norm of the PDF (which by default is the same as the space of the PDF).​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

binnedpdf.out.problike| If the input was unbinned, it returns an array

of shape (nevents,). If the input was binned, the dimensions and ordering of the axes corresponds to the input axes.​

Return type:

|@doc

get_params(floating=True, is_yield=None, extract_independent=True, *, autograd=None)#

Recursively collect parameters that this object depends on according to the filter criteria.

Which parameters should be included can be steered using the arguments as a filter.
  • None: do not filter on this. E.g. floating=None will return parameters that are floating as well as

    parameters that are fixed.

  • True: only return parameters that fulfil this criterion

  • False: only return parameters that do not fulfil this criterion. E.g. floating=False will return

    only parameters that are not floating.

Parameters:

  • floating (bool | None) – if a parameter is floating, e.g. if floating() returns True

  • is_yield (bool | None) – if a parameter is a yield of the _current_ model. This won’t be applied recursively, but may include yields if they do also represent a parameter parametrizing the shape. So if the yield of the current model depends on other yields (or also non-yields), this will be included. If, however, just submodels depend on a yield (as their yield) and it is not correlated to the output of our model, they won’t be included.

  • extract_independent (bool | None) – If the parameter is an independent parameter, i.e. if it is a ZfitIndependentParameter.

Return type:

set[ZfitParameter]

integrate(limits, norm=None, *, options=None, params=None)#

Integral of the PDF, the sum over all the bins normalized to the total integral.

Parameters:

  • limits (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Limits of the integration.​

  • norm (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Normalization of the integration. By default, this is the same as the default space of the PDF. False means no normalization and returns the unnormed integral.​

  • options –

    ​Options for the integration. Additional options for the integration. Currently supported options are:

    • type: one of (bins) This hints that bins are integrated. A method that is vectorizable, non-dynamic and therefore less suitable for complicated functions is chosen.

    Other options may be available in the future.​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Return type:

Union[float, Tensor]

Returns:

Scalar integration value.

log_normalization(norm, *, params=None, options=None, limits=None)#

Normalization of the PDF. For a binned PDF, this is the sum over the counts or the integral over the density. (deprecated arguments)

Deprecated: SOME ARGUMENTS ARE DEPRECATED: (limits). They will be removed in a future version. Instructions for updating: Use norm instead.

Parameters:

  • norm – |@doc:pdf.normalization.norm| Normalization of the function. By default, this is the norm of the PDF (which by default is the same as the space of the PDF). |@docend:pdf.normalization.norm|

  • options –

    |@doc:pdf.normalization.options| Additional options for the normalization. Currently supported options are: - type: one of (bins)

    This hints that bins are integrated. A method that is vectorizable, non-dynamic and therefore less suitable for complicated functions is chosen. |@docend:pdf.normalization.options|

  • params – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Return type:

Union[Tensor, array]

Returns:

log_pdf(x, norm=None, *, params=None)#

Log probability density function, evaluated at x or in the bins of x

Parameters:

  • x (Union[float, Tensor]) – ​Values to evaluate the PDF at. If this is a ZfitBinnedData-like object, a histogram of densities will be returned. If x is a ZfitUnbinnedData-like object, the densities will be evaluated at the points of x.​

  • norm (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Normalization of the function. By default, this is the norm of the PDF (which by default is the same as the space of the PDF).​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

binnedpdf.out.problike| If the input was unbinned, it returns an array

of shape (nevents,). If the input was binned, the dimensions and ordering of the axes corresponds to the input axes.​

Return type:

|@doc

property name: str#

The name of the object.

normalization(norm=None, *, params=None, options=None, limits=None)#

Normalization of the PDF. For a binned PDF, this is the sum over the counts or the integral over the density.

Parameters:

  • norm – |@doc:pdf.normalization.norm| Normalization of the function. By default, this is the norm of the PDF (which by default is the same as the space of the PDF). |@docend:pdf.normalization.norm|

  • options –

    |@doc:pdf.normalization.options| Additional options for the normalization. Currently supported options are: - type: one of (bins)

    This hints that bins are integrated. A method that is vectorizable, non-dynamic and therefore less suitable for complicated functions is chosen. |@docend:pdf.normalization.options|

  • params – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Return type:

Union[Tensor, array]

Returns:

pdf(x, norm=None, *, params=None)#

Probability density function, evaluated at x or in the bins of x

Parameters:

  • x (Union[float, Tensor]) – ​Values to evaluate the PDF at. If this is a ZfitBinnedData-like object, a histogram of densities will be returned. If x is a ZfitUnbinnedData-like object, the densities will be evaluated at the points of x.​

  • norm (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Normalization of the function. By default, this is the norm of the PDF (which by default is the same as the space of the PDF).​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

probability density

Return type:

Array-like

register_cacher(cacher)#

Register a cacher that caches values produces by this instance; a dependent.

Parameters:

cacher

rel_counts(x=None, *, norm=None, params=None)#

Calculate the relative number of events in each bin.

This is the integrals of the PDF in each bin divided by the integral of the PDF over the whole space. It is not equal to the density but rather a histogram scaled to 1.

Parameters:

  • x (Union[PlottableHistogram, Iterable[PlottableHistogram]]) – ​Data for the binned PDF. The returned counts correspond to the binned axis in x.​

  • norm (Optional[Space]) – ​Normalization of the counts. This normalizes the counts so that the actual sum of all counts is equal to the yield.​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

A histogram with the relative number of events in each bin.

Return type:

ZfitBinnedData

reset_cache_self()#

Clear the cache of self and all dependent cachers.

sample(n=None, limits=None, *, params=None)#

Draw a random binned sample from the PDF.

Parameters:

  • n (int | None) – ​Number of samples to draw. For an extended PDF, the argument is optional and will be the poisson-fluctuated expected number of events, i.e. the yield.​

  • limits (Union[tuple[tuple[float, ...]], tuple[float, ...], bool, Space]) – ​Limits of the sampling. By default, this is the same as the default space of the PDF.​

  • params (TypeVar(ParamTypeInput, zfit.core.interfaces.ZfitParameter, Union[int, float, complex, Tensor, zfit.core.interfaces.ZfitParameter])) – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

Sampled dataset

Return type:

ZfitBinnedData

to_binned(space, *, extended=None, norm=None)#

Convert the PDF to a binned PDF, returns self.

For compatibility with unbinned PDFs.

to_binneddata(**kwargs)#

Create an Asimov dataset as BinnedData using either counts (for extended) or rel_counts.

Parameters:

() (**kwargs) – arguments to counts or rel_counts.

Returns:

Binned data representing the Asimov dataset of this PDF.

Return type:

BinnedData

to_hist(**kwargs)#

Create an Asimov histogram as Hist using either counts (for extended) or rel_counts.

Parameters:

() (**kwargs) – arguments to counts or rel_counts.

Returns:

Histogram representing the Asimov dataset of this PDF.

Return type:

hist.Hist

to_unbinned()#

Convert the PDF to an unbinned PDF.

values(*, var=None, params=None)#

Histogram values that are either the counts or the normalized counts.

If the PDF is extended, the counts are returned, otherwise the normalized counts are returned.

Parameters:

params – ​Mapping of the parameter names to the actual values. The parameter names refer to the names of the parameters, typically Parameter, that the model was _initialized_ with, not the name of the models parametrization.​

Returns:

Histogram values

Return type:

ZfitBinnedData