pycbc.io package

Submodules

pycbc.io.gracedb module

Class and function for use in dealing with GraceDB uploads

class pycbc.io.gracedb.CandidateForGraceDB(coinc_ifos, ifos, coinc_results, **kwargs)

Bases: object

This class provides an interface for uploading candidates to GraceDB.

save(fname)

Write a file representing this candidate in a LIGOLW XML format compatible with GraceDB.

Parameters:

fname (str) – Name of file to write to disk.

upload(fname, gracedb_server=None, testing=True, extra_strings=None, search='AllSky', labels=None)

Upload this candidate to GraceDB, and annotate it with a few useful plots and comments.

Parameters:

• fname (str) – The name to give the xml file associated with this trigger

• gracedb_server (string, optional) – URL to the GraceDB web API service for uploading the event. If omitted, the default will be used.

• testing (bool) – Switch to determine if the upload should be sent to gracedb as a test trigger (True) or a production trigger (False).

• search (str) – String going into the “search” field of the GraceDB event.

• labels (list) – Optional list of labels to tag the new event with.

pycbc.io.gracedb.gracedb_tag_with_version(gracedb, event_id)

Add a GraceDB log entry reporting PyCBC’s version and install location.

pycbc.io.hdf module

Convenience classes for accessing hdf5 trigger files

class pycbc.io.hdf.DataFromFiles(filelist, group=None, columnlist=None, filter_func=None)

Bases: object

get_column(col)

Loop over files getting the requested dataset values from each

Parameters:

col (string) – Name of the dataset to be returned

Returns:

Values from the dataset, filtered if requested and concatenated in order of file list

Return type:

numpy array

class pycbc.io.hdf.DictArray(data=None, files=None, groups=None)

Bases: object

Utility for organizing sets of arrays of equal length.

Manages a dictionary of arrays of equal length. This can also be instantiated with a set of hdf5 files and the key values. The full data is always in memory and all operations create new instances of the DictArray.

remove(idx)

Return a new DictArray that does not contain the indexed values

save(outname)

select(idx)

Return a new DictArray containing only the indexed values

class pycbc.io.hdf.FileData(fname, group=None, columnlist=None, filter_func=None)

Bases: object

close()

get_column(col)

Method designed to be analogous to legacy pylal.SnglInspiralUtils functionality

Parameters:

col (string) – Name of the dataset to be returned

Returns:

Values from the dataset, filtered if requested

Return type:

numpy array

property mask

Create a mask implementing the requested filter on the datasets

Returns:

True for dataset indices to be returned by the get_column method

Return type:

array of Boolean

class pycbc.io.hdf.ForegroundTriggers(coinc_file, bank_file, sngl_files=None, n_loudest=None, group='foreground', has_inc=True)

Bases: object

get_active_segments()

get_bankfile_array(variable)

get_coincfile_array(variable)

get_end_time()

get_ifos()

Returns:

List of lists of ifo names involved in each foreground event. Ifos will be listed in the same order as self.ifos

Return type:

ifos_list

get_snglfile_array_dict(variable)

property sort_arr

property template_id

to_coinc_hdf_object(file_name)

to_coinc_xml_object(file_name)

property trig_id

class pycbc.io.hdf.HFile(name, mode='r', driver=None, libver=None, userblock_size=None, swmr=False, rdcc_nslots=None, rdcc_nbytes=None, rdcc_w0=None, track_order=None, fs_strategy=None, fs_persist=False, fs_threshold=1, fs_page_size=None, page_buf_size=None, min_meta_keep=0, min_raw_keep=0, locking=None, alignment_threshold=1, alignment_interval=1, meta_block_size=None, **kwds)

Bases: HGroup, File

Low level extensions to the capabilities of reading an hdf5 File

select(fcn, *args, chunksize=1000000, derived=None, group='', return_data=True, premask=None)

Return arrays from an hdf5 file that satisfy the given function

Parameters:

• fcn (a function) – A function that accepts the same number of argument as keys given and returns a boolean array of the same length.

• args (strings) – A variable number of strings that are keys into the hdf5. These must refer to arrays of equal length.

• chunksize ({10**6, int}, optional) – Number of elements to read and process at a time.

• derived (dictionary) – Dictionary keyed on argument name (must be given in args), values are a tuple of: the function to be computed, and the required datasets. The function must take in a dictionary keyed on those dataset names.

• group (string, optional) – The group within the h5py file containing the datasets, e.g. in standard offline merged trigger files, this would be the IFO. This can be included in the args manually, but is required in the case of derived functions, e.g. newsnr.

• return_data (bool, optional, default True) – If True, return the data for elements passing the function.

• premask (array of boolean values, optional) – The pre-mask to apply to the triggers at read-in.

Returns:

• indices (np.ndarray) – An array of indices of elements passing the function.

• return_tuple (tuple of np.ndarrays) – A variable number of arrays depending on the number of args provided, If return_data is True, arrays are the values of each arg. If return_data is False, this is None.

• >>> f = HFile(filename)

• >>> snr = f.select(lambda snr (snr > 6, ‘H1/snr’))

class pycbc.io.hdf.MultiifoStatmapData(data=None, seg=None, attrs=None, files=None, ifos=None)

Bases: StatmapData

cluster(window)

Cluster the dict array, assuming it has the relevant Coinc colums, time1, time2, stat, and timeslide_id

class pycbc.io.hdf.ReadByTemplate(filename, bank=None, segment_name=None, veto_files=None, gating_veto_windows={})

Bases: object

get_data(col, num)

Get a column of data for template with id ‘num’.

Parameters:

• col (str) – Name of column to read

• num (int) – The template id to read triggers for

Returns:

data – The requested column of data

Return type:

numpy.ndarray

set_template(num)

Set the active template to read from.

Parameters:

num (int) – The template id to read triggers for.

Returns:

trigger_id – The indices of this templates triggers.

Return type:

numpy.ndarray

class pycbc.io.hdf.SingleDetTriggers(trig_file, detector, bank_file=None, veto_file=None, segment_name=None, premask=None, filter_rank=None, filter_threshold=None, chunksize=1000000, filter_func=None)

Bases: object

Provides easy access to the parameters of single-detector CBC triggers.

and_masks(logic_mask)

Apply a mask to be combined as a logical and with the current mask.

Parameters:

logic_mask (boolean array or numpy array/list of indices)

apply_mask(logic_mask)

Apply a mask over the top of the current mask

Parameters:

logic_mask (boolean array or numpy array of indices)

property approximant

checkbank(param)

property effective_spin

property end_time

property eta

property f_lower

property f_seobnrv2_peak

property f_seobnrv4_peak

get_column(cname)

Read columns while applying the mask

classmethod get_param_names()

Returns a list of plottable CBC parameter variables

get_ranking(rank_name, **kwargs)

property inclination

property mask_size

mask_to_n_loudest_clustered_events(rank_method, statistic_threshold=None, n_loudest=10, cluster_window=10, statistic_kwargs=None)

Edits the mask property of the class to point to the N loudest single detector events as ranked by ranking statistic.

Events are clustered so that no more than 1 event within +/- cluster_window will be considered. Can apply a threshold on the statistic using statistic_threshold

property mass1

property mass2

property mchirp

property mtotal

property newsnr

property newsnr_sgveto

property newsnr_sgveto_psdvar

property newsnr_sgveto_psdvar_threshold

property psd_var_val

property rchisq

property sgchisq

property snr

property spin1x

property spin1y

property spin1z

property spin2x

property spin2y

property spin2z

property template_duration

property template_id

trig_dict()

Returns dict of the masked trigger values

property u_vals

class pycbc.io.hdf.StatmapData(data=None, seg=None, attrs=None, files=None, groups=('stat', 'time1', 'time2', 'trigger_id1', 'trigger_id2', 'template_id', 'decimation_factor', 'timeslide_id'))

Bases: DictArray

cluster(window)

Cluster the dict array, assuming it has the relevant Coinc colums, time1, time2, stat, and timeslide_id

save(outname)

pycbc.io.hdf.combine_and_copy(f, files, group)

Combine the same column from multiple files and save to a third

pycbc.io.hdf.dump_pickle_to_hdf(memfp, fp, path=None, dsetname='state')

Dumps pickled data to an hdf5 file object.

Parameters:

• memfp (file object) – Bytes stream of pickled data.

• fp (h5py.File) – An open hdf5 file handler. Must have write capability enabled.

• path (str, optional) – The path (group name) to store the state dataset to. Default (None) will result in the array being stored to the top level.

• dsetname (str, optional) – The name of the dataset to store the binary array to. Default is state.

pycbc.io.hdf.dump_state(state, fp, path=None, dsetname='state', protocol=5)

Dumps the given state to an hdf5 file handler.

The state is stored as a raw binary array to {path}/{dsetname} in the given hdf5 file handler. If a dataset with the same name and path is already in the file, the dataset will be resized and overwritten with the new state data.

Parameters:

• state (any picklable object) – The sampler state to dump to file. Can be the object returned by any of the samplers’ .state attribute (a dictionary of dictionaries), or any picklable object.

• fp (h5py.File) – An open hdf5 file handler. Must have write capability enabled.

• path (str, optional) – The path (group name) to store the state dataset to. Default (None) will result in the array being stored to the top level.

• dsetname (str, optional) – The name of the dataset to store the binary array to. Default is state.

• protocol (int, optional) – The protocol version to use for pickling. See the pickle module for more details.

pycbc.io.hdf.get_all_subkeys(grp, key)

pycbc.io.hdf.get_chisq_from_file_choice(hdfile, chisq_choice)

pycbc.io.hdf.load_hdf5_to_dict(h5file, path)

Parameters:

• h5file – h5py file to be loaded as a dictionary

• path – path within h5py file to load: ‘/’ for the whole h5py file

Returns:

dictionary with hdf5 file group content

Return type:

dic

pycbc.io.hdf.load_state(fp, path=None, dsetname='state')

Loads a sampler state from the given hdf5 file object.

The sampler state is expected to be stored as a raw bytes array which can be loaded by pickle.

Parameters:

• fp (h5py.File) – An open hdf5 file handler.

• path (str, optional) – The path (group name) that the state data is stored to. Default (None) is to read from the top level.

• dsetname (str, optional) – The name of the dataset that the state data is stored to. Default is state.

pycbc.io.hdf.name_all_datasets(files)

pycbc.io.hdf.recursively_save_dict_contents_to_group(h5file, path, dic)

Parameters:

• h5file – h5py file to be written to

• path – path within h5py file to saved dictionary

• dic – python dictionary to be converted to hdf5 format

pycbc.io.hdf.save_dict_to_hdf5(dic, filename)

Parameters:

• dic – python dictionary to be converted to hdf5 format

• filename – desired name of hdf5 file

pycbc.io.ligolw module

Tools for dealing with LIGOLW XML files.

class pycbc.io.ligolw.LIGOLWContentHandler(document, start_handlers={})

Bases: LIGOLWContentHandler

Dummy class needed for loading LIGOLW files

endElementNS(uri_localname, qname, __orig_endElementNS=<function LIGOLWContentHandler.endElementNS>)

Convert values of <Param> elements from ilwdchar to int.

startColumn(parent, attrs, __orig_startColumn=<function use_in.<locals>.startColumn>)

Convert types in <Column> elements from ilwdchar to int.

Notes

This method is adapted from ligo.lw.utils.ilwd.strip_ilwdchar().

startStream(parent, attrs, __orig_startStream=<function use_in.<locals>.startStream>)

Convert values in table <Stream> elements from ilwdchar to int.

Notes

This method is adapted from ligo.lw.table.TableStream.config().

startTable(parent, attrs, __orig_startTable=<function use_in.<locals>.startTable>)

pycbc.io.ligolw.create_process_table(document, program_name=None, detectors=None, comment=None, options=None)

Create a LIGOLW process table with sane defaults, add it to a LIGOLW document, and return it.

pycbc.io.ligolw.default_null_value(col_name, col_type)

Associate a sensible “null” default value to a given LIGOLW column type.

pycbc.io.ligolw.get_table_columns(table)

Return a list of columns that are present in the given table, in a format that can be passed to lsctables.New().

The split on “:” is needed for columns like process:process_id, which must be listed as process:process_id in lsctables.New(), but are listed as just process_id in the columnnames attribute of the given table.

pycbc.io.ligolw.legacy_row_id_converter(ContentHandler)

Convert from old-style to new-style row IDs on the fly.

This is loosely adapted from ligo.lw.utils.ilwd.strip_ilwdchar().

Notes

When building a ContentHandler, this must be the _outermost_ decorator, outside of ligo.lw.lsctables.use_in(), ligo.lw.param.use_in(), or ligo.lw.table.use_in().

pycbc.io.ligolw.return_empty_sngl(nones=False)

Function to create a SnglInspiral object where all columns are populated but all are set to values that test False (ie. strings to ‘’, floats/ints to 0, …). This avoids errors when you try to create a table containing columns you don’t care about, but which still need populating. NOTE: This will also produce a process_id and event_id with 0 values. For most applications these should be set to their correct values.

Parameters:

nones (bool (False)) – If True, just set all columns to None.

Returns:

The “empty” SnglInspiral object.

Return type:

lsctables.SnglInspiral

pycbc.io.ligolw.return_search_summary(start_time=0, end_time=0, nevents=0, ifos=None)

Function to create a SearchSummary object where all columns are populated but all are set to values that test False (ie. strings to ‘’, floats/ints to 0, …). This avoids errors when you try to create a table containing columns you don’t care about, but which still need populating. NOTE: This will also produce a process_id with 0 values. For most applications these should be set to their correct values.

It then populates columns if given them as options.

Returns:

The “empty” SearchSummary object.

Return type:

lsctables.SeachSummary

pycbc.io.live module

pycbc.io.live.add_live_trigger_selection_options(parser)

Add options required for obtaining the right set of PyCBC live triggers into an argument parser

pycbc.io.live.find_trigger_files(directory, gps_start_time, gps_end_time, id_string='*', date_directories=False, date_directory_format='%Y_%m_%d')

Find a list of PyCBC live trigger files which are between the gps start and end times given

pycbc.io.live.find_trigger_files_from_cli(args)

Wrapper around the find_trigger_files function to use when called using options from the add_live_trigger_selection_options function

pycbc.io.record module

This modules provides definitions of, and helper functions for, FieldArray. FieldArray are wrappers of numpy recarrays with additional functionality useful for storing and retrieving data created by a search for gravitationa waves.

class pycbc.io.record.FieldArray(shape, name=None, zero=True, **kwargs)

Bases: recarray

Subclass of numpy.recarray that adds additional functionality.

Initialization is done the same way as numpy.recarray, with the addition that a “name” attribute can be passed to name the output array. When you initialize an array it creates a new zeroed array. This is similar to numpy.recarray, except that numpy.recarray(shape) will create an empty array, whereas here the default is to zero all of the elements (see default_zero for definition of zero for different data types). If you prefer an empty array, set zero=False when initializing.

You cannot pass an array or sequence as input as you do with numpy.array. To initialize an FieldArray from an already existing arrays, use the FieldArray.from_arrays class method. To initialize from a list of tuples, use FieldArray.from_records. See the docstring for those methods for details. For more information on initalizing an empty array, see numpy.recarray help.

Some additional features:

• Arbitrary functions:

  You can retrive functions on fields in the same manner that you access individual fields. For example, if you have a FieldArray x with fields a and b, you can access each field with x['a'], x['b']. You can also do x['a*b/(a+b)**2.'], x[cos(a)*sin(b)], etc. Boolean operations are also possible, e.g., x['(a < 3) & (b < 2)']. Syntax for functions is python. Any numpy ufunc, as well as all functions listed in the functionlib attribute, may be used. Note that while fields may be accessed as attributes (e.g, field a can be accessed via x['a'] or x.a), functions on multiple fields may not (x.a+b does not work, for obvious reasons).

• Subfields and ‘.’ indexing: Structured arrays, which are the base class for recarrays and, by inheritance, FieldArray, allows for fields to themselves have fields. For example, an array x may have fields a and b, with b having subfields c and d. You can access subfields using other index notation or attribute notation. So, the subfields d may be retrieved via x['b']['d'], x.b.d, x['b'].d or x['b.d']. Likewise, functions can be carried out on the subfields, as they can on fields. If d is a float field, we could get the log of it via x['log(b.d)']. There is no limit to the number of subfields. So, c could also have subfield c0, which would be accessed via x.c.c0, or any of the other methods.

Warning

Record arrays also allow you to set values of a field using attribute notation. However, this can lead to unexpected results if you accidently misspell the attribute. For example, if x has field foo, and you misspell this when setting, e.g., you try to do x.fooo = numpy.arange(x.size), foo will not be set, nor will you get an error. Instead, the attribute fooo will be added to x. If you tried to do this using index notation, however — x['fooo'] = numpy.arange(x.size) — you will get an AttributeError as you might expect. For this reason, it is recommended that you always use index notation when setting values; you can use either index or attribute notation when retrieving values.

• Properties and methods as fields: If a propety or instance method is defined for a class that inherits from FieldArray, those can be accessed in the same way as fields are. For example, define Foo as:

class Foo(FieldArray):
    @property
    def bar(self):
        return self['a']**2.

    def narf(self, y):
        return self['a'] + y

Then if we have an instance: foo = Foo(100, dtype=[('a', float)]). The bar and narf attributes may be accessed via field notation: foo.bar, foo['bar'], foo.narf(10) and foo['narf(10)'].

• Virtual fields: Virtual fields are methods wrapped as properties that operate on one or more fields, thus returning an array of values. To outside code virtual fields look the same as fields, and can be called similarily. Internally, no additional data is stored; the operation is performed on the fly when the virtual field is called. Virtual fields can be added to an array instance with the add_virtualfields method. Alternatively, virtual fields can be defined by sub-classing FieldArray:

class Foo(FieldArray):
    _virtualfields = ['bar']
    @property
    def bar(self):
        return self['a']**2.

The fields property returns the names of both fields and virtual fields.

Note

It can happen that a field, virtual field, or function in the functionlib have that same name. In that case, precedence is: field, virtual field, function. For example, if a function called ‘foo’ is in the function library, and a virtual field is added call ‘foo’, then a[‘foo’] will return the virtual field rather than the function. Likewise, if the array is initialized with a field called foo, or a field with that name is added, a[‘foo’] will return that field rather than the virtual field and/or the function.

Parameters:

• shape ({int | tuple}) – The shape of the new array.

• name ({None | str}) – Optional, what to name the new array. The array’s name attribute is set to this.

• arguments (For details on other keyword)

• help. (see numpy.recarray)

name

Instance attribute. The name of the array.

Type:

str

Examples

Note

For some predefined arrays with default fields, see the other array classes defined below.

Create an empty array with four rows and two fields called foo and bar, both of which are floats:

>>> x = FieldArray(4, dtype=[('foo', float), ('bar', float)])

Set/retrieve a fields using index or attribute syntax:

>>> x['foo'] = [1.,2.,3.,4.]
>>> x['bar'] = [5.,6.,7.,8.]
>>> x
FieldArray([(1.0, 5.0), (2.0, 6.0), (3.0, 7.0), (4.0, 8.0)],
      dtype=[('foo', '<f8'), ('bar', '<f8')])
>>> x.foo
    array([ 1.,  2.,  3.,  4.])
>>> x['bar']
    array([ 5.,  6.,  7.,  8.])

Get the names of the fields:

>>> x.fieldnames
    ('foo', 'bar')

Rename the fields to a and b:

>>> x.dtype.names = ['a', 'b']
>>> x.fieldnames
    ('a', 'b')

Retrieve a function of the fields as if it were a field:

>>> x['sin(a/b)']
array([ 0.19866933,  0.3271947 ,  0.41557185,  0.47942554])

Add a virtual field:

>>> def c(self):
...     return self['a'] + self['b']
...
>>> x = x.add_virtualfields('c', c)
>>> x.fields
('a', 'b', 'c')
>>> x['c']
array([  6.,   8.,  10.,  12.])

Create an array with subfields:

>>> x = FieldArray(4, dtype=[('foo', [('cat', float), ('hat', int)]), ('bar', float)])
>>> x.fieldnames
    ['foo.cat', 'foo.hat', 'bar']

Load from a list of arrays (in this case, from an hdf5 file):

>>> bankhdf = h5py.File('bank/H1L1-BANK2HDF-1117400416-928800.hdf')
>>> bankhdf.keys()
    [u'mass1', u'mass2', u'spin1z', u'spin2z', u'template_hash']
>>> templates = FieldArray.from_arrays(bankhdf.values(), names=bankhdf.keys())
>>> templates.fieldnames
    ('mass1', 'mass2', 'spin1z', 'spin2z', 'template_hash')
>>> templates.mass1
array([ 1.71731389,  1.10231435,  2.99999857, ...,  1.67488706,
        1.00531888,  2.11106491], dtype=float32)

Sort by a field without having to worry about also sorting the other fields:

>>> templates[['mass1', 'mass2']]
array([(1.7173138856887817, 1.2124452590942383),
       (1.1023143529891968, 1.0074082612991333),
       (2.9999985694885254, 1.0578444004058838), ...,
       (1.6748870611190796, 1.1758257150650024),
       (1.0053188800811768, 1.0020891427993774),
       (2.111064910888672, 1.0143394470214844)],
      dtype=[('mass1', '<f4'), ('mass2', '<f4')])
>>> templates.sort(order='mass1')
>>> templates[['mass1', 'mass2']]
array([(1.000025987625122, 1.0000133514404297),
       (1.0002814531326294, 1.0002814531326294),
       (1.0005437135696411, 1.0005437135696411), ...,
       (2.999999523162842, 1.371169090270996),
       (2.999999523162842, 1.4072519540786743), (3.0, 1.4617927074432373)],
      dtype=[('mass1', '<f4'), ('mass2', '<f4')])

Convert a LIGOLW xml table:

>>> type(sim_table)
    ligo.lw.lsctables.SimInspiralTable
>>> sim_array = FieldArray.from_ligolw_table(sim_table)
>>> sim_array.mass1
array([ 2.27440691,  1.85058105,  1.61507106, ...,  2.0504961 ,
        2.33554196,  2.02732205], dtype=float32)
>>> sim_array.waveform
array([u'SpinTaylorT2', u'SpinTaylorT2', u'SpinTaylorT2', ...,
       u'SpinTaylorT2', u'SpinTaylorT2', u'SpinTaylorT2'], dtype=object)

>>> sim_array = FieldArray.from_ligolw_table(sim_table, columns=['simulation_id', 'mass1', 'mass2'])
>>> sim_array
FieldArray([(0, 2.274406909942627, 2.6340370178222656),
       (1, 1.8505810499191284, 2.8336880207061768),
       (2, 1.6150710582733154, 2.2336490154266357), ...,
       (11607, 2.0504961013793945, 2.6019821166992188),
       (11608, 2.3355419635772705, 1.2164380550384521),
       (11609, 2.0273220539093018, 2.2453839778900146)],
      dtype=[('simulation_id', '<i8'), ('mass1', '<f4'), ('mass2', '<f4')])

Add a field to the array:

>>> optimal_snrs = numpy.random.uniform(4.,40., size=len(sim_array))
>>> sim_array = sim_array.add_fields(optimal_snrs, 'optimal_snrs')
>>> sim_array.fieldnames
    ('simulation_id', 'mass1', 'mass2', 'optimal_snrs')

Notes

Input arrays with variable-length strings in one or more fields can be tricky to deal with. Numpy arrays are designed to use fixed-length datasets, so that quick memory access can be achieved. To deal with variable-length strings, there are two options: 1. set the data type to object, or 2. set the data type to a string with a fixed length larger than the longest string in the input array.

The first option, using objects, essentially causes the array to store a pointer to the string. This is the most flexible option, as it allows strings in the array to be updated to any length. However, operations on object fields are slower, as numpy cannot take advantage of its fast memory striding abilities (see this question/answer on stackoverflow for details). Also, numpy’s support of object arrays is more limited. In particular, prior to version 1.9.2, you cannot create a view of an array that changes the dtype if the array has any fields that are objects, even if the view does not affect the object fields. (This has since been relaxed.)

The second option, using strings of a fixed length, solves the issues with object fields. However, if you try to change one of the strings after the array is created, the string will be truncated at whatever string length is used. Additionally, if you choose too large of a string length, you can substantially increase the memory overhead for large arrays.

add_fields(arrays, names=None, assubarray=False)

Adds the given arrays as new fields to self. Returns a new instance with the new fields added. Note: this array does not change; the returned array is a new copy.

Parameters:

• arrays ((list of) numpy array(s)) – The arrays to add. If adding multiple arrays, must be a list; if adding a single array, can just be that array.

• names ((list of) strings) – Optional, the name(s) of the new fields in the output array. If adding multiple fields, must be a list of strings with the same length as the list of arrays. If None provided, names used will be the same as the name of the datatype in the given arrays. If the datatype has no name, the new field will be 'fi' where i is the index of the array in arrays.

• assubarray (bool) – Add the list of arrays as a single subarray field. If True, and names provided, names should be a string or a length-1 sequence. Default is False, in which case each array will be added as a separate field.

Returns:

new_array – A copy of this array with the desired fields added.

Return type:

new instance of this array

add_functions(names, functions)

Adds the given functions to the function library.

Functions are added to this instance of the array; all copies of and slices of this array will also have the new functions included.

Parameters:

• names ((list of) string(s)) – Name or list of names of the functions.

• functions ((list of) function(s)) – The function(s) to call.

add_methods(names, methods)

Adds the given method(s) as instance method(s) of self. The method(s) must take self as a first argument.

add_properties(names, methods)

Returns a view of self with the given methods added as properties.

From: <http://stackoverflow.com/a/2954373/1366472>.

add_virtualfields(names, methods)

Returns a view of this array with the given methods added as virtual fields. Specifically, the given methods are added using add_properties and their names are added to the list of virtual fields. Virtual fields are properties that are assumed to operate on one or more of self’s fields, thus returning an array of values.

addattr(attrname, value=None, persistent=True)

Adds an attribute to self. If persistent is True, the attribute will be made a persistent attribute. Persistent attributes are copied whenever a view or copy of this array is created. Otherwise, new views or copies of this will not have the attribute.

property aliases

Returns a dictionary of the aliases, or “titles”, of the field names in self. An alias can be specified by passing a tuple in the name part of the dtype. For example, if an array is created with dtype=[(('foo', 'bar'), float)], the array will have a field called bar that has alias foo that can be accessed using either arr[‘foo’] or arr[‘bar’]. Note that the first string in the dtype is the alias, the second the name. This function returns a dictionary in which the aliases are the keys and the names are the values. Only fields that have aliases are returned.

append(other)

Appends another array to this array.

The returned array will have all of the class methods and virutal fields of this array, including any that were added using add_method or add_virtualfield. If this array and other array have one or more string fields, the dtype for those fields are updated to a string length that can encompass the longest string in both arrays.

Note

Increasing the length of strings only works for fields, not sub-fields.

Parameters:

other (array) – The array to append values from. It must have the same fields and dtype as this array, modulo the length of strings. If the other array does not have the same dtype, a TypeError is raised.

Returns:

An array with others values appended to this array’s values. The returned array is an instance of the same class as this array, including all methods and virtual fields.

Return type:

array

del_functions(names)

Removes the specified function names from the function library.

Functions are removed from this instance of the array; all copies and slices of this array will also have the functions removed.

Parameters:

names ((list of) string(s)) – Name or list of names of the functions to remove.

property fieldnames

Returns a tuple listing the field names in self. Equivalent to array.dtype.names, where array is self.

property fields

Returns a tuple listing the names of fields and virtual fields in self.

classmethod from_arrays(arrays, name=None, **kwargs)

Creates a new instance of self from the given (list of) array(s). This is done by calling numpy.rec.fromarrays on the given arrays with the given kwargs. The type of the returned array is cast to this class, and the name (if provided) is set.

Parameters:

• arrays ((list of) numpy array(s)) – A list of the arrays to create the FieldArray from.

• name ({None|str}) – What the output array should be named.

• parameters (For other keyword)

• help. (see the numpy.rec.fromarrays)

Returns:

array – An array that is an instance of this class in which the field data is from the given array(s).

Return type:

instance of this class

classmethod from_kwargs(**kwargs)

Creates a new instance of self from the given keyword arguments. Each argument will correspond to a field in the returned array, with the name of the field given by the keyword, and the value(s) whatever the keyword was set to. Each keyword may be set to a single value or a list of values. The number of values that each argument is set to must be the same; this will be the size of the returned array.

Examples

Create an array with fields ‘mass1’ and ‘mass2’: >>> a = FieldArray.from_kwargs(mass1=[1.1, 3.], mass2=[2., 3.]) >>> a.fieldnames (‘mass1’, ‘mass2’) >>> a.mass1, a.mass2 (array([ 1.1, 3. ]), array([ 2., 3.]))

Create an array with only a single element in it: >>> a = FieldArray.from_kwargs(mass1=1.1, mass2=2.) >>> a.mass1, a.mass2 (array([ 1.1]), array([ 2.]))

classmethod from_ligolw_table(table, columns=None, cast_to_dtypes=None)

Converts the given ligolw table into an FieldArray. The tableName attribute is copied to the array’s name.

Parameters:

• table (LIGOLw table instance) – The table to convert.

• columns ({None|list}) – Optionally specify a list of columns to retrieve. All of the columns must be in the table’s validcolumns attribute. If None provided, all the columns in the table will be converted.

• dtype ({None | dict}) – Override the columns’ dtypes using the given dictionary. The dictionary should be keyed by the column names, with the values a tuple that can be understood by numpy.dtype. For example, to cast a ligolw column called “foo” to a field called “bar” with type float, cast_to_dtypes would be: {"foo": ("bar", float)}.

Returns:

array – The input table as an FieldArray.

Return type:

FieldArray

classmethod from_records(records, name=None, **kwargs)

Creates a new instance of self from the given (list of) record(s).

A “record” is a tuple in which each element is the value of one field in the resulting record array. This is done by calling numpy.rec.fromrecords on the given records with the given kwargs. The type of the returned array is cast to this class, and the name (if provided) is set.

Parameters:

• records ((list of) tuple(s)) – A list of the tuples to create the FieldArray from.

• name ({None|str}) – What the output array should be named.

• parameters (For other keyword)

• help. (see the numpy.rec.fromrecords)

Returns:

array – An array that is an instance of this class in which the field data is from the given record(s).

Return type:

instance of this class

property functionlib

Returns the library of functions that are available when calling items.

parse_boolargs(args)

Returns an array populated by given values, with the indices of those values dependent on given boolen tests on self.

The given args should be a list of tuples, with the first element the return value and the second argument a string that evaluates to either True or False for each element in self.

Each boolean argument is evaluated on elements for which every prior boolean argument was False. For example, if array foo has a field bar, and args = [(1, ‘bar < 10’), (2, ‘bar < 20’), (3, ‘bar < 30’)], then the returned array will have 1`s at the indices for which `foo.bar < 10, 2`s where `foo.bar < 20 and not foo.bar < 10, and 3`s where `foo.bar < 30 and not (foo.bar < 10 or foo.bar < 20).

The last argument in the list may have “else”, an empty string, None, or simply list a return value. In any of these cases, any element not yet populated will be assigned the last return value.

Parameters:

args ({(list of) tuples, value}) – One or more return values and boolean argument determining where they should go.

Returns:

• return_values (array) – An array with length equal to self, with values populated with the return values.

• leftover_indices (array) – An array of indices that evaluated to False for all arguments. These indices will not have been popluated with any value, defaulting to whatever numpy uses for a zero for the return values’ dtype. If there are no leftovers, an empty array is returned.

Examples

Given the following array:

>>> arr = FieldArray(5, dtype=[('mtotal', float)])
>>> arr['mtotal'] = numpy.array([3., 5., 2., 1., 4.])

Return “TaylorF2” for all elements with mtotal < 4 (note that the elements 1 and 4 are leftover):

>>> arr.parse_boolargs(('TaylorF2', 'mtotal<4'))
    (array(['TaylorF2', '', 'TaylorF2', 'TaylorF2', ''],
    dtype='|S8'),
    array([1, 4]))

Return “TaylorF2” for all elements with mtotal < 4, “SEOBNR_ROM_DoubleSpin” otherwise:

>>> arr.parse_boolargs([('TaylorF2', 'mtotal<4'), ('SEOBNRv2_ROM_DoubleSpin', 'else')])
    (array(['TaylorF2', 'SEOBNRv2_ROM_DoubleSpin', 'TaylorF2', 'TaylorF2',
    'SEOBNRv2_ROM_DoubleSpin'],
    dtype='|S23'),
    array([], dtype=int64))

The following will also return the same:

>>> arr.parse_boolargs([('TaylorF2', 'mtotal<4'), ('SEOBNRv2_ROM_DoubleSpin',)])
>>> arr.parse_boolargs([('TaylorF2', 'mtotal<4'), ('SEOBNRv2_ROM_DoubleSpin', '')])
>>> arr.parse_boolargs([('TaylorF2', 'mtotal<4'), 'SEOBNRv2_ROM_DoubleSpin'])

Return “TaylorF2” for all elements with mtotal < 3, “IMRPhenomD” for all elements with 3 <= mtotal < 4, “SEOBNRv2_ROM_DoubleSpin” otherwise:

>>> arr.parse_boolargs([('TaylorF2', 'mtotal<3'), ('IMRPhenomD', 'mtotal<4'), 'SEOBNRv2_ROM_DoubleSpin'])
    (array(['IMRPhenomD', 'SEOBNRv2_ROM_DoubleSpin', 'TaylorF2', 'TaylorF2',
    'SEOBNRv2_ROM_DoubleSpin'],
    dtype='|S23'),
    array([], dtype=int64))

Just return “TaylorF2” for all elements:

>>> arr.parse_boolargs('TaylorF2')
    (array(['TaylorF2', 'TaylorF2', 'TaylorF2', 'TaylorF2', 'TaylorF2'],
    dtype='|S8'),
    array([], dtype=int64))

classmethod parse_parameters(parameters, possible_fields)

Parses a list of parameters to get the list of fields needed in order to evaluate those parameters.

Parameters:

• parameters ((list of) string(s)) – The list of desired parameters. These can be (functions of) fields or virtual fields.

• possible_fields ((list of) string(s)) – The list of possible fields.

Returns:

The list of names of the fields that are needed in order to evaluate the given parameters.

Return type:

list

sort(axis=-1, kind='quicksort', order=None)

Sort an array, in-place.

This function extends the standard numpy record array in-place sort to allow the basic use of Field array virtual fields. Only a single field is currently supported when referencing a virtual field.

Parameters:

• axis (int, optional) – Axis along which to sort. Default is -1, which means sort along the last axis.

• kind ({'quicksort', 'mergesort', 'heapsort'}, optional) – Sorting algorithm. Default is ‘quicksort’.

• order (list, optional) – When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

to_array(fields=None, axis=0)

Returns an numpy.ndarray of self in which the fields are included as an extra dimension.

Parameters:

• fields ({None, (list of) strings}) – The fields to get. All of the fields must have the same datatype. If None, will try to return all of the fields.

• axis ({0, int}) – Which dimension to put the fields in in the returned array. For example, if self has shape (l,m,n) and k fields, the returned array will have shape (k,l,m,n) if axis=0, (l,k,m,n) if axis=1, etc. Setting axis=-1 will put the fields in the last dimension. Default is 0.

Returns:

The desired fields as a numpy array.

Return type:

numpy.ndarray

property virtualfields

Returns a tuple listing the names of virtual fields in self.

class pycbc.io.record.WaveformArray(shape, name=None, additional_fields=None, field_kwargs=None, **kwargs)

Bases: _FieldArrayWithDefaults

A FieldArray with some default fields and properties commonly used by CBC waveforms. This may be initialized in one of 3 ways:

1. With just the size of the array. In this case, the returned array will have all of the default field names. Example:

>>> warr = WaveformArray(10)
>>> warr.fieldnames
    ('distance',
     'spin2x',
     'mass1',
     'mass2',
     'lambda1',
     'polarization',
     'spin2y',
     'spin2z',
     'spin1y',
     'spin1x',
     'spin1z',
     'inclination',
     'coa_phase',
     'dec',
     'tc',
     'lambda2',
     'ra')

2. With some subset of the default field names. Example:

>>> warr = WaveformArray(10, names=['mass1', 'mass2'])
>>> warr.fieldnames
    ('mass1', 'mass2')

The list of names may include virtual fields, and methods, as well as functions of these. If one or more virtual fields or methods are specified, the source code is analyzed to pull out whatever underlying fields are needed. Example:

>>> warr = WaveformArray(10, names=['mchirp**(5/6)', 'chi_eff', 'cos(coa_phase)'])
>>> warr.fieldnames
    ('spin2z', 'mass1', 'mass2', 'coa_phase', 'spin1z')

3. By specifying a dtype. In this case, only the provided fields will be used, even if they are not in the defaults. Example:

>>> warr = WaveformArray(10, dtype=[('foo', float)])
>>> warr.fieldnames
    ('foo',)

Additional fields can also be specified using the additional_fields keyword argument. Example:

>>> warr = WaveformArray(10, names=['mass1', 'mass2'], additional_fields=[('bar', float)])
>>> warr.fieldnames
    ('mass1', 'mass2', 'bar')

Note

If an array is initialized with all of the default fields (case 1, above), then the names come from waveform.parameters; i.e., they are actually Parameter instances, not just strings. This means that the field names carry all of the metadata that a Parameter has. For example:

>>> warr = WaveformArray(10)
>>> warr.fields[0]
    'distance'
>>> warr.fields[0].description
    'Luminosity distance to the binary (in Mpc).'
>>> warr.fields[0].label
    '$d_L$ (Mpc)'

property chi_eff

Returns the effective spin.

property eta

Returns the symmetric mass ratio.

property mchirp

Returns the chirp mass.

property mtotal

Returns the total mass.

property primary_mass

Returns the larger of self.mass1 and self.mass2.

property q

Returns the mass ratio m1/m2, where m1 >= m2.

property remnant_mass

Returns the remnant mass for an NS-BH binary.

property secondary_mass

Returns the smaller of self.mass1 and self.mass2.

property spin1_a

Returns the dimensionless spin magnitude of mass 1.

property spin1_azimuthal

Returns the azimuthal spin angle of mass 1.

property spin1_polar

Returns the polar spin angle of mass 1.

property spin2_a

Returns the dimensionless spin magnitude of mass 2.

property spin2_azimuthal

Returns the azimuthal spin angle of mass 2.

property spin2_polar

Returns the polar spin angle of mass 2.

property spin_px

Returns the x-component of the spin of the primary mass.

property spin_py

Returns the y-component of the spin of the primary mass.

property spin_pz

Returns the z-component of the spin of the primary mass.

property spin_sx

Returns the x-component of the spin of the secondary mass.

property spin_sy

Returns the y-component of the spin of the secondary mass.

property spin_sz

Returns the z-component of the spin of the secondary mass.

Module contents

pycbc.io.get_file(url, retry=5, **args)

Retrieve file with retry upon failure

Uses the astropy download_file but adds a retry feature for flaky connections. See astropy for full options