__init__.py.in 3.43 KB
Newer Older
Kipp Cannon's avatar
Kipp Cannon committed
1
# Copyright (C) 2006,2007,2009,2011,2013,2016,2017  Kipp Cannon
kipp's avatar
kipp committed
2 3 4
#
# 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
duncan's avatar
duncan committed
5
# Free Software Foundation; either version 3 of the License, or (at your
kipp's avatar
kipp committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
# 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
#
# =============================================================================
23 24
#

kipp's avatar
kipp committed
25
"""
Kipp Cannon's avatar
Kipp Cannon committed
26 27 28 29 30 31 32 33 34 35 36 37
DOM-like library for handling LIGO Light Weight XML files.  For more
information on the Python DOM specification and SAX document content
handlers, please refer to the Python standard library reference and the
documentation it links to.

Here is a brief tutorial for a common use case:  load a LIGO Light-Weight
XML document containing tabular data complying with the LSC table
definitions, access rows in the tables including the use of ID-based cross
references, modify the contents of a table, and finally write the document
back to disk.  Please see the documentation for the modules, classes,
functions, and methods shown below for more information.

38 39 40
Example:

>>> # import modules
41 42 43
>>> from ligo.lw import ligolw
>>> from ligo.lw import lsctables
>>> from ligo.lw import utils as ligolw_utils
44 45 46 47 48 49 50
>>>
>>> # define a content handler
>>> class LIGOLWContentHandler(ligolw.LIGOLWContentHandler):
... 	pass
...
>>> lsctables.use_in(LIGOLWContentHandler)
>>>
51 52
>>> # load a document.  gzip'ed files are auto-detected
>>> filename = "demo.xml.gz"
53
>>> xmldoc = ligolw_utils.load_filename(filename, contenthandler = LIGOLWContentHandler, verbose = True)
54 55 56
>>> 
>>> # retrieve the process and sngl_inspiral tables.  these are list-like
>>> # objects of rows.  the row objects' attributes are the column names
57 58
>>> process_table = lsctables.ProcessTable.get_table(xmldoc)
>>> sngl_inspiral_table = lsctables.SnglInspiralTable.get_table(xmldoc)
59 60 61 62 63 64 65 66 67 68 69 70 71
>>> 
>>> # fix the mtotal column in the sngl_inspiral table
>>> for row in sngl_inspiral_table:
...	row.mtotal = row.mass1 + row.mass2
...
>>> # construct a look-up table mapping process_id to row in process table
>>> index = dict((row.process_id, row) for row in process_table)
>>> 
>>> # for each trigger in the sngl_inspiral table, print the name of the user
>>> # who ran the job that produced it, the computer on which the job ran, and
>>> # the GPS end time of the trigger
>>> for row in sngl_inspiral_table:
...	process = index[row.process_id]
72
...	print "%s@%s: %s s" % (process.username, process.node, str(row.end))
73 74
...
>>> # write document.  must explicitly state whether or not the file is to be
75
>>> # gzip compressed
76
>>> ligolw_utils.write_filename(xmldoc, filename, compress = 'gz' if filename.endswith(".gz") else False, verbose = True)
kipp's avatar
kipp committed
77 78
"""

79

80
__author__ = "Kipp Cannon <kipp.cannon@ligo.org>"
Kipp Cannon's avatar
Kipp Cannon committed
81
__version__ = "@VERSION@"
82
__date__ = "@DATE@"
83 84 85


__all__ = [
86 87 88
	"__author__",
	"__date__",
	"__version__",
89
	"array",
Kipp Cannon's avatar
Kipp Cannon committed
90 91
	"ilwd",
	"ligolw",
92
	"lsctables",
Kipp Cannon's avatar
Kipp Cannon committed
93 94 95
	"param",
	"table",
	"types",
96 97
	"utils"
]