Class LigolwSegments
source code
object --+
|
set --+
|
LigolwSegments
An interface shim between code that makes use of segments in
glue.segments form, and LIGO Light-Weight XML I/O code.
This class is "attached" to an XML document object, at which
time it parses and extracts the segment lists from the document, and
clears the document's segment tables (preventing a second LigolwSegments
object from being meaningfully attached to the same document). When the
application is finished manipulating the segment lists, they can be
inserted into the XML document at which time the contents of the
LigolwSegments object are cleared (preventing any further
manipulations).
This class is a subclass of the Python set builtin. Each element of
the set is a LigolwSegmentList instance describing one of the segment
lists in the original XML document.
This class may be used as a context manager to automate the
replacement of segments back into the XML document, including in the
event of an untrapped exception. When used as a context manager, the
process parameter of the .__init__() method is not optional.
Example:
>>> import sys
>>> from glue.segments import *
>>> from lal import LIGOTimeGPS
>>> from glue.ligolw import ligolw, lsctables
>>> xmldoc = ligolw.Document()
>>> xmldoc.appendChild(ligolw.LIGO_LW())
<glue.ligolw.ligolw.LIGO_LW object at ...>
>>> process = lsctables.Process(process_id = lsctables.ProcessTable.get_next_id())
>>> with LigolwSegments(xmldoc, process) as xmlsegments:
... h1segs = segmentlist([segment(LIGOTimeGPS(0), LIGOTimeGPS(10))])
... xmlsegments.insert_from_segmentlistdict({"H1": h1segs}, "test")
... l1segs = h1segs.shift(5)
... xmlsegments.add(LigolwSegmentList(active = l1segs, valid = segmentlist([segment(-infinity(), infinity())]), instruments = set(["L1"]), name = "test"))
>>> xmldoc.write(sys.stdout)
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE LIGO_LW SYSTEM "http://ldas-sw.ligo.caltech.edu/doc/ligolwAPI/html/ligolw_dtd.txt">
<LIGO_LW>
<Table Name="segment_definer:table">
<Column Type="ilwd:char" Name="segment_definer:process_id"/>
<Column Type="ilwd:char" Name="segment_definer:segment_def_id"/>
<Column Type="lstring" Name="segment_definer:ifos"/>
<Column Type="lstring" Name="segment_definer:name"/>
<Column Type="int_4s" Name="segment_definer:version"/>
<Column Type="lstring" Name="segment_definer:comment"/>
<Stream Delimiter="," Type="Local" Name="segment_definer:table">
"process:process_id:0","segment_definer:segment_def_id:0","H1","test",,,
"process:process_id:0","segment_definer:segment_def_id:1","L1","test",,,
</Stream>
</Table>
<Table Name="segment_summary:table">
<Column Type="ilwd:char" Name="segment_summary:process_id"/>
<Column Type="ilwd:char" Name="segment_summary:segment_sum_id"/>
<Column Type="int_4s" Name="segment_summary:start_time"/>
<Column Type="int_4s" Name="segment_summary:start_time_ns"/>
<Column Type="int_4s" Name="segment_summary:end_time"/>
<Column Type="int_4s" Name="segment_summary:end_time_ns"/>
<Column Type="ilwd:char" Name="segment_summary:segment_def_id"/>
<Column Type="lstring" Name="segment_summary:comment"/>
<Stream Delimiter="," Type="Local" Name="segment_summary:table">
"process:process_id:0","segment_summary:segment_sum_id:0",4294967295,4294967295,2147483647,4294967295,"segment_definer:segment_def_id:1",,
</Stream>
</Table>
<Table Name="segment:table">
<Column Type="ilwd:char" Name="segment:process_id"/>
<Column Type="ilwd:char" Name="segment:segment_id"/>
<Column Type="int_4s" Name="segment:start_time"/>
<Column Type="int_4s" Name="segment:start_time_ns"/>
<Column Type="int_4s" Name="segment:end_time"/>
<Column Type="int_4s" Name="segment:end_time_ns"/>
<Column Type="ilwd:char" Name="segment:segment_def_id"/>
<Stream Delimiter="," Type="Local" Name="segment:table">
"process:process_id:0","segment:segment_id:0",0,0,10,0,"segment_definer:segment_def_id:0",
"process:process_id:0","segment:segment_id:1",5,0,15,0,"segment_definer:segment_def_id:1"
</Stream>
</Table>
</LIGO_LW>
>>> xmlsegments = LigolwSegments(xmldoc)
>>> xmlsegments.get_by_name("test")
{u'H1': [segment(LIGOTimeGPS(0, 0), LIGOTimeGPS(10, 0))], u'L1': [segment(LIGOTimeGPS(5, 0), LIGOTimeGPS(15, 0))]}
>>> xmlsegments.get_by_name("wrong name")
Traceback (most recent call last):
...
KeyError: "no segmentlists named 'wrong name'"
NOTE: the process of extracting and re-inserting the contents of the
segment tables will, in general, randomize the IDs assigned to the rows
of these tables. If there are references to segment, segment_summary, or
segment_definer row IDs in other tables in the document, those references
will be broken by this process.
|
|
|
|
|
|
|
new empty set object
|
__init__(self,
xmldoc,
process=None)
x.__init__(...) initializes x; see help(type(x)) for signature |
source code
|
|
|
|
|
|
|
finalize(self,
process_row=None)
Restore the LigolwSegmentList objects to the XML tables in
preparation for output. |
source code
|
|
|
|
get_by_name(self,
name,
clip_to_valid=False)
Retrieve the active segmentlists whose name equals name. |
source code
|
|
|
|
insert_from_segmentlistdict(self,
seglists,
name,
version=None,
comment=None)
Insert the segments from the segmentlistdict object seglists as a new
list of "active" segments into this LigolwSegments object. |
source code
|
|
|
|
insert_from_segwizard(self,
fileobj,
instruments,
name,
version=None,
comment=None)
Parse the contents of the file object fileobj as a segwizard-format
segment list, and insert the result as a new list of
"active" segments into this LigolwSegments object. |
source code
|
|
|
|
optimize(self)
Identifies segment lists that differ only in their instruments ---
they have the same valid and active segments, the same name, version
and the same comment --- and then deletes all but one of them,
leaving just a single list having the union of the instruments. |
source code
|
|
|
|
|
|
Inherited from set:
__and__,
__cmp__,
__contains__,
__eq__,
__ge__,
__getattribute__,
__gt__,
__iand__,
__ior__,
__isub__,
__iter__,
__ixor__,
__le__,
__len__,
__lt__,
__ne__,
__new__,
__or__,
__rand__,
__reduce__,
__repr__,
__ror__,
__rsub__,
__rxor__,
__sizeof__,
__sub__,
__xor__,
add,
clear,
copy,
difference,
difference_update,
discard,
intersection,
intersection_update,
isdisjoint,
issubset,
issuperset,
pop,
remove,
symmetric_difference,
symmetric_difference_update,
union,
update
Inherited from object:
__delattr__,
__format__,
__reduce_ex__,
__setattr__,
__str__,
__subclasshook__
|
|
Inherited from set:
__hash__
|
|
Inherited from object:
__class__
|
__init__(self,
xmldoc,
process=None)
(Constructor)
| source code
|
x.__init__(...) initializes x; see help(type(x)) for signature
- Returns: new empty set object
- Overrides:
object.__init__
- (inherited documentation)
|
|
Coalesce the segment lists. Returns self.
|
|
Restore the LigolwSegmentList objects to the XML tables in preparation
for output. All segments from all segment lists are inserted into the
tables in time order, but this is NOT behaviour external applications
should rely on. This is done simply in the belief that it might assist in
constructing well balanced indexed databases from the resulting files.
If that proves not to be the case, or for some reason this behaviour
proves inconvenient to preserve, then it might be discontinued without
notice. You've been warned.
|
get_by_name(self,
name,
clip_to_valid=False)
| source code
|
Retrieve the active segmentlists whose name equals name. The result is
a segmentlistdict indexed by instrument. All segmentlist objects within
it will be copies of the contents of this object, modifications will not
affect the contents of this object. If clip_to_valid is True then the
segmentlists will be intersected with their respective intervals of
validity, otherwise they will be the verbatim active segments.
NOTE: the intersection operation required by clip_to_valid will yield
undefined results unless the active and valid segmentlist objects are
coalesced.
|
insert_from_segmentlistdict(self,
seglists,
name,
version=None,
comment=None)
| source code
|
Insert the segments from the segmentlistdict object seglists as a new
list of "active" segments into this LigolwSegments object. The
dictionary's keys are assumed to provide the instrument name for each
segment list. A new entry will be created in the segment_definer table
for the segment lists, and the dictionary's keys, the name, and comment
will be used to populate the entry's metadata.
|
insert_from_segwizard(self,
fileobj,
instruments,
name,
version=None,
comment=None)
| source code
|
Parse the contents of the file object fileobj as a segwizard-format
segment list, and insert the result as a new list of "active"
segments into this LigolwSegments object. A new entry will be created in
the segment_definer table for the segment list, and instruments, name and
comment are used to populate the entry's metadata. Note that the
"valid" segments are left empty, nominally indicating that
there are no periods of validity. Returns the newly created
LigolwSegmentList object.
|
|
Sort the segment lists. The optional args are passed to the .sort()
methods of the segment lists. This can be used to control the sort order
by providing an alternate comparison function (the default is to sort all
lists by segment start time with ties broken by end time).
|