GWDataFind¶
Installation¶
$ python -m pip install gwdatafind
Supported python versions: 2.7, 3.4+.
$ conda install -c conda-forge gwdatafind
Supported python versions: 2.7, 3.5+.
$ apt-get install python3-gwdatafind
Supported python versions: 2.7, 3.4 (Jessie), 3.5 (Stretch), 3.6 (Buster), click here for instructions on how to add the required debian repositories.
$ yum install python-gwdatafind
Supported python versions: 2.7, click here for instructions on how to add the required yum repositories.
$ port install py37-gwdatafind
Supported python versions: 2.7, 3.6+.
Package overview¶
The client library for the LIGO Data Replicator (LDR) service.
The DataFind service allows users to query for the location of Gravitational-Wave Frame (GWF) files containing data from the current gravitational-wave detectors.
This package provides the HTTPConnection and
HTTPSConnection class objects, for connecting to an LDR server
in open and authenticated access modes respectively.
The authenticated HTTPSConnection requires users have a valid X509
certificate that is registered with the server in question.
Quick-start¶
A high-level connect() function is provided that will automatically
select the correct protocol based on the host given, and will attempt to
access any required X509 credentials.
Functions¶
connect([host, port]) |
Open a new connection to a Datafind server |
find_latest(*args, **kwargs) |
Query for the most recent file of a given type. |
find_observatories(*args, **kwargs) |
Query the LDR host for observatories. |
find_times(*args, **kwargs) |
Query the LDR for times for which files are avaliable. |
find_types(*args, **kwargs) |
Query the LDR host for frame types. |
find_url(*args, **kwargs) |
Query the LDR host for a single filename. |
find_urls(*args, **kwargs) |
Find all files of the given type in the [start, end) GPS interval. |
ping(*args, **kwargs) |
Ping the LDR host to test for life. |
Classes¶
HTTPConnection([host, port, timeout, …]) |
Connect to a GWDataFind host using HTTP. |
HTTPSConnection([host, port]) |
Connect to a GWDataFind host using HTTPS. |
See Also¶
gwdatafind.utils Module¶
Utilities for the GW datafind service
Functions¶
file_segment(filename) |
Return the data segment for a filename following LIGO-T050017. |
filename_metadata(filename) |
Return metadata parsed from a filename following LIGO-T050017 |
find_credential() |
Locate X509 certificate and key files. |
get_default_host() |
Returns the default host as stored in the ${LIGO_DATAFIND_SERVER} |
validate_proxy(path) |
Validate an X509 proxy certificate file. |
Migrating from glue.datafind¶
This document provides some basic instructions on how to update code written
to use glue.datafind to using gwdatafind.
Renamed objects¶
The table below summarise all renamings between glue.datafind and
gwdatafind.
glue.datafind name |
gwdatafind name |
|---|---|
GWDataFindHTTPConnection |
HTTPConnection |
GWDataFindHTTPSConnection |
HTTPSConnection |
GWDataFindHTTPConnection.find_frame |
HTTPConnection.find_url |
GWDataFindHTTPConnection.find_frame_urls |
HTTPConnection.find_urls |
Query output type¶
glue.datafind returns list of URLs as a glue.lal.Cache of
lal.CacheEntry objects.
gwdatafind returns simple lists of str.
You can translate the new form back to the old easily:
from glue.lal import Cache
cache = Cache.from_urls(urls)
Creating a connection¶
glue.datafind provided no convenience methods for opening a new
connection, so you probably wrote your own function that stripped the port
number from the server name, and handled HTTP/HTTPS manually.
With gwdatafind, you can just use the gwdatafind.connect() method to
handle that:
>>> from gwdatafind import connect
>>> connection = connect()
or if you know the server URL:
>>> connection = connect('datafind.server.url:443')
Simplified single calls¶
If you are only interested in a single query to a single server (the typical use case), you can utilise one of the new top-level functions. So, instead of:
>>> from glue.datafind import GWDataFindHTTPConnection
>>> connection = GWDataFindHTTPConnection()
>>> cache = connection.find_frame_urls(...)
you can just use:
>>> from gwdatafind import find_urls
>>> urls = find_urls(...)
The arguments and syntax for find_urls() is the same as that of the
old glue.datafind.GWDataFindHTTPConnection.find_frame_urls() method.
Similar top-level functions exist for
ping(),
find_observatories(),
find_types(),
find_times(),
find_url(),
find_latest(), and
find_urls()
Command-line usage¶
The lscsoft-glue package provides the
gw_data_find script, used to perform queries from the command-line.
gwdatafind provides an identical interface via Python module execution (python -m).
To migrate, replace gw_data_find with python -m gwdatafind.