IoVSet Class Reference

Public Member Functions
def	__init__ (self, iterable=None, *allow_overlaps=False, allow_startone=False)
def	add (self, iov, allow_overlaps=None)
def	remove (self, iov)
def	intersect (self, iov)
def	contains (self, iov)
def	overlaps (self, iov)
def	copy (self)
def	clear (self)
def	iovs (self)
def	first (self)
def	final (self)
def	gaps (self)
def	__bool__ (self)
def	__contains__ (self, iov)
def	__and__ (self, other)
def	__or__ (self, other)
def	__sub__ (self, other)
def	__iter__ (self)
def	__len__ (self)
def	__repr__ (self)

Private Attributes
	__iovs
	The set of iovs.
	__allow_overlaps
	Whether or not we raise an error on overlaps.
	__allow_startone
	Whether or not run 1 will be also considered the first run when combining iovs between experiments.

Detailed Description

A set of iovs.

This class allows to combine iovs into a set. New iovs can be added with
`add()` and will be combined with existing iovs if possible.

The final, minimal number of iovs can be obtained with the `iovs` property

    >>> a = IoVSet()
    >>> a.add((0,0,0,2))
    >>> a.add((0,3,0,5))
    >>> a.add((0,8,0,9))
    >>> a
    {(0, 0, 0, 5), (0, 8, 0, 9)}

Definition at line 279 of file iov.py.

Constructor & Destructor Documentation

__init__()

def __init__	(		self,
			iterable = None,
		*	allow_overlaps = False,
			allow_startone = False
	)

Create a new set.

    >>> a = IoVSet([IntervalOfValidity(3,6,3,-1), (0,0,3,5)])
    >>> a
    {(0, 0, 3, inf)}

Parameters:
    iterable: if not None it should be an iterable of IntervalOfValidity
        objects or anything that can be converted to an IntervalOfValidity.
    allow_overlaps (bool): If False adding which overlaps with any
        existing iov in the set will raise a ValueError.
    allow_startone (bool): If True also join iovs if one covers the
        whole experiment and the next one starts at run 1 in the next
        experiment. If False they will only be joined if the next one
        starts at run 0.

Definition at line 295 of file iov.py.

    def __init__(self, iterable=None, *, allow_overlaps=False, allow_startone=False):
        """Create a new set.
 
            >>> a = IoVSet([IntervalOfValidity(3,6,3,-1), (0,0,3,5)])
            >>> a
            {(0, 0, 3, inf)}
 
        Parameters:
            iterable: if not None it should be an iterable of IntervalOfValidity
                objects or anything that can be converted to an IntervalOfValidity.
            allow_overlaps (bool): If False adding which overlaps with any
                existing iov in the set will raise a ValueError.
            allow_startone (bool): If True also join iovs if one covers the
                whole experiment and the next one starts at run 1 in the next
                experiment. If False they will only be joined if the next one
                starts at run 0.
        """
        
        self.__iovs = set()
        
        self.__allow_overlaps = allow_overlaps
        
        self.__allow_startone = allow_startone
        if iterable is not None:
            for element in iterable:
                self.add(element)
 

Member Function Documentation

__and__()

def __and__	(		self,
			other
	)

Return a new set that is the intersection between two sets

    >>> a = IoVSet([(0,0,1,-1)])
    >>> a & (1,0,2,-1)
    {(1, 0, 1, inf)}

Definition at line 622 of file iov.py.

    def __and__(self, other):
        """Return a new set that is the intersection between two sets
 
            >>> a = IoVSet([(0,0,1,-1)])
            >>> a & (1,0,2,-1)
            {(1, 0, 1, inf)}
        """
        return self.intersect(other)
 

__bool__()

def __bool__

(

self

)

Return True if the set is not empty


    >>> a = IoVSet()
    >>> a.add((0,0,1,-1))
    >>> bool(a)
    True
    >>> a.clear()
    >>> a
    {}
    >>> bool(a)
    False

Definition at line 602 of file iov.py.

    def __bool__(self):
        """Return True if the set is not empty
 
 
            >>> a = IoVSet()
            >>> a.add((0,0,1,-1))
            >>> bool(a)
            True
            >>> a.clear()
            >>> a
            {}
            >>> bool(a)
            False
        """
        return len(self.__iovs) > 0
 

__contains__()

def __contains__	(		self,
			iov
	)

Check if an iov is fully covered by the set

Definition at line 618 of file iov.py.

    def __contains__(self, iov):
        """Check if an iov is fully covered by the set"""
        return self.contains(iov)
 

__iter__()

def __iter__

(

self

)

Loop over the set of iovs

Definition at line 667 of file iov.py.

    def __iter__(self):
        """Loop over the set of iovs"""
        return iter(self.__iovs)
 

__len__()

def __len__

(

self

)

Return the number of validity intervals in this set

Definition at line 671 of file iov.py.

    def __len__(self):
        """Return the number of validity intervals in this set"""
        return len(self.__iovs)
 

__or__()

def __or__	(		self,
			other
	)

Return a new set that is the combination of two sets: The new set will
be valid everywhere any of the two sets were valid.

No check for overlaps will be performed but the result will inherit the
settings for further additions from the first set

    >>> a = IoVSet([(0,0,1,-1)])
    >>> a | (1,0,2,-1)
    {(0, 0, 2, inf)}
    >>> a | (3,0,3,-1)
    {(0, 0, 1, inf), (3, 0, 3, inf)}

Definition at line 631 of file iov.py.

    def __or__(self, other):
        """
        Return a new set that is the combination of two sets: The new set will
        be valid everywhere any of the two sets were valid.
 
        No check for overlaps will be performed but the result will inherit the
        settings for further additions from the first set
 
            >>> a = IoVSet([(0,0,1,-1)])
            >>> a | (1,0,2,-1)
            {(0, 0, 2, inf)}
            >>> a | (3,0,3,-1)
            {(0, 0, 1, inf), (3, 0, 3, inf)}
        """
        copy = self.copy()
        copy.add(other, allow_overlaps=True)
        return copy
 

__repr__()

def __repr__

(

self

)

Return a printable representation

Definition at line 675 of file iov.py.

    def __repr__(self):
        """Return a printable representation"""
        return '{' + ', '.join(str(e) for e in sorted(self.__iovs)) + '}'

__sub__()

def __sub__	(		self,
			other
	)

Return a new set which is only valid for where a is valid but not b.

See `remove` but this will not modify the set in place

    >>> a = IoVSet([(0,0,-1,-1)])
    >>> a - (1,0,2,-1)
    {(0, 0, 0, inf), (3, 0, inf, inf)}
    >>> a - (0,0,3,-1) - (10,0,-1,-1)
    {(4, 0, 9, inf)}
    >>> IoVSet([(0,0,1,-1)]) - (2,0,2,-1)
    {(0, 0, 1, inf)}

Definition at line 649 of file iov.py.

    def __sub__(self, other):
        """
        Return a new set which is only valid for where a is valid but not b.
 
        See `remove` but this will not modify the set in place
 
            >>> a = IoVSet([(0,0,-1,-1)])
            >>> a - (1,0,2,-1)
            {(0, 0, 0, inf), (3, 0, inf, inf)}
            >>> a - (0,0,3,-1) - (10,0,-1,-1)
            {(4, 0, 9, inf)}
            >>> IoVSet([(0,0,1,-1)]) - (2,0,2,-1)
            {(0, 0, 1, inf)}
        """
        copy = self.copy()
        copy.remove(other)
        return copy
 

add()

def add	(		self,
			iov,
			allow_overlaps = None
	)

Add a new iov to the set.

The new iov be combined with existing iovs if possible. After the
operation the set will contain the minimal amount of separate iovs
possible to represent all added iovs

    >>> a = IoVSet()
    >>> a.add((0, 0, 0, 2))
    >>> a.add((0, 3, 0, 5))
    >>> a.add((0, 8, 0, 9))
    >>> a
    {(0, 0, 0, 5), (0, 8, 0, 9)}
    >>> a.add(IoVSet([(10, 0, 10, 1), (10, 2, 10, -1)]))
    >>> a
    {(0, 0, 0, 5), (0, 8, 0, 9), (10, 0, 10, inf)}

Be aware, by default it's not possible to add overlapping iovs to the set.
This can be changed either on construction or per `add` call using
``allow_overlap``

    >>> a.add((0, 2, 0, 3))
    Traceback (most recent call last):
        ...
    ValueError: Overlap between (0, 0, 0, 5) and (0, 2, 0, 3)
    >>> a.add((0, 2, 0, 3), allow_overlaps=True)
    >>> a
    {(0, 0, 0, 5), (0, 8, 0, 9), (10, 0, 10, inf)}

Parameters:
    iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
        set of IoVs to add to this set
    allow_overlaps (bool): Can be used to override global overlap setting
        of this set to allow/restrict overlaps for a single insertion
        operation

Warning:
    This method modifies the set in place

Definition at line 323 of file iov.py.

    def add(self, iov, allow_overlaps=None):
        """
        Add a new iov to the set.
 
        The new iov be combined with existing iovs if possible. After the
        operation the set will contain the minimal amount of separate iovs
        possible to represent all added iovs
 
            >>> a = IoVSet()
            >>> a.add((0, 0, 0, 2))
            >>> a.add((0, 3, 0, 5))
            >>> a.add((0, 8, 0, 9))
            >>> a
            {(0, 0, 0, 5), (0, 8, 0, 9)}
            >>> a.add(IoVSet([(10, 0, 10, 1), (10, 2, 10, -1)]))
            >>> a
            {(0, 0, 0, 5), (0, 8, 0, 9), (10, 0, 10, inf)}
 
        Be aware, by default it's not possible to add overlapping iovs to the set.
        This can be changed either on construction or per `add` call using
        ``allow_overlap``
 
            >>> a.add((0, 2, 0, 3))
            Traceback (most recent call last):
                ...
            ValueError: Overlap between (0, 0, 0, 5) and (0, 2, 0, 3)
            >>> a.add((0, 2, 0, 3), allow_overlaps=True)
            >>> a
            {(0, 0, 0, 5), (0, 8, 0, 9), (10, 0, 10, inf)}
 
        Parameters:
            iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
                set of IoVs to add to this set
            allow_overlaps (bool): Can be used to override global overlap setting
                of this set to allow/restrict overlaps for a single insertion
                operation
 
        Warning:
            This method modifies the set in place
        """
        # check whether we override overlap settings
        if allow_overlaps is None:
            allow_overlaps = self.__allow_overlaps
        # we can add a set to a set :D
        if isinstance(iov, IoVSet):
            for element in iov:
                self.add(element, allow_overlaps)
            return
        # make sure it's actually an IoV, this will raise an error on failure
        if not isinstance(iov, IntervalOfValidity):
            iov = IntervalOfValidity(iov)
        # and now check for all existing iovs ... (but use a copy since we modify the set)
        for existing in list(self.__iovs):
            # if there's an overlap to the new iov
            if (not allow_overlaps) and (existing & iov):
                raise ValueError(f"Overlap between {existing} and {iov}")
            # and if they can be combined to a bigger iov
            combined = existing.union(iov, self.__allow_startone)
            # if we now have a combined iov, remove the one that we were able to
            # combine it with from the existing iovs because we now check
            # against the combined one. Since the only way to add a new iov is
            # this loop we know all previous existing iovs we checked before
            # didn't have a union with this new iov or any other existing iovs
            # so if the just check the remaining iovs against the new combined
            # one we can cascade combine all iovs in one go.
            if combined is not None:
                self.__iovs.remove(existing)
                iov = combined
        # done, we now have a new iov which combines all existing iovs it had an
        # overlap with and we removed the existing iovs so nothing else to do
        # but add the iov back in the list
        self.__iovs.add(iov)
 

clear()

def clear

(

self

)

Clear all iovs from this set

Definition at line 548 of file iov.py.

    def clear(self):
        """Clear all iovs from this set"""
        self.__iovs = {}
 

contains()

def contains	(		self,
			iov
	)

Check if an iov is fully covered by the set

    >>> a = IoVSet([(0,0,2,-1), (5,0,5,-1)])
    >>> a.contains((0,0,1,-1))
    True
    >>> a.contains(IntervalOfValidity(0,0,3,2))
    False
    >>> a.contains(IoVSet([(0,1,1,23), (5,0,5,23)]))
    True
    >>> a.contains(IoVSet([(0,1,1,23), (5,0,6,23)]))
    False
    >>> a.contains((3,0,4,-1))
    False

Parameters:
    iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
        set of IoVs to be checked

Returns:
    True if the full iov or all the iovs in the given set are fully
    present in this set

Definition at line 468 of file iov.py.

    def contains(self, iov):
        """
        Check if an iov is fully covered by the set
 
            >>> a = IoVSet([(0,0,2,-1), (5,0,5,-1)])
            >>> a.contains((0,0,1,-1))
            True
            >>> a.contains(IntervalOfValidity(0,0,3,2))
            False
            >>> a.contains(IoVSet([(0,1,1,23), (5,0,5,23)]))
            True
            >>> a.contains(IoVSet([(0,1,1,23), (5,0,6,23)]))
            False
            >>> a.contains((3,0,4,-1))
            False
 
        Parameters:
            iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
                set of IoVs to be checked
 
        Returns:
            True if the full iov or all the iovs in the given set are fully
            present in this set
        """
        # check if the whole set is in this set: all iovs need to be in here
        if isinstance(iov, IoVSet):
            return all(e in self for e in iov)
        # make sure it's actually an IoV, this will raise an error on failure
        if not isinstance(iov, IntervalOfValidity):
            iov = IntervalOfValidity(iov)
        # and then check all iovs in the set if they cover it
        for existing in self.__iovs:
            if iov - existing is None:
                return True
        return False
 

copy()

def copy

(

self

)

Return a copy of this set

Definition at line 542 of file iov.py.

    def copy(self):
        """Return a copy of this set"""
        copy = IoVSet(allow_overlaps=self.__allow_overlaps, allow_startone=self.__allow_startone)
        copy.__iovs = set(self.__iovs)
        return copy
 

final()

def final

(

self

)

Return the final run covered by this iov set

>>> a = IoVSet([(3,0,3,10), (10,11,10,23), (0,0,2,-1), (5,0,5,-1)])
>>> a.final
(10, 23)

Definition at line 570 of file iov.py.

    def final(self):
        """Return the final run covered by this iov set
 
        >>> a = IoVSet([(3,0,3,10), (10,11,10,23), (0,0,2,-1), (5,0,5,-1)])
        >>> a.final
        (10, 23)
        """
        if not self.__iovs:
            return None
        return max(self.iovs).final
 

first()

def first

(

self

)

Return the first run covered by this iov set

>>> a = IoVSet([(3,0,3,10), (10,11,10,23), (0,0,2,-1), (5,0,5,-1)])
>>> a.first
(0, 0)

Definition at line 558 of file iov.py.

    def first(self):
        """Return the first run covered by this iov set
 
        >>> a = IoVSet([(3,0,3,10), (10,11,10,23), (0,0,2,-1), (5,0,5,-1)])
        >>> a.first
        (0, 0)
        """
        if not self.__iovs:
            return None
        return min(self.iovs).first
 

gaps()

def gaps

(

self

)

Return the gaps in the set. Any area not covered between the first
point of validity and the last

>>> a = IoVSet([(0,0,2,-1)])
>>> a.gaps
{}
>>> b = IoVSet([(0,0,2,-1), (5,0,5,-1)])
>>> b.gaps
{(3, 0, 4, inf)}
>>> c = IoVSet([(0,0,2,-1), (5,0,5,-1), (10,3,10,6)])
>>> c.gaps
{(3, 0, 4, inf), (6, 0, 10, 2)}

Definition at line 582 of file iov.py.

    def gaps(self):
        """Return the gaps in the set. Any area not covered between the first
        point of validity and the last
 
        >>> a = IoVSet([(0,0,2,-1)])
        >>> a.gaps
        {}
        >>> b = IoVSet([(0,0,2,-1), (5,0,5,-1)])
        >>> b.gaps
        {(3, 0, 4, inf)}
        >>> c = IoVSet([(0,0,2,-1), (5,0,5,-1), (10,3,10,6)])
        >>> c.gaps
        {(3, 0, 4, inf), (6, 0, 10, 2)}
        """
        if len(self.__iovs) < 2:
            return IoVSet()
 
        full_range = IoVSet([self.first + self.final])
        return full_range - self
 

intersect()

def intersect	(		self,
			iov
	)

Intersect this set with another set and return a new set
which is valid exactly where both sets have been valid before

    >>> a = IoVSet()
    >>> a.add((0,0,10,-1))
    >>> a.intersect((5,0,20,-1))
    {(5, 0, 10, inf)}
    >>> a.intersect(IoVSet([(0,0,3,-1), (9,0,20,-1)]))
    {(0, 0, 3, inf), (9, 0, 10, inf)}

Parameters:
    iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
        set of IoVs to intersect with this set

Definition at line 439 of file iov.py.

    def intersect(self, iov):
        """Intersect this set with another set and return a new set
        which is valid exactly where both sets have been valid before
 
            >>> a = IoVSet()
            >>> a.add((0,0,10,-1))
            >>> a.intersect((5,0,20,-1))
            {(5, 0, 10, inf)}
            >>> a.intersect(IoVSet([(0,0,3,-1), (9,0,20,-1)]))
            {(0, 0, 3, inf), (9, 0, 10, inf)}
 
        Parameters:
            iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
                set of IoVs to intersect with this set
        """
        if not isinstance(iov, (IoVSet, IntervalOfValidity)):
            iov = IntervalOfValidity(iov)
        if isinstance(iov, IntervalOfValidity):
            iov = IoVSet([iov])
 
        # ok for all combinations a,b from set1 and set2 check the intersection
        # and if not empty add to the result
        result = IoVSet()
        for a, b in product(self.iovs, iov.iovs):
            c = a & b
            if c:
                result.add(c)
        return result
 

iovs()

def iovs

(

self

)

Return the set of valid iovs

Definition at line 553 of file iov.py.

    def iovs(self):
        """Return the set of valid iovs"""
        return self.__iovs
 

overlaps()

def overlaps	(		self,
			iov
	)

Check if the given iov overlaps with this set.

In contrast to `contains` this doesn't require the given iov to be fully
covered. It's enough if the any run covered by the iov is also covered
by this set.

    >>> a = IoVSet([(0,0,2,-1), (5,0,5,-1)])
    >>> a.overlaps((0,0,1,-1))
    True
    >>> a.overlaps(IntervalOfValidity(0,0,3,2))
    True
    >>> a.overlaps(IoVSet([(0,1,1,23), (5,0,5,23)]))
    True
    >>> a.overlaps(IoVSet([(0,1,1,23), (5,0,6,23)]))
    True
    >>> a.overlaps((3,0,4,-1))
    False

Parameters:
    iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
        set of IoVs to be checked

Returns:
    True if the iov or any of the iovs in the given set overlap with any
    iov in this set

Definition at line 504 of file iov.py.

    def overlaps(self, iov):
        """Check if the given iov overlaps with this set.
 
        In contrast to `contains` this doesn't require the given iov to be fully
        covered. It's enough if the any run covered by the iov is also covered
        by this set.
 
            >>> a = IoVSet([(0,0,2,-1), (5,0,5,-1)])
            >>> a.overlaps((0,0,1,-1))
            True
            >>> a.overlaps(IntervalOfValidity(0,0,3,2))
            True
            >>> a.overlaps(IoVSet([(0,1,1,23), (5,0,5,23)]))
            True
            >>> a.overlaps(IoVSet([(0,1,1,23), (5,0,6,23)]))
            True
            >>> a.overlaps((3,0,4,-1))
            False
 
        Parameters:
            iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
                set of IoVs to be checked
 
        Returns:
            True if the iov or any of the iovs in the given set overlap with any
            iov in this set
        """
        if not isinstance(iov, (IoVSet, IntervalOfValidity)):
            iov = IntervalOfValidity(iov)
        if isinstance(iov, IntervalOfValidity):
            iov = IoVSet([iov])
 
        for a, b in product(self.iovs, iov.iovs):
            c = a & b
            if c:
                return True
        return False
 

remove()

def remove	(		self,
			iov
	)

Remove an iov or a set of iovs from this set

After this operation the set will not be valid for the given iov or set
of iovs:

    >>> a = IoVSet()
    >>> a.add((0,0,10,-1))
    >>> a.remove((1,0,1,-1))
    >>> a.remove((5,0,8,5))
    >>> a
    {(0, 0, 0, inf), (2, 0, 4, inf), (8, 6, 10, inf)}
    >>> a.remove(IoVSet([(3,0,3,10), (3,11,3,-1)]))
    >>> a
    {(0, 0, 0, inf), (2, 0, 2, inf), (4, 0, 4, inf), (8, 6, 10, inf)}

Parameters:
    iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
        set of IoVs to remove from this set

Warning:
    This method modifies the set in place

Definition at line 396 of file iov.py.

    def remove(self, iov):
        """Remove an iov or a set of iovs from this set
 
        After this operation the set will not be valid for the given iov or set
        of iovs:
 
            >>> a = IoVSet()
            >>> a.add((0,0,10,-1))
            >>> a.remove((1,0,1,-1))
            >>> a.remove((5,0,8,5))
            >>> a
            {(0, 0, 0, inf), (2, 0, 4, inf), (8, 6, 10, inf)}
            >>> a.remove(IoVSet([(3,0,3,10), (3,11,3,-1)]))
            >>> a
            {(0, 0, 0, inf), (2, 0, 2, inf), (4, 0, 4, inf), (8, 6, 10, inf)}
 
        Parameters:
            iov (Union[IoVSet, IntervalOfValidity, tuple(int)]): IoV or
                set of IoVs to remove from this set
 
        Warning:
            This method modifies the set in place
        """
        # we can remove a set from a set :D
        if isinstance(iov, IoVSet):
            for element in iov:
                self.remove(element)
            return
        # make sure it's actually an IoV, this will raise an error on failure
        if not isinstance(iov, IntervalOfValidity):
            iov = IntervalOfValidity(iov)
        # and subtract the iov from all existing iovs
        for existing in list(self.__iovs):
            delta = existing - iov
            if delta != existing:
                self.__iovs.remove(existing)
                if isinstance(delta, tuple):
                    # got two new iovs, apparently we split the old one
                    for new in delta:
                        self.__iovs.add(new)
                elif delta is not None:
                    self.__iovs.add(delta)
 

Member Data Documentation

__allow_overlaps

__allow_overlaps

private

Whether or not we raise an error on overlaps.

Definition at line 315 of file iov.py.

__allow_startone

__allow_startone

private

Whether or not run 1 will be also considered the first run when combining iovs between experiments.

Definition at line 318 of file iov.py.

__iovs

__iovs

private

The set of iovs.

Definition at line 313 of file iov.py.

---

The documentation for this class was generated from the following file:

• framework/scripts/conditions_db/iov.py