FFTConvPDFV1¶
- class zfit.pdf.FFTConvPDFV1(func, kernel, n=None, limits_func=None, limits_kernel=None, interpolation=None, obs=None, name='FFTConvV1')[source]¶
Bases:
zfit.models.functor.BaseFunctor
EXPERIMENTAL Numerical Convolution pdf of
func
convoluted withkernel
using FFTCURRENTLY ONLY 1 DIMENSIONAL!
EXPERIMENTAL: Feedback is very welcome! Performance, which parameters to tune, which fail etc.
TL;DR technical details:
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
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
\[(f * g)(t) \triangleq\ \int_{-\infty}^\infty f(\tau) g(t - \tau) \, d\tau\]It defines the “smearing” of
func
by akernel
. This is when an element infunc
is randomly added to an element ofkernel
. 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
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.- Parameters
func (
ZfitPDF
) – PDF withpdf
method that takes x and returns the function value. Here x is aData
with the obs and limits of limits.kernel (
ZfitPDF
) – PDF withpdf
method that takes x acting as the kernel. Here x is aData
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. IfNone
, a heuristic is used (default to 100 in 1 dimension).limits_func (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
,float
]) –Specify in which limits the
func
should be evaluated for the convolution:If
None
, the limits from thefunc
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
,ForwardRef
]) – 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, ‘spline’ should be followed an integer, separated by a colon as e.g. in ‘spline:3’ to use a spline of order three. This method is considerably more computationally expensive as it requires to solve a system of equations. When using 1000+ points this can affect the runtime critical. However, it provides better solution, a curve that is smooth even with less points than for a linear interpolation.
obs (
Union
[str
,Iterable
[str
],ForwardRef
,None
]) – Observables of the class. If not specified, automatically taken fromfunc
name (
str
) – Human readable name of the PDF
- add_cache_deps(cache_deps, allow_non_cachable=True)¶
Add dependencies that render the cache invalid if they change.
- Parameters
cache_deps (
Union
[ForwardRef
,Iterable
[ForwardRef
]]) –allow_non_cachable (
bool
) – IfTrue
, allowcache_dependents
to be non-cachables. IfFalse
, anycache_dependents
that is not aZfitCachable
will raise an error.
- Raises
TypeError – if one of the
cache_dependents
is not aZfitCachable
_and_allow_non_cachable
ifFalse
.
- analytic_integrate(limits, norm=None, *, norm_range=None)¶
Analytical integration over function and raise Error if not possible.
- Parameters
limits (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
]) – the limits to integrate overnorm (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
]) – the limits to normalize over
- Return type
Union
[float
,Tensor
]- Returns
The integral value
- Raises
AnalyticIntegralNotImplementedError – If no analytical integral is available (for this limits).
NormRangeNotImplementedError – if the norm argument is not supported. This means that no analytical normalization is available, explicitly: the analytical integral over the limits = norm is not available.
- apply_yield(value, norm=False, log=False)¶
If a norm_range is given, the value will be multiplied by the yield.
- Parameters
value (
Union
[float
,Tensor
]) –norm (
Union
[ZfitLimit
,Tensor
,ndarray
,Iterable
[float
],float
,Tuple
[float
],List
[float
],bool
,None
]) –log (
bool
) –
- Return type
Union
[float
,Tensor
]- Returns
Numerical
- as_func(norm=False, *, norm_range=None)¶
Return a
Function
with the functionmodel(x, norm=norm)
.- Parameters
norm (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
]) –
- copy(**override_parameters)¶
Creates a copy of the model.
Note: the copy model may continue to depend on the original initialization arguments.
- Parameters
**override_parameters – String/value dictionary of initialization arguments to override with new value.
- Return type
- Returns
- A new instance of
type(self)
initialized from the union of self.parameters and override_parameters, i.e.,
dict(self.parameters, **override_parameters)
.
- A new instance of
- create_extended(yield_, name_addition='_extended')¶
Return an extended version of this pdf with yield
yield_
. The parameters are shared.- Parameters
yield –
name_addition –
- Return type
ZfitPDF
- Returns
ZfitPDF
- create_projection_pdf(limits, *, options=None, limits_to_integrate=None)¶
Create a PDF projection by integrating out some of the dimensions. (deprecated arguments)
Warning: SOME ARGUMENTS ARE DEPRECATED:
(limits_to_integrate)
. They will be removed in a future version. Instructions for updating: Uselimits
instead.The new projection pdf is still fully dependent on the pdf it was created with.
- Parameters
() (options) –
() –
limits (
Union
[ZfitLimit
,Tensor
,ndarray
,Iterable
[float
],float
,Tuple
[float
],List
[float
],bool
,None
]) –
- Return type
ZfitPDF
- Returns
A pdf without the dimensions from
limits_to_integrate
.
- create_sampler(n=None, limits=None, fixed_params=True)¶
Create a
Sampler
that acts asData
but can be resampled, also with changed parameters and n.If
limits
is not specified,space
is used (if the space contains limits). Ifn
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
,ForwardRef
]) – From which space to sample.fixed_params (
Union
[bool
,List
[ZfitParameter
],Tuple
[ZfitParameter
]]) – A list ofParameters
that will be fixed during severalresample
calls. If True, all are fixed, if False, all are floating. If aParameter
is not fixed and its value gets updated (e.g. by aParameter.set_value()
call), this will be reflected inresample
. If fixed, the Parameter will still have the same value as theSampler
has been created with when it resamples.
- Return type
Sampler
- Returns
Sampler
- 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: tensorflow.python.framework.dtypes.DType¶
The dtype of the object.
- Return type
DType
- get_cache_deps(only_floating=True)¶
Return a set of all independent
Parameter
that this object depends on.- Parameters
only_floating (
bool
) – IfTrue
, only return floatingParameter
- Return type
OrderedSet
- get_dependencies(only_floating=True)¶
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 orget_cache_deps
in case you need the numerical cache dependents (advanced).
- get_params(floating=True, is_yield=None, extract_independent=True, only_floating=<class 'zfit.util.checks.NotSpecified'>)¶
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.
- None: do not filter on this. E.g.
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.
- False: only return parameters that do not fulfil this criterion. E.g.
- Parameters
floating (
Optional
[bool
]) – if a parameter is floating, e.g. iffloating()
returnsTrue
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 aZfitIndependentParameter
.
- Return type
Set
[ZfitParameter
]
- get_yield()¶
Return the yield (only for extended models).
- Return type
Optional
[Parameter
]- Returns
The yield of the current model or None
- property is_extended: bool¶
Flag to tell whether the model is extended or not.
- Return type
bool
- Returns
A boolean.
- log_pdf(x, norm=None, *, norm_range=None)¶
Log probability density function normalized over
norm_range
.- Parameters
x (
Union
[float
,Tensor
]) –float
ordouble
Tensor
.norm (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
]) –Space
to normalize over
- Return type
Union
[float
,Tensor
]- Returns
A
Tensor
of typeself.dtype
.
- property models: List[zfit.core.interfaces.ZfitModel]¶
Return the models of this
Functor
.Can be
pdfs
orfuncs
.- Return type
List
[ZfitModel
]
- property name: str¶
The name of the object.
- Return type
str
- property norm: Union[zfit.core.space.Space, None, bool]¶
Return the current normalization range. If None and the
obs
have limits, they are returned.- Return type
Union
[Space
,None
,bool
]- Returns
The current normalization range.
- property norm_range: Union[zfit.core.space.Space, None, bool]¶
Return the current normalization range. If None and the
obs
have limits, they are returned. (deprecated)Warning: THIS FUNCTION IS DEPRECATED. It will be removed in a future version. Instructions for updating: Use the
norm
attribute instead.- Return type
Union
[Space
,None
,bool
]- Returns
The current normalization range.
- normalization(limits, *, options=None)¶
Return the normalization of the function (usually the integral over
limits
).- Parameters
() (options) –
() –
limits (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
]) – The limits on where to normalize over
- Return type
Union
[float
,Tensor
]- Returns
The normalization value
- numeric_integrate(limits, norm=None, *, options=None, norm_range=None)¶
Numerical integration over the model.
- Parameters
limits (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
]) – the limits to integrate overnorm (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
]) – the limits to normalize over
- Return type
Union
[float
,Tensor
]- Returns
The integral value
- classmethod register_additional_repr(**kwargs)¶
Register an additional attribute to add to the repr.
- Parameters
an (any keyword argument. The value has to be gettable from the instance (has to be) –
self. (attribute or callable method of) –
- classmethod register_analytic_integral(cls, func, limits=None, priority=50, *, supports_norm=None, supports_norm_range=None, supports_multiple_limits=None)¶
Register an analytic integral with the class. (deprecated arguments)
Warning: SOME ARGUMENTS ARE DEPRECATED:
(supports_norm_range)
. They will be removed in a future version. Instructions for updating: Usesupports_norm
instead.- Parameters
func (
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 partial integral. If it is not a partial integral, this will be None.
- x (
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.
- norm_range (
params (Dict[param_name,
zfit.Parameters
]): The parameters of the model.model (
ZfitModel
):The model that is being integrated.
limits (
Union
[Tuple
[Tuple
[float
, …]],Tuple
[float
, …],bool
,ForwardRef
]) – If aSpace
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
) – IfTrue
, thelimits
given to the integration function can have multiple limits. IfFalse
, only simple limits will pass through and multiple limits will be auto-handled.supports_norm (
bool
) – IfTrue
,norm
argument to the function may not beNone
. IfFalse
,norm
will always beNone
and care is taken of the normalization automatically.
- Return type
None
- register_cacher(cacher)¶
Register a
cacher
that caches values produces by this instance; a dependent.- Parameters
cacher (
Union
[ForwardRef
,Iterable
[ForwardRef
]]) –
- classmethod register_inverse_analytic_integral(func)¶
Register an inverse analytical integral, the inverse (unnormalized) cdf.
- Parameters
func (
Callable
) – A function with the signaturefunc(x, params)
, wherex
is a Data object andparams
is a dict.- Return type
None
- reset_cache_self()¶
Clear the cache of self and all dependent cachers.
- sample(n=None, limits=None, x=None)¶
Sample
n
points withinlimits
from the model.If
limits
is not specified,space
is used (if the space contains limits). Ifn
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
,ForwardRef
]) – In which region to sample in
- Return type
SampleData
- Returns
SampleData(n_obs, n_samples)
- Raises
NotExtendedPDFError – if ‘extended’ is (implicitly by default or explicitly) chosen 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.
- set_norm_range(norm)¶
Set the normalization range (temporarily if used with contextmanager).
- Parameters
norm (
Union
[ZfitLimit
,Tensor
,ndarray
,Iterable
[float
],float
,Tuple
[float
],List
[float
],bool
,None
]) –
- set_yield(value)¶
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
andintegrate
and similar methods will continue to return the same - normalized to 1 - values. However, not only can this parameter be accessed viaget_yield
, the methodsext_pdf
andext_integral
provide a version ofpdf
andintegrate
respecetively that is multiplied by the yield.These can be useful for plotting and for binned likelihoods.
- Parameters
() (value) –
- unnormalized_pdf(x)¶
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=False)
instead- Parameters
x (
Union
[float
,Tensor
]) – The value, have to be convertible to a Tensor- Return type
Union
[float
,Tensor
]- Returns
1-dimensional
tf.Tensor
containing the unnormalized pdf.
- update_integration_options(draws_per_dim=None, mc_sampler=None, tol=None, max_draws=None, draws_simpson=None)¶
Set the integration options.
- Parameters
max_draws (default ~1'000'000) – Maximum number of draws when integrating . Typically 500’000 - 5’000’000.
tol – Tolerance on the error of the integral. typically 1e-4 to 1e-8
draws_per_dim – The draws for MC integration to do per iteration. Can be set to
'auto
’.draws_simpson – Number of points in one dimensional Simpson integration. Can be set to
'auto'
.