Module lsctables

Construct a pre-defined LSC table. The optional columns argument is a sequence of the names of the columns the table should be constructed with. If columns = None, then the table is constructed with all valid columns (use columns = [] to create a table with no columns).

Example:

>>> import sys
>>> tbl = New(ProcessTable, [u"process_id", u"start_time", u"end_time", u"comment"])
>>> tbl.write(sys.stdout)       # doctest: +NORMALIZE_WHITESPACE
<Table Name="process:table">
        <Column Type="ilwd:char" Name="process:process_id"/>
        <Column Type="int_4s" Name="process:start_time"/>
        <Column Type="int_4s" Name="process:end_time"/>
        <Column Type="lstring" Name="process:comment"/>
        <Stream Delimiter="," Type="Local" Name="process:table">
        </Stream>
</Table>

Convert an iterable of instrument names into a value suitable for storage in the "ifos" column found in many tables. This function is mostly for internal use by the .instruments properties of the corresponding row classes. The input can be None or an iterable of zero or more instrument names, none of which may be zero-length, consist exclusively of spaces, or contain "," or "+" characters. The output is a single string containing the unique instrument names concatenated using "," as a delimiter. instruments will only be iterated over once and so can be a generator expression. Whitespace is allowed in instrument names but might not be preserved. Repeated names will not be preserved.

NOTE: in the special case that there is 1 instrument name in the iterable and it has an even number of characters > 2 in it, the output will have a "," appended in order to force instrumentsproperty.get() to parse the string back into a single instrument name. This is a special case included temporarily to disambiguate the encoding until all codes have been ported to the comma-delimited encoding. This behaviour will be discontinued at that time. DO NOT WRITE CODE THAT RELIES ON THIS! You have been warned.

Example:

>>> print(instrumentsproperty.set(None))
None
>>> instrumentsproperty.set(())
u''
>>> instrumentsproperty.set((u"H1",))
u'H1'
>>> instrumentsproperty.set((u"H1",u"H1",u"H1"))
u'H1'
>>> instrumentsproperty.set((u"H1",u"L1"))
u'H1,L1'
>>> instrumentsproperty.set((u"SWIFT",))
u'SWIFT'
>>> instrumentsproperty.set((u"H1L1",))
u'H1L1,'

Parse the values stored in the "ifos" and "instruments" columns found in many tables. This function is mostly for internal use by the .instruments properties of the corresponding row classes. The mapping from input to output is as follows (rules are applied in order):

input is None --> output is None

input contains "," --> output is set of strings split on "," with leading and trailing whitespace stripped from each piece and empty strings removed from the set

input contains "+" --> output is set of strings split on "+" with leading and trailing whitespace stripped from each piece and empty strings removed from the set

else, after stripping input of leading and trailing whitespace,

input has an even length greater than two --> output is set of two-character pieces

input is a non-empty string --> output is a set containing input as single value

else output is an empty set.

NOTE: the complexity of this algorithm is a consequence of there being several conventions in use for encoding a set of instruments into one of these columns; it has been proposed that L.L.W. documents standardize on the comma-delimited variant of the encodings recognized by this function, and for this reason the inverse function, instrumentsproperty.set(), implements that encoding only.

NOTE: to force a string containing an even number of characters to be interpreted as a single instrument name and not to be be split into two-character pieces, add a "," character to the end to force the comma-delimited decoding to be used. instrumentsproperty.set() does this for you.

Example:

>>> print(instrumentsproperty.get(None))
None
>>> instrumentsproperty.get(u"")
set([])
>>> instrumentsproperty.get(u"  ,  ,,")
set([])
>>> instrumentsproperty.get(u"H1")
set([u'H1'])
>>> instrumentsproperty.get(u"SWIFT")
set([u'SWIFT'])
>>> instrumentsproperty.get(u"H1L1")
set([u'H1', u'L1'])
>>> instrumentsproperty.get(u"H1L1,")
set([u'H1L1'])
>>> instrumentsproperty.get(u"H1,L1")
set([u'H1', u'L1'])
>>> instrumentsproperty.get(u"H1+L1")
set([u'H1', u'L1'])

For each class in the list, if the .next_id attribute is not None (meaning the table has an ID generator associated with it), set .next_id to 0. This has the effect of reseting the ID generators, and is useful in applications that process multiple documents and add new rows to tables in those documents. Calling this function between documents prevents new row IDs from growing continuously from document to document. There is no need to do this, it's purpose is merely aesthetic, but it can be confusing to open a document and find process ID 300 in the process table and wonder what happened to the other 299 processes.

Example:

>>> reset_next_ids(TableByName.values())

Modify ContentHandler, a sub-class of glue.ligolw.LIGOLWContentHandler, to cause it to use the Table classes defined in this module when parsing XML documents.

Example:

>>> from glue.ligolw import ligolw
>>> class MyContentHandler(ligolw.LIGOLWContentHandler):
...     pass
...
>>> use_in(MyContentHandler)
<class 'glue.ligolw.lsctables.MyContentHandler'>

TableByName

Value:

{'coinc_definer': <class 'glue.ligolw.lsctables.CoincDefTable'>, 'coinc_event': <class 'glue.ligolw.lsctables.CoincTable'>, 'coinc_event_map': <class 'glue.ligolw.lsctables.CoincMapTable'>, 'coinc_inspiral': <class 'glue.ligolw.lsctables.CoincInspiralTable'>, 'coinc_ringdown': <class 'glue.ligolw.lsctables.CoincRingdownTable'>, 'dq_list': <class 'glue.ligolw.lsctables.DQSpecListTable'>, 'experiment': <class 'glue.ligolw.lsctables.ExperimentTable'>, 'experiment_map': <class 'glue.ligolw.lsctables.ExperimentMapTable'>, ...