A Python object representing one line in a LAL cache file.
The LAL cache format is defined elsewhere, and what follows is meant only to be informative, not an official specification. Each line in a LAL cache identifies a single file, and the line consists of five columns of white-space delimited text.
The first column, "observatory", generally stores the name of an observatory site or one or more instruments (preferably delimited by ",", but often there is no delimiter between instrument names in which case they should be 2 characters each).
The second column, "description", stores a short string tag that is usually all capitals with "_" separating components, in the style of the description part of the LIGO-Virgo frame filename format.
The third and fourth columns store the start time and duration in GPS seconds of the interval spanned by the file identified by the cache line. When the file does not start on an integer second or its duration is not an integer number of seconds, the conventions of the LIGO-Virgo frame filename format apply.
The fifth (last) column stores the file's URL.
The values for these columns are stored in the .observatory, .description, .segment and .url attributes of instances of this class, respectively. The .segment attribute stores a ligo.segments.segment object describing the interval spanned by the file. Any of these attributes except the URL is allowed to be None.
Example (parse a string):
c = CacheEntry("H1 S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1-815901601-576.xml") c.scheme
'file'
c.host
'localhost'
Example (one-liners to read and write a cache file):
import os filename = "874000000-20000.cache"
inname = os.path.join(os.environ.get("LAL_TEST_SRCDIR", "."), filename)
cache = list(map(CacheEntry, open(inname)))
print(*cache, sep = "\\n", file = open(filename + ".new", "w"))
Example (extract segmentlist dictionary from LAL cache):
from ligo import segments seglists = segments.segmentlistdict() for cacheentry in cache:
... seglists |= cacheentry.segmentlistdict ...
NOTE: the CacheEntry type defines a comparison operation and a .__hash__() implementation, both of which disregard the URL. That is, if two CacheEntry objects differ only by URL and otherwise have same metadata, they are considered to be redundant copies of the same data. For example, uniquification with a set() will retain only one redundant copy, selected at random.
x = CacheEntry("H1 S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1-815901601-576.xml") y = CacheEntry("H1 S5 815901601 576.5 gsiftp://data.server.org/bigpileofdata/H1-815901601-576.xml") x == y
True
len(set((x, y)))
1
NOTE: this is a pure Python object providing an alternative representation of the contents of a LAL cache file to the C implementation in the LAL library proper. The two are not interchangeable.
See also:
ligo.segments.utils..fromlalcache()
Inherits object.
Public Member Functions | |
def | __init__ (self, *args, **kwargs) |
Intialize a CacheEntry object. More... | |
def | __str__ (self) |
Convert the CacheEntry to a string in the format of a line in a LAL cache. More... | |
def | __lt__ (self, other) |
Compare two CacheEntry objects by observatory, then description, then segment. More... | |
def | __eq__ (self, other) |
Compare two CacheEntry objects by observatory, then description, then segment. More... | |
def | __hash__ (self) |
CacheEntry objects are hashed by the tuple (observatory, description, segment), i.e., the URL is disregarded. More... | |
def | url (self) |
The cache entry's URL. More... | |
def | url (self, url) |
def | segmentlistdict (self) |
A segmentlistdict object describing the instruments and time spanned by this CacheEntry. More... | |
def | from_T050017 (cls, url, coltype=LIGOTimeGPS) |
Parse a URL in the style of T050017-00 into a CacheEntry. More... | |
Data Fields | |
observatory | |
description | |
segment | |
url | |
path | |
def lal.utils.cache.CacheEntry.__init__ | ( | self, | |
* | args, | ||
** | kwargs | ||
) |
Intialize a CacheEntry object.
The arguments can take two forms: a single string argument, which is interpreted and parsed as a line from a LAL cache file, or four arguments used to explicitly initialize the observatory, description, segment and URL in that order. When parsing a single line of text from a LAL cache, an optional key-word argument "coltype" can be provided to set the type the start and durations are parsed as. The default is lal.LIGOTimeGPS.
Example:
c = CacheEntry("H1", "S5", segments.segment(815901601, 815902177.5), "file://localhost/home/kipp/tmp/1/H1-815901601-576.xml") print(c.segment)
[815901601 ... 815902177.5)
print(str(c))
H1 S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1-815901601-576.xml
c = CacheEntry("H1 S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1-815901601-576.xml") print(c.segment)
[815901601 ... 815902177.5)
print(CacheEntry("H1 S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1-815901601-576.xml", coltype = float).segment)
[815901601.0 ... 815902177.5)
See also the .from_T050017() class method for an alternative initialization mechanism.
def lal.utils.cache.CacheEntry.__str__ | ( | self | ) |
Convert the CacheEntry to a string in the format of a line in a LAL cache.
Used to write the CacheEntry to a file.
Example:
c = CacheEntry("H1 S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1-815901601-576.xml") str(c)
'H1 S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1-815901601-576.xml'
def lal.utils.cache.CacheEntry.__lt__ | ( | self, | |
other | |||
) |
Compare two CacheEntry objects by observatory, then description, then segment.
CacheEntry objects that have different URLs but for which all other metadata are the same are considered to be equivalent. If two entries differ only by their URL, they are considered to be redundant copies of the same data, and by comparing them as equal the Python sort operation (which is a stable sort) will preserve their relative order. By preserving the order of redundant copies, we allow the preference for the order in which redundant copies are to be attempted to be conveyed by their order in the list, and preserved.
def lal.utils.cache.CacheEntry.__eq__ | ( | self, | |
other | |||
) |
Compare two CacheEntry objects by observatory, then description, then segment.
CacheEntry objects that have different URLs but for which all other metadata are the same are considered to be equivalent. If two entries differ only by their URL, they are considered to be redundant copies of the same data, and by comparing them as equal the Python sort operation (which is a stable sort) will preserve their relative order. By preserving the order of redundant copies, we allow the preference for the order in which redundant copies are to be attempted to be conveyed by their order in the list, and preserved.
def lal.utils.cache.CacheEntry.__hash__ | ( | self | ) |
CacheEntry objects are hashed by the tuple (observatory, description, segment), i.e., the URL is disregarded.
def lal.utils.cache.CacheEntry.url | ( | self | ) |
def lal.utils.cache.CacheEntry.segmentlistdict | ( | self | ) |
A segmentlistdict object describing the instruments and time spanned by this CacheEntry.
A new object is constructed each time this attribute is accessed (segments are immutable so there is no reason to try to share a reference to the CacheEntry's internal segment; modifications of one would not be reflected in the other anyway).
Example:
c = CacheEntry("H1 S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1-815901601-576.xml") c.segmentlistdict['H1']
[segment(LIGOTimeGPS(815901601, 0), LIGOTimeGPS(815902177, 500000000))]
The "observatory" column of the cache entry, which is frequently used to store instrument names, is parsed into instrument names for the dictionary keys using the same rules as ligo.lw.lsctables.instrumentsproperty.get().
Example:
c = CacheEntry("H1H2, S5 815901601 576.5 file://localhost/home/kipp/tmp/1/H1H2-815901601-576.xml") c.segmentlistdict['H1H2']
[segment(LIGOTimeGPS(815901601, 0), LIGOTimeGPS(815902177, 500000000))]
def lal.utils.cache.CacheEntry.from_T050017 | ( | cls, | |
url, | |||
coltype = LIGOTimeGPS |
|||
) |
Parse a URL in the style of T050017-00 into a CacheEntry.
The T050017-00 file name format is, essentially,
observatory-description-start-duration.extension
Example:
c = CacheEntry.from_T050017("file://localhost/data/node144/frames/S5/strain-L2/LLO/L-L1_RDS_C03_L2-8365/L-L1_RDS_C03_L2-836562330-83.gwf") c.observatory
'L'
c.host
'localhost'
os.path.basename(c.path)
'L-L1_RDS_C03_L2-836562330-83.gwf'