pycbc.io package

Submodules

pycbc.io.hdf module

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

Bases: object

get_column(col)[source]

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)[source]

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)[source]

Return a new DictArray that does not contain the indexed values

save(outname)[source]
select(idx)[source]

Return a new DictArray containing only the indexed values

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

Bases: object

close()[source]
get_column(col)[source]
Parameters:col (string) – Name of the dataset to be returned
Returns:Values from the dataset, filtered if requested
Return type:numpy array
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')[source]

Bases: object

get_bankfile_array(variable)[source]
get_coincfile_array(variable)[source]
get_end_time()[source]
get_ifos()[source]
get_snglfile_array_dict(variable)[source]
sort_arr
template_id
to_coinc_xml_object(file_name)[source]
trig_id
class pycbc.io.hdf.HFile(name, mode=None, driver=None, libver=None, userblock_size=None, swmr=False, rdcc_nslots=None, rdcc_nbytes=None, rdcc_w0=None, track_order=None, **kwds)[source]

Bases: h5py._hl.files.File

Low level extensions to the capabilities of reading an hdf5 File

select(fcn, *args, **kwds)[source]

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 ({1e6, int}, optional) – Number of elements to read and process at a time.
  • return_indices (bool, optional) – If True, also return the indices of elements passing the function.
Returns:

  • values (np.ndarrays) – A variable number of arrays depending on the number of keys into the hdf5 file that are given. If return_indices is True, the first element is an array of indices of elements passing the function.
  • >>> 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)[source]

Bases: pycbc.io.hdf.StatmapData

cluster(window)[source]

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={})[source]

Bases: object

get_data(col, num)[source]

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)[source]

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, bank_file, veto_file, segment_name, filter_func, detector, premask=None)[source]

Bases: object

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

apply_mask(logic_mask)[source]

Apply a boolean array to the set of triggers

checkbank(param)[source]
effective_spin
end_time
eta
f_lower
f_seobnrv2_peak
f_seobnrv4_peak
get_column(cname)[source]
classmethod get_param_names()[source]

Returns a list of plottable CBC parameter variables

inclination
mask_to_n_loudest_clustered_events(n_loudest=10, ranking_statistic='newsnr', cluster_window=10, statistic_files=None)[source]

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.

mass1
mass2
mchirp
mtotal
newsnr
newsnr_sgveto
newsnr_sgveto_psdvar
newsnr_sgveto_psdvar_threshold
psd_var_val
rchisq
sgchisq
snr
spin1x
spin1y
spin1z
spin2x
spin2y
spin2z
template_duration
template_id
trig_dict()[source]

Returns dict of the masked trigger valuse

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'))[source]

Bases: pycbc.io.hdf.DictArray

cluster(window)[source]

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

save(outname)[source]
pycbc.io.hdf.combine_and_copy(f, files, group)[source]

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')[source]

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=4)[source]

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)[source]
pycbc.io.hdf.get_chisq_from_file_choice(hdfile, chisq_choice)[source]
pycbc.io.hdf.load_hdf5_to_dict(h5file, path)[source]
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')[source]

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)[source]
pycbc.io.hdf.recursively_save_dict_contents_to_group(h5file, path, dic)[source]
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)[source]
Parameters:
  • dic – python dictionary to be converted to hdf5 format
  • filename – desired name of hdf5 file

pycbc.io.live module

class pycbc.io.live.SingleCoincForGraceDB(ifos, coinc_results, **kwargs)[source]

Bases: object

Create xml files and submit them to gracedb from PyCBC Live

save(filename)[source]

Write this trigger to gracedb compatible xml format

Parameters:filename (str) – Name of file to write to disk.
upload(fname, gracedb_server=None, testing=True, extra_strings=None, search='AllSky')[source]

Upload this trigger to gracedb

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.
pycbc.io.live.make_psd_xmldoc(psddict, xmldoc=None)[source]

Add a set of PSDs to a LIGOLW XML document. If the document is not given, a new one is created first.

pycbc.io.live.snr_series_to_xml(snr_series, document, sngl_inspiral_id)[source]

Save an SNR time series into an XML document, in a format compatible with BAYESTAR.

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[source]

Bases: numpy.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.
  • details on other keyword arguments, see numpy.recarray help. (For) –
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)
    glue.ligolw.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)[source]

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)[source]

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)[source]

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)[source]

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

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

add_virtualfields(names, methods)[source]

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)[source]

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.

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)[source]

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)[source]

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.
fieldnames

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

fields

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

classmethod from_arrays(arrays, name=None, **kwargs)[source]

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.
  • other keyword parameters, see the numpy.rec.fromarrays help. (For) –
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)[source]

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)[source]

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)[source]

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.
Other Parameters:
 

For other keyword parameters, see the `numpy.rec.fromrecords` help.

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

functionlib

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

parse_boolargs(args)[source]

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)[source]

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)[source]

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)[source]

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

virtualfields

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

class pycbc.io.record.WaveformArray[source]

Bases: pycbc.io.record._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')
  1. 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)'
chi_eff

Returns the effective spin.

eta

Returns the symmetric mass ratio.

mchirp

Returns the chirp mass.

mtotal

Returns the total mass.

primary_mass

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

q

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

secondary_mass

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

spin1_a

Returns the dimensionless spin magnitude of mass 1.

spin1_azimuthal

Returns the azimuthal spin angle of mass 1.

spin1_polar

Returns the polar spin angle of mass 1.

spin2_a

Returns the dimensionless spin magnitude of mass 2.

spin2_azimuthal

Returns the azimuthal spin angle of mass 2.

spin2_polar

Returns the polar spin angle of mass 2.

spin_px

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

spin_py

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

spin_pz

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

spin_sx

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

spin_sy

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

spin_sz

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

Module contents