instrumentsproperty

class igwn_ligolw.lsctables.instrumentsproperty(name)

Bases: object

Methods Summary

get(instruments)	Parse the values stored in the "ifos" and "instruments" columns found in many tables.
set(instruments)	Convert an iterable of instrument names into a value suitable for storage in the "ifos" or "instruments" columns found in many tables.

Methods Documentation

static get(instruments)

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.

If the input is None, then the output is None. Otherwise, the input is split on “,”, the resulting strings stripped of leading and trailing whitespace, and the sequence of non-zero length strings that remain is returned as a set (orderless sequence, with unique elements).

NOTE: in the past, many tools relied on the convention that instrument names be exactly 2 characters long, and so sets of instruments were represented by simply concatenating the names as there was no ambiguity in how to split the result back into a collection of names. For a while, some tools encoded sets of instrument names by delimiting them with a “+” character. This decoder used to support all of these encodings, including the modern “,”-delimited encoding, by using a complex heuristic set of rules to auto-select the correct decode algorithm. Because this operation is performend an enormous number of times when processing typical documents, this eventually proved to be a significant performance burden. For this reason, this code now only supports the “,”-delimited encoding. For over a decade, the corresponding encoder in this library has only generated documents using the “,”-delimited encoding, so there should no longer be any documents in active use that rely on one of the older encodings. However, if you find yourself trying to read a very old document be aware that instrument name sets stored in the document might not be decoded the way the original tool that wrote the document intended, and you should be aware of the possible need to do some format translation. There will be no warning or error message: documents using obsolete encodings will appear to be valid documents, the strings will simply be mistaken for unusual instrument names, as shown below in some examples.

Example:

>>> assert instrumentsproperty.get(None) is None
>>> assert instrumentsproperty.get("") == set([])
>>> assert instrumentsproperty.get("  ,  ,,") == set([])
>>> assert instrumentsproperty.get("H1") == set(['H1'])
>>> assert instrumentsproperty.get("H1,") == set(['H1'])
>>> assert instrumentsproperty.get("H1,L1") == set(['H1', 'L1'])
>>> assert instrumentsproperty.get("H1L1") == set(['H1L1'])
>>> assert instrumentsproperty.get("H1+L1") == set(['H1+L1'])

static set(instruments)

Convert an iterable of instrument names into a value suitable for storage in the “ifos” or “instruments” columns found in many tables. This function is mostly for internal use by the .instruments properties of the corresponding row classes. The input must be None or an iterable of zero or more instrument names, none of which may be zero-length, contain whitespace, or contain “,” 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.

NOTE: for performance reasons, because of the large number of times this operation is performed when processing a typical document, very little error checking is performed. If any of the instrument names fail to meet the criteria listed above, that fact will typically go unnoticed. The document that results will be decodable, under no circumstances will an unreadable document be generated, but what form the decoded instruments string takes is undefined.

Example:

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