zfit.pdf.
BasePDF
Bases: zfit.core.interfaces.ZfitPDF, zfit.core.basemodel.BaseModel
zfit.core.interfaces.ZfitPDF
zfit.core.basemodel.BaseModel
space
zfit.Space
norm_range
Return the current normalization range. If None and the obs have limits, they are returned.
Union[Space, None, bool]
Union
Space
None
bool
The current normalization range.
set_norm_range
Set the normalization range (temporarily if used with contextmanager).
norm_range (Union[ZfitLimit, Tensor, ndarray, Iterable[float], float, Tuple[float], List[float], bool, None]) –
ZfitLimit
Tensor
ndarray
Iterable
float
Tuple
List
normalization
Return the normalization of the function (usually the integral over limits).
limits (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space]) – The limits on where to normalize over
Union[float, Tensor]
The normalization value
unnormalized_pdf
PDF “unnormalized”. Use functions for unnormalized pdfs. this is only for performance in special cases. (deprecated)
Warning: THIS FUNCTION IS DEPRECATED. It will be removed in a future version. Instructions for updating: Use pdf(norm_range=False) instead
x (Union[float, Tensor]) – The value, have to be convertible to a Tensor
component_norm_range (Union[ZfitLimit, Tensor, ndarray, Iterable[float], float, Tuple[float], List[float], bool, None]) – The normalization range for the components. Needed for
composition (certain) – pdfs.
1-dimensional tf.Tensor containing the unnormalized pdf.
tf.Tensor
ext_pdf
ext_log_pdf
pdf
log_pdf
Log probability density function normalized over norm_range.
x (Union[float, Tensor]) – float or double Tensor.
norm_range (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space, None]) – Space to normalize over
A Tensor of type self.dtype.
gradients
ext_integrate
apply_yield
If a norm_range is given, the value will be multiplied by the yield.
value (Union[float, Tensor]) –
log (bool) –
Numerical
create_extended
Return an extended version of this pdf with yield yield_. The parameters are shared.
yield –
name_addition –
ZfitPDF
set_yield
Make the model extended by setting a yield. If possible, prefer to use create_extended.
This does not alter the general behavior of the PDF. The pdf and integrate and similar methods will continue to return the same - normalized to 1 - values. However, not only can this parameter be accessed via get_yield, the methods ext_pdf and ext_integral provide a version of pdf and integrate respecetively that is multiplied by the yield.
These can be useful for plotting and for binned likelihoods.
() (value) –
is_extended
Flag to tell whether the model is extended or not.
A boolean.
get_yield
Return the yield (only for extended models).
Optional[Parameter]
Optional
Parameter
The yield of the current model or None
create_projection_pdf
Create a PDF projection by integrating out some of the dimensions.
The new projection pdf is still fully dependent on the pdf it was created with.
limits_to_integrate (Union[ZfitLimit, Tensor, ndarray, Iterable[float], float, Tuple[float], List[float], bool, None]) –
A pdf without the dimensions from limits_to_integrate.
copy
Creates a copy of the model.
Note: the copy model may continue to depend on the original initialization arguments.
**override_parameters – String/value dictionary of initialization arguments to override with new value.
of self.parameters and override_parameters, i.e., dict(self.parameters, **override_parameters).
as_func
Return a Function with the function model(x, norm_range=norm_range).
norm_range (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space]) –
add_cache_deps
Add dependencies that render the cache invalid if they change.
cache_deps (Union[ForwardRef, Iterable[ForwardRef]]) –
ForwardRef
allow_non_cachable (bool) – If True, allow cache_dependents to be non-cachables. If False, any cache_dependents that is not a ZfitCachable will raise an error.
TypeError – if one of the cache_dependents is not a ZfitCachable _and_ allow_non_cachable if False.
analytic_integrate
Analytical integration over function and raise Error if not possible.
limits (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space]) – the limits to integrate over
norm_range (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space, None]) – the limits to normalize over
The integral value
AnalyticIntegralNotImplementedError – If no analytical integral is available (for this limits).
NormRangeNotImplementedError – if the norm_range argument is not supported. This means that no analytical normalization is available, explicitly: the analytical integral over the limits = norm_range is not available.
axes
Optional[Tuple[int]]
int
convert_sort_space
Convert the inputs (using eventually obs, axes) to ZfitSpace and sort them according to own obs.
ZfitSpace
obs (Union[str, Iterable[str], Space, ZfitLimit, Tensor, ndarray, Iterable[float], float, Tuple[float], List[float], bool, None]) –
str
axes (Union[int, Iterable[int], None]) –
limits (Union[ZfitLimit, Tensor, ndarray, Iterable[float], float, Tuple[float], List[float], bool, None]) –
Returns:
Optional[ZfitSpace]
create_sampler
Create a Sampler that acts as Data but can be resampled, also with changed parameters and n.
Sampler
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.
n (Union[int, Tensor, str, None]) –
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, None]) – From which space to sample.
fixed_params (Union[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 Sampler has been created with when it resamples.
ZfitParameter
py:class:~`zfit.core.data.Sampler`
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.
dtype
The dtype of the object
DType
get_cache_deps
Return a set of all independent Parameter that this object depends on.
only_floating (bool) – If True, only return floating Parameter
OrderedSet
get_dependencies
DEPRECATED FUNCTION
Warning: THIS FUNCTION IS DEPRECATED. It will be removed in a future version. Instructions for updating: Use get_params instead if you want to retrieve the independent parameters or get_cache_deps in case you need the numerical cache dependents (advanced).
get_params
Recursively collect parameters that this object depends on according to the filter criteria.
parameters that are fixed.
True: only return parameters that fulfil this criterion
only parameters that are not floating.
floating (Optional[bool]) – if a parameter is floating, e.g. if floating() returns True
floating()
is_yield (Optional[bool]) – 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 (Optional[bool]) – If the parameter is an independent parameter, i.e. if it is a ZfitIndependentParameter.
Set[ZfitParameter]
Set
graph_caching_methods
instances
integrate
n_obs
name
The name of the object.
numeric_integrate
Numerical integration over the model.
obs
Optional[Tuple[str, …]]
params
~ParametersType
partial_analytic_integrate
partial_integrate
partial_numeric_integrate
register_additional_repr
Register an additional attribute to add to the repr.
keyword argument. The value has to be gettable from the instance (has to be an (any) –
or callable method of self. (attribute) –
register_analytic_integral
Register an analytic integral with the class.
func (Callable) –
Callable
A function that calculates the (partial) integral over the axes limits. The signature has to be the following:
x (ZfitData, None): the data for the remaining axes in a partialintegral. If it is not a partial integral, this will be None. limits (ZfitSpace): the limits to integrate over. norm_range (ZfitSpace, None): Normalization range of the integral.If not supports_supports_norm_range, this will be None. params (Dict[param_name, zfit.Parameters]): The parameters of the model. model (ZfitModel):The model that is being integrated.
ZfitData
integral. If it is not a partial integral, this will be None.
limits (ZfitSpace): the limits to integrate over.
If not supports_supports_norm_range, this will be None.
params (Dict[param_name, zfit.Parameters]): The parameters of the model.
zfit.Parameters
model (ZfitModel):The model that is being integrated.
ZfitModel
limits (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space, None]) – If a :py:class:~`zfit.Space` is given, it is used as limits. Otherwise arguments to instantiate a Range class can be given as follows.|limits_init|
priority (Union[int, float]) – Priority of the function. If multiple functions cover the same space, the one with the highest priority will be used.
supports_multiple_limits (bool) – If True, the limits given to the integration function can have multiple limits. If False, only simple limits will pass through and multiple limits will be auto-handled.
supports_norm_range (bool) – If True, norm_range argument to the function may not be None. If False, norm_range will always be None and care is taken of the normalization automatically.
register_cacher
Register a cacher that caches values produces by this instance; a dependent.
cacher (Union[ForwardRef, Iterable[ForwardRef]]) –
register_inverse_analytic_integral
Register an inverse analytical integral, the inverse (unnormalized) cdf.
func (Callable) – A function with the signature func(x, params), where x is a Data object and params is a dict.
reset_cache
reset_cache_self
Clear the cache of self and all dependent cachers.
sample
Sample n points within limits from the model.
limits (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space, None]) – In which region to sample in
SampleData
SampleData(n_obs, n_samples)
NotExtendedPDFError – if ‘extended’ is (implicitly by default or explicitly) chosen as an option for n but the pdf itself is not extended.
update_integration_options
Set the integration options.
draws_per_dim – The draws for MC integration to do
mc_sampler –
BaseFunctor
Bases: zfit.models.basefunctor.FunctorMixin, zfit.core.basepdf.BasePDF
zfit.models.basefunctor.FunctorMixin
zfit.core.basepdf.BasePDF
pdfs_extended
get_models
List[ZfitModel]
models
Return the models of this Functor. Can be pdfs or funcs.
Exponential
Bases: zfit.core.basepdf.BasePDF
Exponential function exp(lambda * x).
The function is normalized over a finite range and therefore a pdf. So the PDF is precisely defined as \(\frac{ e^{\lambda \cdot x}}{ \int_{lower}^{upper} e^{\lambda \cdot x} dx}\)
lam – Accessed as parameter “lambda”.
obs (Union[str, Iterable[str], Space, None]) – The Space the pdf is defined in.
name (str) – Name of the pdf.
dtype –
CrystalBall
Crystal Ball shaped PDF. A combination of a Gaussian with a powerlaw tail.
The function is defined as follows:
with
mu (~ParamTypeInput) – The mean of the gaussian
sigma (~ParamTypeInput) – Standard deviation of the gaussian
alpha (~ParamTypeInput) – parameter where to switch from a gaussian to the powertail
n (~ParamTypeInput) – Exponent of the powertail
obs (Union[str, Iterable[str], Space]) –
name (str) –
dtype (Type) –
Type
DoubleCB
Double sided Crystal Ball shaped PDF. A combination of two CB using the mu (not a frac) on each side.
alphal (~ParamTypeInput) – parameter where to switch from a gaussian to the powertail on the left
side –
nl (~ParamTypeInput) – Exponent of the powertail on the left side
alphar (~ParamTypeInput) – parameter where to switch from a gaussian to the powertail on the right
nr (~ParamTypeInput) – Exponent of the powertail on the right side
Gauss
Bases: zfit.models.dist_tfp.WrapDistribution
zfit.models.dist_tfp.WrapDistribution
Gaussian or Normal distribution with a mean (mu) and a standartdeviation (sigma).
The gaussian shape is defined as
with the normalization over [-inf, inf] of
The normalization changes for different normalization ranges
mu (~ParamTypeInput) – Mean of the gaussian dist
sigma (~ParamTypeInput) – Standard deviation or spread of the gaussian
obs (Union[str, Iterable[str], Space]) – Observables and normalization range the pdf is defined in
name (str) – Name of the pdf
distribution
Uniform
Uniform distribution which is constant between low, high and zero outside.
low (~ParamTypeInput) – Below this value, the pdf is zero.
high (~ParamTypeInput) – Above this value, the pdf is zero.
TruncatedGauss
Gaussian distribution that is 0 outside of low, high. Equivalent to the product of Gauss and Uniform.
WrapDistribution
Baseclass to wrap tensorflow-probability distributions automatically.
Cauchy
Non-relativistic Breit-Wigner (Cauchy) PDF representing the energy distribution of a decaying particle.
The (unnormalized) shape of the non-relativistic Breit-Wigner is given by
with \(m\) the mean and \(\gamma\) the width of the distribution.
m (~ParamTypeInput) – Invariant mass of the unstable particle.
gamma (~ParamTypeInput) – Width of the shape.
name (str) – Name of the PDF
Poisson
Poisson distribution, parametrized with an event rate parameter (lamb).
The probability mass function of the Poisson distribution is given by
lamb (~ParamTypeInput) – the event rate
Chebyshev
Bases: zfit.models.polynomials.RecursivePolynomial
zfit.models.polynomials.RecursivePolynomial
Linear combination of Chebyshev (first kind) polynomials of order len(coeffs), coeffs are scaling factors.
The 0th coefficient is set to 1 by default but can be explicitly set with coeff0. Since the PDF normalization removes a degree of freedom, the 0th coefficient is redundant and leads to an arbitrary overall scaling of all parameters.
Notice that this is already a sum of polynomials and the coeffs are simply scaling the individual orders of the polynomials.
The recursive definition of a single order of the polynomial is
Notice that \(T_1\) is x as opposed to 2x in Chebyshev polynomials of the second kind.
obs – The default space the PDF is defined in.
coeffs (list) – A list of the coefficients for the polynomials of order 1+ in the sum.
list
apply_scaling (bool) – Rescale the data so that the actual limits represent (-1, 1).
coeff0 (Optional[~ParamTypeInput]) – The scaling factor of the 0th order polynomial. If not given, it is set to 1.
name (str) – Name of the polynomial
degree
degree of the polynomial, starting from 0.
Legendre
Linear combination of Legendre polynomials of order len(coeffs), the coeffs are overall scaling factors.
obs (Union[str, Iterable[str], Space]) – The default space the PDF is defined in.
coeffs (List[~ParamTypeInput]) – A list of the coefficients for the polynomials of order 1+ in the sum.
Chebyshev2
Linear combination of Chebyshev (second kind) polynomials of order len(coeffs), coeffs are scaling factors.
Notice that \(T_1\) is 2x as opposed to x in Chebyshev polynomials of the first kind.
Hermite
Linear combination of Hermite polynomials (for physics) of order len(coeffs), with coeffs as scaling factors.
with P_0 = 1 P_1 = 2x
Laguerre
Linear combination of Laguerre polynomials of order len(coeffs), the coeffs are overall scaling factors.
with P_0 = 1 P_1 = 1 - x
RecursivePolynomial
1D polynomial generated via three-term recurrence.
Base class to create 1 dimensional recursive polynomials that can be rescaled. Overwrite _poly_func.
coeffs (list) – Coefficients for each polynomial. Used to calculate the degree.
apply_scaling (bool) –
Rescale the data so that the actual limits represent (-1, 1).
ProductPDF
Bases: zfit.models.functor.BaseFunctor
zfit.models.functor.BaseFunctor
SumPDF
Create the sum of the pdfs with fracs as coefficients or the yields, if extended pdfs are given.
If all pdfs are extended, the fracs is optional and the (normalized) yields will be used as fracs. If fracs is given, this will be used as the fractions, regardless of whether the pdfs have a yield or not.
The parameters of the SumPDF are the fractions that are used to multiply the output of each daughter pdf. They can be accessed with pdf.params and have names f”frac_{i}” with i starting from 0 and going to the number of pdfs given.
To get the component outputs of this pdf, e.g. to plot it, use pdf.params.values() to iterate through the fracs and pdfs to get the pdfs. For example
for pdf, frac in zip(sumpdf.pdfs, sumpdf.params.values()): frac_integral = pdf.integrate(...) * frac
pdfs (List[ZfitPDF]) – The pdfs to be added.
fracs (Optional[~ParamTypeInput]) –
Coefficients for the linear combination of the pdfs. Optional if all pdfs are extended.
len(frac) == len(basic) - 1 results in the interpretation of a non-extended pdf. The last coefficient will equal to 1 - sum(frac)
len(frac) == len(pdf): the fracs will be used as is and no normalization attempt is taken.
name (str) – This is the stub description for names. Change it in docs/subst_types.txt.
ModelIncompatibleError: If model is incompatible.
fracs
GaussianKDE1DimV1
EXPERIMENTAL, FEEDBACK WELCOME One dimensional, (truncated) Kernel Density Estimation with a Gaussian Kernel.
Kernel Density Estimation is a non-parametric method to approximate the density of given points.
where the kernel in this case is a (truncated) Gaussian
The bandwidth of the kernel can be estimated in different ways. It can either be a global bandwidth, corresponding to a single value, or a local bandwidth, each corresponding to one data point
data (~ParamTypeInput) – 1-D Tensor-like. The positions of the kernel, the \(x_i\). Determines how many kernels will be created.
bandwidth (Optional[~ParamTypeInput]) – Bandwidth of the kernel. Valid options are {‘silverman’, ‘scott’, ‘adaptive’} or a numerical. If a numerical is given, it as to be broadcastable to the batch and event shape of the distribution. A scalar or a zfit.Parameter will simply broadcast to data for a 1-D distribution.
obs (Union[str, Iterable[str], Space]) – Observables
weights (Union[Tensor, None, ndarray]) – Weights of each data, can be None or Tensor-like with shape compatible with data
truncate (bool) – If a truncated Gaussian kernel should be used with the limits given by the obs lower and upper limits. This can cause NaNs in case datapoints are outside of the limits.
FFTConvPDFV1
EXPERIMENTAL Numerical Convolution pdf of func convoluted with kernel using FFT
CURRENTLY ONLY 1 DIMENSIONAL!
EXPERIMENTAL: Feedback is very welcome! Performance, which parameters to tune, which fail etc.
FFT-like technique: discretization of function. Number of bins splits the kernel into n bins and uses the same binwidth for the func while extending it by the kernel space. Internally, tf.nn.convolution (attention, this is actually a cross-correlation) is used.
Then interpolation by either linear or spline function
The kernel is assumed to be “small enough” outside of it’s space and points there won’t be evaluated.
The convolution of two (normalized) functions is defined as
It defines the “smearing” of func by a kernel. This is when an element in func is randomly added to an element of kernel. While the sampling (the addition of elements) is rather simple to do computationally, the calculation of the convolutional PDF (if there is no analytic solution available) is not, as it requires:
an integral from -inf to inf an integral _for every point of x that is requested_
an integral from -inf to inf
an integral _for every point of x that is requested_
This can be solved with a few tricks. Instead of integrating to infinity, it is usually sufficient to integrate from a point where the function is “small enough”.
If the functions are arbitrary and with conditional dependencies, there is no way around an integral and another PDF has to be used. If the two functions are uncorrelated, a simplified version can be done by a discretization of the space (followed by a Fast Fourier Transfrom, after which the convolution becomes a simple multiplication) and a discrete convolution can be performed.
An interpolation of the discrete convolution for the requested points x is performed afterwards.
func (ZfitPDF) – PDF with pdf method that takes x and returns the function value. Here x is a Data with the obs and limits of limits.
kernel (ZfitPDF) – PDF with pdf method that takes x acting as the kernel. Here x is a Data with the obs and limits of limits.
n (Optional[int]) – Number of points _per dimension_ to evaluate the kernel and pdf at. The higher the number of points, the more accurate the convolution at the cost of computing time. If None, a heuristic is used (default to 100 in 1 dimension).
limits_func (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space, float, None]) –
Specify in which limits the func should be evaluated for the convolution: - If None, the limits from the func are used and extended by a
default value (relative 0.2).
If float: the fraction of the limit do be extended. 0 means no extension, 1 would extend the limits to each side by the same size resulting in a tripled size (for 1 dimension). As an example, the limits (1, 5) with a limits_func of 0.5 would result in effective limits of (-1, 7), as 0.5 * (5 - 1) = 2 has been added to each side.
If a space with limits is used, this is taken as the range.
limits_kernel (Union[Tuple[Tuple[float, …]], Tuple[float, …], bool, Space, None]) – the limits of the kernel. Usually not needed to change and automatically taken from the kernel.
interpolation (Optional[str]) –
Specify the method that is used for interpolation. Available methods are: - ‘linear’: this is the default for any convolution > 1 dimensional. It is a
fast, linear interpolation between the evaluated points and approximates the function reasonably well in case of high number of points and a smooth response.
’spline’ or f’spline{order}’: a spline interpolation with polynomials. If the order is not specified, a default is used. To specify the order, an integer should be followed the word ‘spline’ as e.g. in ‘spline3’ to use a spline of order three. This method is considerably more computationally intensive as it requires to solve a system of equations. When using 1000+ points this can affect the runtime critical. However, it provides better solutions that are smooth even with less points than for a linear interpolation.
obs (Union[str, Iterable[str], Space, None]) – Observables of the class. If not specified, automatically taken from func
name (str) – Human readable name of the PDF
conv_interpolation
ZPDF
Bases: zfit.core.basemodel.SimpleModelSubclassMixin, zfit.core.basepdf.BasePDF
zfit.core.basemodel.SimpleModelSubclassMixin
SimplePDF
SimpleFunctorPDF
Bases: zfit.models.functor.BaseFunctor, zfit.models.special.SimplePDF
zfit.models.special.SimplePDF