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.Any[source]

Bases: object

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:
  • obs (str, List[str,..]) –
  • () (limits) –
  • name (str) –
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:

Space

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:

Space

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:
  • () (obs) –
  • as_dict (bool) – If True, returns a ordered dictionary with {obs: axis}
  • autofill (bool) – If True and the axes are not specified, automatically fill them with the default numbering and return (not setting them).
Returns:

Tuple, OrderedDict

Raises:
  • ValueError – if the requested obs do not match with the one defined in the range
  • AxesNotSpecifiedError – If the axes in this Space 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:
  • obs (str, Tuple[str]) –
  • axes (int, Tuple[int]) –
  • () (name) –

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:

Space

with_obs(obs: Union[str, Iterable[str], zfit.Space]) → zfit.Space[source]

Sort by obs and return the new instance.

Parameters:() (obs) –
Returns:Space
with_obs_axes(obs_axes: Union[OrderedDict[str, int], Dict[str, int]], ordered: bool = False, allow_subset=False) → zfit.Space[source]

Return a new Space with reordered observables and set the axes.

Parameters:
  • obs_axes (OrderedDict[str, int]) – An ordered dict with {obs: axes}.
  • ordered (bool) – If True (and the obs_axes is an OrderedDict), the
  • () (allow_subset) –
Returns:

Return type:

Space

zfit.core.limits.contains_tensor(object)[source]
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 of Space 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 a Space and axes respectively obs is not None.

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.shape_np_tf(object)[source]
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:
  • norm_range (bool) – If False, no norm_range argument will be passed through resp. will be None
  • multiple_limits (bool) – If False, only simple limits are to be expected and no iteration is therefore required.