============================
Space, Observable and Range
============================
Inside zfit, :py:class:`~zfit.Space` defines the domain of objects by specifying the observables/axes and *maybe* also
the limits. Any model and data needs to be specified in a certain domain, which is usually done using the
``obs`` argument. It is crucial that the axis used by the observable of the data and the model match, and this matching is
handle by the :py:class:`~zfit.Space` class.
.. code:: python
obs = zfit.Space("x")
model = zfit.pdf.Gauss(obs=obs, ...)
data = zfit.Data.from_numpy(obs=obs, ...)
Definitions
-----------
**Space**: an *n*-dimensional definition of a domain (either by using one or more observables or axes),
with or without limits.
.. note::
*compared to `RooFit`, a space is **not** the equivalent of an observable but rather corresponds
to an object combining **a set** of observables (which of course can be of size 1). Furthermore,
there is a **strong** distinction in zfit between a :py:class:`~zfit.Space` (or observables)
and a :py:class:`~zfit.Parameter`, both conceptually and in terms of implementation and usage.*
**Observable**: a string defining the axes; a named axes.
*(for advanced usage only, can be skipped on first read)*
**Axis**: integer defining the axes *internally* of a model. There is always a mapping of observables <-> axes *once inside a model*.
**Limit** The range on a certain axis. Typically defines an interval. In fact, there are two times of limits:
* **rectangular**: This type is the usual limit as e.g. ``(-2, 5)`` for a simple, 1 dimensional interval. It is
rectangular. This can either be given as ``limits`` of a :py:class:`~zfit.Space` or as ``rect_limits``.
* **functional**: In order to define arbitrary limits, a function can be used that receives a tensor-like
object ``x`` and returns ``True`` on every position that is inside the limits, ``False`` for every value outside.
When a functional limit is given, rectangular limits that contain the functional limit as a subset **must** be
defined as well.
Since every object has a well defined domain, it is possible to combine them in an unambiguous way.
While not enforced, a space should usually be created with limits that define the default space of an object.
This correspond for example to the default normalization range ``norm_range`` or sampling range.
.. code:: python
lower1, upper1 = [0, 1], [2, 3]
lower2, upper2 = [-4, 1], [10, 3]
obs1 = zfit.Space(['x', 'y'], limits=(lower1, upper2))
obs2 = zfit.Space(['z', 'y'], limits=(lower2, upper2))
model1 = zfit.pdf.Gauss(obs=obs1, ...)
model2 = zfit.pdf.Gauss(obs=obs2, ...)
# creating a composite pdf
product = model1 * model2
# OR, equivalently
product = zfit.pdf.ProductPDF([model1, model2])
assert obs1 * obs2 = product.space
The ``product`` is now defined in the space with observables `['x', 'y', 'z']`. Any :py:class:`~zfit.Data` object
to be combined with ``product`` has to be specified in the same space.
.. code:: python
# create the space
combined_obs = obs1 * obs2
data = zfit.Data.from_numpy(obs=combined_obs, ...)
Now we have a :py:class:`~zfit.Data` object that is defined in the same domain as `product` and can be used to build a loss function.
Limits
------
In many places, just defining the observables is not enough and an interval, specified by its limits, is required.
Examples are a normalization range, the limits of an integration or sampling in a certain region.
Simple, 1-dimensional limits can be specified as follows. Operations like addition (creating a space with
two intervals) or combination (increase the dimensionality) are also possible.
.. code:: python
simple_limit1 = zfit.Space(obs='obs1', limits=(-5, 1))
simple_limit2 = zfit.Space(obs='obs1', limits=(3, 7.5))
added_limits = simple_limit1 + simple_limit2
In this case, `added_limits` is now a :py:class:`zfit.Space` with observable `'obs1'` defined in the intervals
(-5, 1) and (3, 7.5). This can be useful, *e.g.*, when fitting in two regions.
An example of the product of different :py:class:`zfit.Space` instances has been shown before as ``combined_obs``.
Functional limits
'''''''''''''''''
Limits can be defined by a function that returns whether a value is inside the boundaries or not **and** rectangular
limits (note that specifying `rect_limit` does *not* enforce them, the function itself has to take care of that).
This example specifies the bounds between (-4, 0.5) with the `limit_fn` (which, in this simple case, could be better
achieved by directly specifying them as rectangular limits).
.. code:: python
def limit_fn(x):
x = z.unstack_x(x)
inside_lower = tf.greater_equal(x, -4)
inside_upper = tf.less_equal(x, 0.5)
inside = tf.logical_and(inside_lower, inside_upper)
return inside
space = zfit.Space(obs='obs1', limits=limit_fn, rect_limits=(-5, 1))
Combining limits
''''''''''''''''
To define simple, 1-dimensional limits, a tuple with two numbers or a functional limit in 1 dimension is enough. For anything more complicated,
the operators product `*` or addition `+` respectively their functional API :py:func:`zfit.dimension.combine_spaces`
and :py:func:`zfit.dimension.add_spaces` can be used.
A working code example of :py:class:`~zfit.Space` handling is provided in `spaces.py` in
:doc:`examples <../../examples/spaces.py>`.
Using the limits
'''''''''''''''''
To use the limits of any object, the methods :py:meth`~zfit.Space.inside` (to test if values are inside or outside of the boundaries)
and :py:meth`~zfit.Space.filter` can be used.
The rectangular limits can also direclty be accessed by ``rect_limits``, ``rect_lower`` or ``rect_upper``. The returned shape is of
`(n_events, n_obs)`, for the lower respectively upper limit (``rect_limits`` is a tuple of `(lower, upper)`).
This should be used with caution and only if the rectangular limits are desired.