limits¶
# NamedSpace and limits
Limits define a certain interval in a specific dimension. This can be used to define, for example, the limits of an integral over several dimensions or a normalization range.
### with limits
Therefore a different way of specifying limits is possible, basically by defining chunks of the lower and the upper limits. The shape of a lower resp. upper limit is (n_limits, n_obs).
Example: 1-dim: 1 to 4, 2.-dim: 21 to 24 AND 1.-dim: 6 to 7, 2.-dim 26 to 27 >>> lower = ((1, 21), (6, 26)) >>> upper = ((4, 24), (7, 27)) >>> limits2 = Space(limits=(lower, upper), obs=(‘obs1’, ‘obs2’)
General form:
lower = ((lower1_dim1, lower1_dim2, lower1_dim3), (lower2_dim1, lower2_dim2, lower2_dim3),…) upper = ((upper1_dim1, upper1_dim2, upper1_dim3), (upper2_dim1, upper2_dim2, upper2_dim3),…)
## Using Space
NamedSpace
offers a few useful functions to easier deal with the intervals
### Handling areas
For example when doing a MC integration using the expectation value, it is mandatory to know the total area of your intervals. You can retrieve the total area or (if multiple limits (=intervals
are given) the area of each interval.
>>> area = limits2.area() >>> area_1, area_2 = limits2.iter_areas(rel=False) # if rel is True, return the fraction of 1
### Retrieve the limits
>>> lower, upper = limits2.limits
which you can now iterate through. For example, to calc an integral (assuming there is a function integrate taking the lower and upper limits and returning the function), you can do >>> def integrate(lower_limit, upper_limit): return 42 # dummy function >>> integral = sum(integrate(lower_limit=low, upper_limit=up) for low, up in zip(lower, upper))
-
class
zfit.core.limits.
AnyLower
[source]¶ Bases:
zfit.core.limits.Any
-
class
zfit.core.limits.
AnyUpper
[source]¶ Bases:
zfit.core.limits.Any
-
class
zfit.core.limits.
Space
(obs: Union[str, Iterable[str], zfit.Space], limits: Union[Tuple[Tuple[Tuple[float, ...]]], Tuple[float, float], bool, None] = None, name: Optional[str] = 'Space')[source]¶ Bases:
zfit.core.interfaces.ZfitSpace
,zfit.core.baseobject.BaseObject
Define a space with the name (obs) of the axes (and it’s number) and possibly it’s limits.
Parameters: -
ANY
= <Any>¶
-
ANY_LOWER
= <Any Lower Limit>¶
-
ANY_UPPER
= <Any Upper Limit>¶
-
AUTO_FILL
= <object object>¶
-
add
(other: Union[zfit.Space, Iterable[zfit.Space]])[source]¶ Add the limits of the spaces. Only works for the same obs.
In case the observables are different, the order of the first space is taken.
Parameters: other ( Space
) –Returns: Return type: Space
-
area
() → float[source]¶ Return the total area of all the limits and axes. Useful, for example, for MC integration.
-
axes
¶ The axes (“obs with int”) the space is defined in.
Returns:
-
combine
(other: Union[zfit.Space, Iterable[zfit.Space]]) → zfit.core.interfaces.ZfitSpace[source]¶ Combine spaces with different obs (but consistent limits).
Parameters: other ( Space
) –Returns: Return type: Space
-
copy
(name: Optional[str] = None, **overwrite_kwargs) → zfit.Space[source]¶ Create a new
Space
using the current attributes and overwriting with overwrite_overwrite_kwargs.Parameters: - name (str) – The new name. If not given, the new instance will be named the same as the current one.
- () (**overwrite_kwargs) –
Returns:
-
classmethod
from_axes
(axes: Union[int, Iterable[int]], limits: Union[Tuple[Tuple[Tuple[float, ...]]], Tuple[float, float], bool, None] = None, name: str = None) → zfit.Space[source]¶ Create a space from axes instead of from obs.
Parameters: - () (limits) –
- () –
- name (str) –
Returns:
-
get_axes
(obs: Union[str, Iterable[str], zfit.Space] = None, as_dict: bool = False, autofill: bool = False) → Union[Tuple[int], None, Dict[str, int]][source]¶ Return the axes corresponding to the obs (or all if None).
Parameters: Returns: Tuple, OrderedDict
Raises: ValueError
– if the requested obs do not match with the one defined in the rangeAxesNotSpecifiedError
– If the axes in thisSpace
have not been specified.
-
get_obs_axes
(obs: Union[str, Iterable[str], zfit.Space] = None, axes: Union[int, Iterable[int]] = None)[source]¶
-
get_reorder_indices
(obs: Union[str, Iterable[str], zfit.Space] = None, axes: Union[int, Iterable[int]] = None) → Tuple[int][source]¶ Indices that would order self.obs as obs respectively self.axes as axes.
Parameters: - () (axes) –
- () –
Returns:
-
get_subspace
(obs: Union[str, Iterable[str], zfit.Space] = None, axes: Union[int, Iterable[int]] = None, name: Optional[str] = None) → zfit.Space[source]¶ Create a
Space
consisting of only a subset of the obs/axes (only one allowed).Parameters: Returns:
-
iter_areas
(rel: bool = False) → Tuple[float, ...][source]¶ Return the areas of each interval
Parameters: rel (bool) – If True, return the relative fraction of each interval Returns: Return type: Tuple[float]
-
iter_limits
(as_tuple: bool = True) → Union[Tuple[zfit.Space], Tuple[Tuple[Tuple[float]]], Tuple[Tuple[float]]][source]¶ Return the limits, either as
Space
objects or as pure limits-tuple.This makes iterating over limits easier: for limit in space.iter_limits() allows to, for example, pass limit to a function that can deal with simple limits only or if as_tuple is True the limit can be directly used to calculate something.
Example
for lower, upper in space.iter_limits(as_tuple=True): integrals = integrate(lower, upper) # calculate integral integral = sum(integrals)
Returns: Return type: List[ Space
] or List[limit,…]
-
limit1d
¶ return the tuple(lower, upper).
Returns: so lower, upper = space.limit1d
for a simple, 1 obs limit.Return type: tuple(float, float) Raises: RuntimeError
– if the conditions (n_obs or n_limits) are not satisfied.Type: Simplified limits getter for 1 obs, 1 limit only
-
limit2d
¶ return the tuple(low_obs1, low_obs2, up_obs1, up_obs2).
Returns: - so low_x, low_y, up_x, up_y = space.limit2d for a single, 2 obs limit.
- low_x is the lower limit in x, up_x is the upper limit in x etc.
Return type: tuple(float, float, float, float) Raises: RuntimeError
– if the conditions (n_obs or n_limits) are not satisfied.Type: Simplified limits for exactly 2 obs, 1 limit
-
limits
¶ Return the limits.
Returns:
-
limits1d
¶ return the tuple(low_1, …, low_n, up_1, …, up_n).
Returns: - so low_1, low_2, up_1, up_2 = space.limits1d for several, 1 obs limits.
- low_1 to up_1 is the first interval, low_2 to up_2 is the second interval etc.
Return type: tuple(float, float, ..) Raises: RuntimeError
– if the conditions (n_obs or n_limits) are not satisfied.Type: Simplified .limits for exactly 1 obs, n limits
-
lower
¶ Return the lower limits.
Returns:
-
n_limits
¶ The number of different limits.
Returns: int >= 1
-
n_obs
¶ Return the number of observables/axes.
Returns: int >= 1
-
name
¶ The name of the object.
-
obs
¶ The observables (“axes with str”)the space is defined in.
Returns:
-
obs_axes
¶
-
reorder_by_indices
(indices: Tuple[int])[source]¶ Return a
Space
reordered by the indices.Parameters: () (indices) –
-
upper
¶ Return the upper limits.
Returns:
-
with_autofill_axes
(overwrite: bool = False) → zfit.Space[source]¶ Return a
Space
with filled axes corresponding to range(len(n_obs)).Parameters: overwrite (bool) – If self.axes is not None, replace the axes with the autofilled ones. If axes is already set, don’t do anything if overwrite is False. Returns: Space
-
with_axes
(axes: Union[int, Iterable[int]]) → zfit.Space[source]¶ Sort by obs and return the new instance.
Parameters: () (axes) – Returns: Space
-
with_limits
(limits: Union[Tuple[Tuple[Tuple[float, ...]]], Tuple[float, float], bool], name: Optional[str] = None) → zfit.Space[source]¶ Return a copy of the space with the new limits (and the new name).
Parameters: - () (limits) –
- name (str) –
Returns:
-
with_obs
(obs: Union[str, Iterable[str], zfit.Space]) → zfit.Space[source]¶ Sort by obs and return the new instance.
Parameters: () (obs) – Returns: Space
-
-
zfit.core.limits.
convert_to_obs_str
(obs)[source]¶ Convert obs to the list of obs, also if it is a
Space
.
-
zfit.core.limits.
convert_to_space
(obs: Union[str, Iterable[str], zfit.Space, None] = None, axes: Union[int, Iterable[int], None] = None, limits: Union[Tuple[Tuple[Tuple[float, ...]]], Tuple[float, float], bool, None] = None, *, overwrite_limits: bool = False, one_dim_limits_only: bool = True, simple_limits_only: bool = True) → Union[None, zfit.core.limits.Space, bool][source]¶ Convert limits to a
Space
object if not already None or False.Parameters: - obs (Union[Tuple[float, float],
Space
]) – - () (axes) –
- () –
- overwrite_limits (bool) – If obs or axes is a
Space
_and_ limits are given, return an instance ofSpace
with the new limits. If the flag is False, the limits argument will be ignored if - one_dim_limits_only (bool) –
- simple_limits_only (bool) –
Returns: Return type: Union[
Space
, False, None]Raises: OverdefinedError
– if obs or axes is aSpace
and axes respectively obs is not None.- obs (Union[Tuple[float, float],
-
zfit.core.limits.
no_multiple_limits
(func)[source]¶ Decorator: Catch the ‘limits’ kwargs. If it contains multiple limits, raise MultipleLimitsNotImplementedError.
-
zfit.core.limits.
no_norm_range
(func)[source]¶ Decorator: Catch the ‘norm_range’ kwargs. If not None, raise NormRangeNotImplementedError.
-
zfit.core.limits.
supports
(*, norm_range: bool = False, multiple_limits: bool = False) → Callable[source]¶ Decorator: Add (mandatory for some methods) on a method to control what it can handle.
If any of the flags is set to False, it will check the arguments and, in case they match a flag (say if a norm_range is passed while the norm_range flag is set to False), it will raise a corresponding exception (in this example a NormRangeNotImplementedError) that will be catched by an earlier function that knows how to handle things.
Parameters: