offsetvector.py

Go to the documentation of this file.

# Copyright (C) 2010--2013,2015,2016,2018  Kipp Cannon
#
# This program is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the
# Free Software Foundation; either version 2 of the License, or (at your
# option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
# Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
 
#
# =============================================================================
#
#                                   Preamble
#
# =============================================================================
#
 
 
import itertools
 
 
__author__ = "Kipp Cannon <kipp.cannon@ligo.org>"
from .git_version import date as __date__
from .git_version import version as __version__
 
 
#
# =============================================================================
#
#                                Offset Vector
#
# =============================================================================
#
 
 
class offsetvector(dict):
        """
        Subclass of the dict built-in type for storing mappings of
        instrument to time offset.
 
        Examples:
 
        >>> x = offsetvector({"H1": 0, "L1": 10, "V1": 20})
        >>> x["H1"]
        0
        >>> not any(x.values()) # check for "zero-lag"
        False
        """
        @property
        def refkey(self):
                """
                = min(self)
 
                Raises ValueError if the offsetvector is empty.
                """
                # min() emits ValueError when the list is empty, but it
                # might also emit a ValueError if the comparison operations
                # inside it fail, so we can't simply wrap it in a
                # try/except pair or we might mask genuine failures
                if not self:
                        raise ValueError("offsetvector is empty")
                return min(self)
 
        @property
        def deltas(self):
                """
                Dictionary of relative offsets.  The keys in the result are
                pairs of keys from the offset vector, (a, b), and the
                values are the relative offsets, (offset[b] - offset[a]).
                Raises ValueError if the offsetvector is empty (WARNING:
                this behaviour might change in the future).
 
                Example:
 
                >>> x = offsetvector({"H1": 0, "L1": 10, "V1": 20})
                >>> assert x.deltas == {('H1', 'L1'): 10, ('H1', 'V1'): 20, ('H1', 'H1'): 0}
                >>> y = offsetvector({'H1': 100, 'L1': 110, 'V1': 120})
                >>> y.deltas == x.deltas
                True
 
                Note that the result always includes a "dummy" entry,
                giving the relative offset of self.refkey with respect to
                itself, which is always 0.
 
                See also .fromdeltas().
 
                BUGS:  I think the keys in each tuple should be reversed.
                I can't remember why I put them in the way they are.
                Expect them to change in the future.
                """
                # FIXME:  instead of raising ValueError when the
                # offsetvector is empty this should return an empty
                # dictionary.  the inverse, .fromdeltas() accepts
                # empty dictionaries
                # NOTE:  the arithmetic used to construct the offsets
                # *must* match the arithmetic used by
                # time_slide_component_vectors() so that the results of the
                # two functions can be compared to each other without worry
                # of floating-point round off confusing things.
                refkey = self.refkey
                refoffset = self[refkey]
                return dict(((refkey, key), self[key] - refoffset) for key in self)
 
        def __str__(self, compact = False):
                """
                Return a human-readable string representation of an offset
                vector.
 
                Example:
 
                >>> a = offsetvector({"H1": -10.1234567, "L1": 0.125})
                >>> str(a)
                'H1 = -10.1234567 s, L1 = +0.125 s'
                >>> a.__str__(compact = True)
                'H1=-10.123,L1=0.125'
                """
                if compact:
                        return ",".join(("%s=%.5g" % x) for x in sorted(self.items()))
                return ", ".join(("%s = %+.16g s" % x) for x in sorted(self.items()))
 
        def __repr__(self):
                """
                Return a string representation of the offset vector.
                Running eval() on the result reconstructs the offsetvector.
 
                Example:
 
                >>> a = offsetvector({"H1": -10.1234567, "L1": 0.1})
                >>> b = eval(repr(a))
                >>> b == a
                True
                >>> b is a
                False
                >>> c = offsetvector({"H1": -10.1234567})
                >>> repr(c)
                "offsetvector({'H1': -10.1234567})"
                """
                return "%s(%s)" % (self.__class__.__name__, dict.__repr__(self))
 
        def __abs__(self):
                """
                Returns max(offset) - min(offset).
 
                Example:
 
                >>> abs(offsetvector({"H1": 0.0, "H2": 0.0, "L1": 0.0}))
                0.0
                >>> abs(offsetvector({"H1": 10.0, "H2": 10.0, "L1": 10.0}))
                0.0
                >>> abs(offsetvector({'H1': 10.0, 'L1': 0.0, 'V1': -10.0}))
                20.0
                """
                return max(self.values()) - min(self.values())
 
        def contains(self, other):
                """
                Returns True if offset vector other can be found in self,
                False otherwise.  An offset vector is "found in" another
                offset vector if the latter contains all of the former's
                instruments and the relative offsets among those
                instruments are equal (the absolute offsets need not be).
 
                Example:
 
                >>> a = offsetvector({"H1": 10, "L1": 20, "V1": 30})
                >>> b = offsetvector({"H1": 20, "V1": 40})
                >>> a.contains(b)
                True
 
                Note the distinction between this and the "in" operator:
 
                >>> "H1" in a
                True
                """
                return offsetvector((key, offset) for key, offset in self.items() if key in other).deltas == other.deltas
 
        def normalize(self, **kwargs):
                """
                Adjust the offsetvector so that a particular instrument has
                the desired offset.  All other instruments have their
                offsets adjusted so that the relative offsets are
                preserved.  The instrument to noramlize, and the offset one
                wishes it to have, are provided as a key-word argument.
                The return value is the time slide dictionary, which is
                modified in place.
 
                If more than one key-word argument is provided the keys are
                sorted and considered in order until a key is found that is
                in the offset vector.  The offset vector is normalized to
                that value.  This function is a no-op if no key-word
                argument is found that applies.
 
                Example:
 
                >>> a = offsetvector({"H1": -10, "H2": -10, "L1": -10})
                >>> assert a.normalize(L1 = 0) == offsetvector({'H2': 0, 'H1': 0, 'L1': 0})
                >>> a = offsetvector({"H1": -10, "H2": -10})
                >>> assert a.normalize(L1 = 0, H2 = 5) == offsetvector({'H2': 5, 'H1': 5})
                """
                # FIXME:  should it be performed in place?  if it should
                # be, the should there be no return value?
                for key, offset in sorted(kwargs.items()):
                        if key in self:
                                delta = offset - self[key]
                                for key in self.keys():
                                        self[key] += delta
                                break
                return self
 
        @classmethod
        def fromdeltas(cls, deltas):
                """
                Construct an offsetvector from a dictionary of offset
                deltas as returned by the .deltas attribute.
 
                Example:
 
                >>> x = offsetvector({"H1": 0, "L1": 10, "V1": 20})
                >>> y = offsetvector.fromdeltas(x.deltas)
                >>> y == x
                True
 
                See also .deltas, .fromkeys()
                """
                return cls((key, value) for (refkey, key), value in deltas.items())
 
 
#
# =============================================================================
#
#                                  Utilities
#
# =============================================================================
#
 
 
def component_offsetvectors(offsetvectors, n):
        """
        Given an iterable of offset vectors, return the shortest list of
        the unique n-instrument offset vectors from which all the vectors
        in the input iterable can be constructed.  This can be used to
        determine the minimal set of n-instrument coincs required to
        construct all of the coincs for all of the requested instrument and
        offset combinations in a set of offset vectors.
 
        It is assumed that the coincs for the vector {"H1": 0, "H2": 10,
        "L1": 20} can be constructed from the coincs for the vectors {"H1":
        0, "H2": 10} and {"H2": 0, "L1": 10}, that is only the relative
        offsets are significant in determining if two events are
        coincident, not the absolute offsets.
        """
        #
        # collect unique instrument set / deltas combinations
        #
 
        delta_sets = {}
        for vect in offsetvectors:
                for instruments in itertools.combinations(sorted(vect), n):
                        # NOTE:  the arithmetic used to construct the
                        # offsets *must* match the arithmetic used by
                        # offsetvector.deltas so that the results of the
                        # two can be compared to each other without worry
                        # of floating-point round off confusing things.
                        delta_sets.setdefault(instruments, set()).add(tuple(vect[instrument] - vect[instruments[0]] for instrument in instruments))
 
        #
        # translate into a list of normalized n-instrument offset vectors
        #
 
        return [offsetvector(zip(instruments, deltas)) for instruments, delta_set in delta_sets.items() for deltas in delta_set]