This module defines the BasePdf that can be used to inherit from in order to build a custom PDF.
The BasePDF implements already a lot of ready-to-use functionality like integral, automatic normalization and sampling.
A simple example: >>> class MyGauss(BasePDF): >>> def __init__(self, mean, stddev, name=”MyGauss”): >>> super().__init__(mean=mean, stddev=stddev, name=name) >>> >>> def _unnormalized_pdf(self, x): >>> return tf.exp((x - mean) ** 2 / (2 * stddev**2))
Notice that here we only specify the function and no normalization. This No attempt to explicitly normalize the function should be done inside _unnormalized_pdf. The normalization is handled with another method depending on the normalization range specified. (It is possible, though discouraged, to directly provide the normalized probability by overriding _pdf(), but there are other, more convenient ways to add improvements like providing an analytical integrals.)
Before we create an instance, we need to create the variables to initialize it >>> mean = zfit.Parameter(“mean1”, 2., 0.1, 4.2) # signature as in RooFit: name, initial, lower, upper >>> stddev = zfit.Parameter(“stddev1”, 5., 0.3, 10.) Let’s create an instance and some example data >>> gauss = MyGauss(mean=mean, stddev=stddev) >>> example_data = np.random.random(10) Now we can get the probability >>> probs = gauss.pdf(x=example_data,norm_range=(-30., 30)) # norm_range specifies over which range to normalize Or the integral >>> integral = gauss.integrate(limits=(-5, 3.1), norm_range=False) # norm_range is False -> return unnormalized integral Or directly sample from it >>> sample = gauss.sample(n_draws=1000, limits=(-10, 10)) # draw 1000 samples within (-10, 10)
We can create an extended PDF, which will result in anything using a norm_range to not return the probability but the number probability (the function will be normalized to yield instead of 1 inside the norm_range) >>> yield1 = Parameter(“yield1”, 100, 0, 1000) >>> gauss_extended = gauss.create_extended(yield1) >>> gauss.is_extended True
>>> integral_extended = gauss.integrate(limits=(-10, 10), norm_range=(-10, 10)) # yields approx 100
For more advanced methods and ways to register analytic integrals or overwrite certain methods, see also the advanced tutorials in zfit tutorials
zfit.core.basepdf.
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 –