pyfstat package¶
These pages document the full API and set of classes provided by PyFstat.
See here for installation instructions and other general information.
Submodules¶
pyfstat.core module¶
The core tools used in pyfstat

class
pyfstat.core.
BaseSearchClass
(*args, **kwargs)[source]¶ Bases:
object
The base class providing parent methods to other PyFstat classes.
This does not actually have any ‘search’ functionality, which needs to be added by child classes along with full initialization and any other custom methods.

set_ephemeris_files
(earth_ephem=None, sun_ephem=None)[source]¶ Set the ephemeris files to use for the Earth and Sun.
NOTE: If not given explicit arguments, default values from helper_functions.get_ephemeris_files() are used (looking in ~/.pyfstat or $LALPULSAR_DATADIR)
 Parameters
earth_ephem (str) – Paths of the two files containing positions of Earth and Sun, respectively at evenly spaced times, as passed to CreateFstatInput
sun_ephem (str) – Paths of the two files containing positions of Earth and Sun, respectively at evenly spaced times, as passed to CreateFstatInput

pprint_init_params_dict
()[source]¶ Prettyprint a parameters dictionary for output file headers.
 Returns
pretty_init_parameters – A list of lines to be printed, including opening/closing “{” and “}”, consistent indentation, as well as endofline commas, but no comment markers at start of lines.
 Return type
list

get_output_file_header
()[source]¶ Constructs a metainformation header for text output files.
This will include PyFstat and LALSuite versioning, information about when/where/how the code was run, and input parameters of the instantiated class.
 Returns
header – A list of formatted header lines.
 Return type
list

read_par
(filename=None, label=None, outdir=None, suffix='par', raise_error=True)[source]¶ Read a key=val file and return a dictionary.
 Parameters
filename (str or None) – Filename (path) containing rows of key=val data to read in.
label (str or None) – If filename is None, form the file to read as outdir/label.suffix.
outdir (str or None) – If filename is None, form the file to read as outdir/label.suffix.
suffix (str or None) – If filename is None, form the file to read as outdir/label.suffix.
raise_error (bool) – If True, raise an error for lines which are not comments, but cannot be read.
 Returns
params_dict – A dictionary of the parsed key=val pairs.
 Return type
dict

static
translate_keys_to_lal
(dictionary)[source]¶ Convert input keys into lalpulsar convention.
In PyFstat’s convention, input keys (search parameter names) are F0, F1, F2, …, while lalpulsar functions prefer to use Freq, f1dot, f2dot, ….
Since lalpulsar keys are only used internally to call lalpulsar routines, this function is provided so the keys can be translated on the fly.
 Parameters
dictionary (dict) – Dictionary to translate. A copy will be made (and returned) before translation takes place.
 Returns
translated_dict – Copy of “dictionary” with new keys according to lalpulsar convention.
 Return type
dict


class
pyfstat.core.
ComputeFstat
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.BaseSearchClass
Base search class providing an interface to lalpulsar.ComputeFstat.
In most cases, users should be using one of the higherlevel search classes from the grid_based_searches or mcmc_based_searches modules instead.
See the lalpulsar documentation at https://lscsoft.docs.ligo.org/lalsuite/lalpulsar/group___compute_fstat__h.html and R. Prix, The Fstatistic and its implementation in ComputeFstatistic_v2 ( https://dcc.ligo.org/T0900149/public ) for details of the lalpulsar module and the meaning of various technical concepts as embodied by some of the class’s parameters.
Normally this will read in existing data through the sftfilepattern argument, but if that option is None and the necessary alternative arguments are used, it can also generate simulated data (including noise and/or signals) on the fly.
 Parameters
tref (int) – GPS seconds of the reference time.
sftfilepattern (str) – Pattern to match SFTs using wildcards (*?) and ranges [09]; mutiple patterns can be given separated by colons.
minStartTime (int) – Only use SFTs with timestamps starting from within this range, following the XLALCWGPSinRange convention: halfopen intervals [minStartTime,maxStartTime].
maxStartTime (int) – Only use SFTs with timestamps starting from within this range, following the XLALCWGPSinRange convention: halfopen intervals [minStartTime,maxStartTime].
Tsft (int) – SFT duration in seconds. Only required if sftfilepattern=None and hence simulted data is generated on the fly.
binary (bool) – If true, search over binary parameters.
BSGL (bool) –
If true, compute the log10BSGL statistic rather than the twoF value. For details, see Keitel et al (PRD 89, 064023, 2014): https://arxiv.org/abs/1311.5738 Tuning parameters are currently hardcoded:
Fstar0=15 for coherent searches.
A pvalue of 1e6 and correspondingly recalculated Fstar0 for semicoherent searches.
Uniform perdetector prior linevsGaussian odds.
transientWindowType (str) – If rect or exp, allow for the Fstat to be computed over a transient range. (none instead of None explicitly calls the transientwindow function, but with the full range, for debugging.) (If not None, will also force atoms regardless of computeAtoms option.)
t0Band (int) – Search ranges for transient starttime t0 and duration tau. If >0, search t0 in (minStartTime,minStartTime+t0Band) and tau in (tauMin,2*Tsft+tauBand). If =0, only compute the continuouswave Fstat with t0=minStartTime, tau=maxStartTimeminStartTime.
tauBand (int) – Search ranges for transient starttime t0 and duration tau. If >0, search t0 in (minStartTime,minStartTime+t0Band) and tau in (tauMin,2*Tsft+tauBand). If =0, only compute the continuouswave Fstat with t0=minStartTime, tau=maxStartTimeminStartTime.
tauMin (int) – Minimum transient duration to cover, defaults to 2*Tsft.
dt0 (int) – Grid resolution in transient starttime, defaults to Tsft.
dtau (int) – Grid resolution in transient duration, defaults to Tsft.
detectors (str) – Twocharacter references to the detectors for which to use data. Specify None for no constraint. For multiple detectors, separate by commas.
minCoverFreq (float) – The min and max cover frequency passed to lalpulsar.CreateFstatInput. For negative values, these will be used as offsets from the min/max frequency contained in the sftfilepattern. If either is None, the search_ranges argument is used to estimate them. If the automatic estimation fails and you do not have a good idea what to set these two options to, setting both to 0.5 will reproduce the default behaviour of PyFstat <=1.4 and may be a reasonably safe fallback in many cases.
maxCoverFreq (float) – The min and max cover frequency passed to lalpulsar.CreateFstatInput. For negative values, these will be used as offsets from the min/max frequency contained in the sftfilepattern. If either is None, the search_ranges argument is used to estimate them. If the automatic estimation fails and you do not have a good idea what to set these two options to, setting both to 0.5 will reproduce the default behaviour of PyFstat <=1.4 and may be a reasonably safe fallback in many cases.
search_ranges (dict) – Dictionary of ranges in all search parameters, only used to estimate frequency band passed to lalpulsar.CreateFstatInput, if minCoverFreq, maxCoverFreq are not specified (==`None`). For actually running searches, grids/points will have to be passed separately to the .run() method. The entry for each parameter must be a list of length 1, 2 or 3: [single_value], [min,max] or [min,max,step].
injectSources (dict or str) – Either a dictionary of the signal parameters to inject, or a string pointing to a .cff file defining a signal.
injectSqrtSX (float or list or str) – Singlesided PSD values for generating fake Gaussian noise on the fly. Single float or str value: use same for all IFOs. List or commaseparated string: must match len(detectors) and/or the data in sftfilepattern. Detectors will be paired to list elements following alphabetical order.
assumeSqrtSX (float or list or str) – Don’t estimate noisefloors but assume this (stationary) singlesided PSD. Single float or str value: use same for all IFOs. List or commaseparated string: must match len(detectors) and/or the data in sftfilepattern. Detectors will be paired to list elements following alphabetical order. If working with signalonly data, please set assumeSqrtSX=1 .
SSBprec (int) – Flag to set the Solar System Barycentring (SSB) calculation in lalpulsar: 0=Newtonian, 1=relativistic, 2=relativistic optimised, 3=DMoff, 4=NO_SPIN
RngMedWindow (int) – RunningMedian window size for Fstatistic noise normalization (number of SFT bins).
tCWFstatMapVersion (str) – Choose between implementations of the transient Fstatistic funcionality: standard lal implementation, pycuda for GPU version, and some others only for devel/debug.
cudaDeviceName (str) – GPU name to be matched against drv.Device output, only for tCWFstatMapVersion=pycuda.
computeAtoms (bool) – Request calculation of ‘Fstatistic atoms’ regardless of transientWindowType.
earth_ephem (str) – Earth ephemeris file path. If None, will check standard sources as per helper_functions.get_ephemeris_files().
sun_ephem (str) – Sun ephemeris file path. If None, will check standard sources as per helper_functions.get_ephemeris_files().

init_computefstatistic
()[source]¶ Initialization step for the Fstastic computation internals.
This sets up the special input and output structures the lalpulsar module needs, the ephemerides, optional onthefly signal injections, and extra options for multidetector consistency checks and transient searches.
All inputs are taken from the preinitialized object, so this function does not have additional arguments of its own.

estimate_min_max_CoverFreq
()[source]¶ Extract spanned spinrange at reference time from the template bank.
To use this method, self.search_ranges must be a dictionary of lists per search parameter which can be either [single_value], [min,max] or [min,max,step].

get_fullycoherent_detstat
(F0, F1, F2, Alpha, Delta, asini=None, period=None, ecc=None, tp=None, argp=None, tstart=None, tend=None)[source]¶ Computes the detection statistic (twoF or log10BSGL) fullycoherently at a single point.
These are also stored to self.twoF and self.log10BSGL respectively. As the basic statistic of this class, self.twoF is always computed. If self.BSGL, additionally the singledetector 2Fstat values are saved in self.twoFX.
If transient parameters are enabled (self.transientWindowType is set), the full transientFstat map will also be computed here, but stored in self.FstatMap, not returned.
 Parameters
F0 (float) – Parameters at which to compute the statistic.
F1 (float) – Parameters at which to compute the statistic.
F2 (float) – Parameters at which to compute the statistic.
Alpha (float) – Parameters at which to compute the statistic.
Delta (float) – Parameters at which to compute the statistic.
asini (float, optional) – Optional: Binary parameters at which to compute the statistic.
period (float, optional) – Optional: Binary parameters at which to compute the statistic.
ecc (float, optional) – Optional: Binary parameters at which to compute the statistic.
tp (float, optional) – Optional: Binary parameters at which to compute the statistic.
argp (float, optional) – Optional: Binary parameters at which to compute the statistic.
tstart (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime. This is only passed on to self.get_transient_detstat(), i.e. only used if self.transientWindowType is set.
tend (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime. This is only passed on to self.get_transient_detstat(), i.e. only used if self.transientWindowType is set.
 Returns
stat – A single value of the detection statistic (twoF or log10BSGL) at the input parameter values. Also stored as self.twoF or self.log10BSGL.
 Return type
float

get_fullycoherent_twoF
(F0, F1, F2, Alpha, Delta, asini=None, period=None, ecc=None, tp=None, argp=None)[source]¶ Computes the fullycoherent 2F statistic at a single point.
NOTE: This always uses the full data set as defined when initialising the search object. If you want to restrict the range of data used for a single 2F computation, you need to set a self.transientWindowType and then call self.get_fullycoherent_detstat() with tstart and tend options instead of this funcion.
 Parameters
F0 (float) – Parameters at which to compute the statistic.
F1 (float) – Parameters at which to compute the statistic.
F2 (float) – Parameters at which to compute the statistic.
Alpha (float) – Parameters at which to compute the statistic.
Delta (float) – Parameters at which to compute the statistic.
asini (float, optional) – Optional: Binary parameters at which to compute the statistic.
period (float, optional) – Optional: Binary parameters at which to compute the statistic.
ecc (float, optional) – Optional: Binary parameters at which to compute the statistic.
tp (float, optional) – Optional: Binary parameters at which to compute the statistic.
argp (float, optional) – Optional: Binary parameters at which to compute the statistic.
 Returns
twoF – A single value of the fullycoherent 2F statistic at the input parameter values. Also stored as self.twoF.
 Return type
float

get_fullycoherent_single_IFO_twoFs
()[source]¶ Computes singledetector Fstats at a single point.
This requires self.get_fullycoherent_twoF() to be run first.
 Returns
twoFX – A list of the singledetector detection statistics twoF. Also stored as self.twoFX.
 Return type
list

get_fullycoherent_log10BSGL
()[source]¶ Computes the linerobust statistic log10BSGL at a single point.
This requires self.get_fullycoherent_twoF() and self.get_fullycoherent_single_IFO_twoFs() to be run first.
 Returns
log10BSGL – A single value of the detection statistic log10BSGL at the input parameter values. Also stored as self.log10BSGL.
 Return type
float

get_transient_maxTwoFstat
(tstart=None, tend=None)[source]¶ Computes the transient maxTwoF statistic at a single point.
This requires self.get_fullycoherent_twoF() to be run first.
The full transientFstat map will also be computed here, but stored in self.FstatMap, not returned.
 Parameters
F0 (float) – Parameters at which to compute the statistic.
F1 (float) – Parameters at which to compute the statistic.
F2 (float) – Parameters at which to compute the statistic.
Alpha (float) – Parameters at which to compute the statistic.
Delta (float) – Parameters at which to compute the statistic.
asini (float, optional) – Optional: Binary parameters at which to compute the statistic.
period (float, optional) – Optional: Binary parameters at which to compute the statistic.
ecc (float, optional) – Optional: Binary parameters at which to compute the statistic.
tp (float, optional) – Optional: Binary parameters at which to compute the statistic.
argp (float, optional) – Optional: Binary parameters at which to compute the statistic.
tstart (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime. This is only passed on to self.get_transient_detstat(), i.e. only used if self.transientWindowType is set.
tend (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime. This is only passed on to self.get_transient_detstat(), i.e. only used if self.transientWindowType is set.
 Returns
maxTwoF – A single value of the detection statistic (twoF or log10BSGL) at the input parameter values. Also stored as self.maxTwoF.
 Return type
float

get_transient_log10BSGL
()[source]¶ Computes a transient detection statistic log10BSGL at a single point.
This requires self.get_transient_maxTwoFstat() to be run first.
The singledetector 2Fstat values used for that computation (at the index of maxTwoF) are saved in self.twoFXatMaxTwoF, not returned.
 Returns
log10BSGL – A single value of the detection statistic log10BSGL at the input parameter values. Also stored as self.log10BSGL.
 Return type
float

calculate_twoF_cumulative
(F0, F1, F2, Alpha, Delta, asini=None, period=None, ecc=None, tp=None, argp=None, tstart=None, tend=None, num_segments=1000)[source]¶ Calculate the cumulative twoF over subsets of the observation span.
This means that we consider sub“segments” of the [tstart,tend] interval, each starting at the overall tstart and with increasing durations, and compute the 2F for each of these, which for a true CW signal should increase roughly with duration towards the full value.
 Parameters
F0 (float) – Parameters at which to compute the cumulative twoF.
F1 (float) – Parameters at which to compute the cumulative twoF.
F2 (float) – Parameters at which to compute the cumulative twoF.
Alpha (float) – Parameters at which to compute the cumulative twoF.
Delta (float) – Parameters at which to compute the cumulative twoF.
asini (float, optional) – Optional: Binary parameters at which to compute the cumulative 2F.
period (float, optional) – Optional: Binary parameters at which to compute the cumulative 2F.
ecc (float, optional) – Optional: Binary parameters at which to compute the cumulative 2F.
tp (float, optional) – Optional: Binary parameters at which to compute the cumulative 2F.
argp (float, optional) – Optional: Binary parameters at which to compute the cumulative 2F.
tstart (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime;. If outside those: autotruncated.
tend (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime;. If outside those: autotruncated.
num_segments (int) – Number of segments to split [tstart,tend] into.
 Returns
cumulative_durations (ndarray of shape (num_segments,)) – Offsets of each segment’s tend from the overall tstart.
twoFs (ndarray of shape (num_segments,)) – Values of twoF computed over [[tstart,tstart+duration] for duration in cumulative_durations].

predict_twoF_cumulative
(F0, Alpha, Delta, h0, cosi, psi, tstart=None, tend=None, num_segments=10, **predict_fstat_kwargs)[source]¶ Calculate expected 2F, with uncertainty, over subsets of the observation span.
This yields the expected behaviour that calculate_twoF_cumulative() can be compared against: 2F for CW signals increases with duration as we take longer and longer subsets of the total observation span.
 Parameters
F0 (float) – Parameters at which to compute the cumulative predicted twoF.
Alpha (float) – Parameters at which to compute the cumulative predicted twoF.
Delta (float) – Parameters at which to compute the cumulative predicted twoF.
h0 (float) – Parameters at which to compute the cumulative predicted twoF.
cosi (float) – Parameters at which to compute the cumulative predicted twoF.
psi (float) – Parameters at which to compute the cumulative predicted twoF.
tstart (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime. If outside those: autotruncated.
tend (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime. If outside those: autotruncated.
num_segments (int) – Number of segments to split [tstart,tend] into.
predict_fstat_kwargs – Other kwargs to be passed to helper_functions.predict_fstat().
 Returns
tstart (int) – GPS start time of the observation span.
cumulative_durations (ndarray of shape (num_segments,)) – Offsets of each segment’s tend from the overall tstart.
pfs (ndarray of size (num_segments,)) – Predicted 2F for each segment.
pfs_sigma (ndarray of size (num_segments,)) – Standard deviations of predicted 2F.

plot_twoF_cumulative
(CFS_input, PFS_input=None, tstart=None, tend=None, num_segments_CFS=1000, num_segments_PFS=10, custom_ax_kwargs=None, savefig=False, label=None, outdir=None, **PFS_kwargs)[source]¶ Plot how 2F accumulates over time.
This compares the accumulation on the actual data set (‘CFS’, from self.calculate_twoF_cumulative()) against (optionally) the average expectation (‘PFS’, from self.predict_twoF_cumulative()).
 Parameters
CFS_input (dict) – Input arguments for self.calculate_twoF_cumulative() (besides [tstart, tend, num_segments]).
PFS_input (dict) – Input arguments for self.predict_twoF_cumulative() (besides [tstart, tend, num_segments]). If None: do not calculate predicted 2F.
tstart (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime. If outside those: autotruncated.
tend (int or None) – GPS times to restrict the range of data used. If None: falls back to self.minStartTime and self.maxStartTime. If outside those: autotruncated.
num_segments_(CFSPFS) (int) – Number of time segments to (computepredict) twoF.
custom_ax_kwargs (dict) – Optional axis formatting options.
savefig (bool) – If true, save the figure in outdir. If false, return an axis object without saving to disk.
label (str) – Output filename will be constructed by appending _twoFcumulative.png to this label. (Ignored unless savefig=true.)
outdir (str) – Output folder (ignored unless savefig=true).
PFS_kwargs (dict) – Other kwargs to be passed to self.predict_twoF_cumulative().
 Returns
ax – The axes object containing the plot.
 Return type
matplotlib.axes._subplots_AxesSubplot, optional

write_atoms_to_file
(fnamebase='')[source]¶ Save Fstatistic atoms (timedependent quantities) for a given parameterspace point.
 Parameters
fnamebase (str) – Basis for output filename, full name will be {fnamebase}_Fstatatoms_{dopplerName}.dat where dopplerName is a canonical lalpulsar formatting of the ‘Doppler’ parameter space point (frequencyevolution parameters).

class
pyfstat.core.
SemiCoherentSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.ComputeFstat
A simple semicoherent search class.
This will split the data set into multiple segments, run a coherent Fstat search over each, and produce a final semicoherent detection statistic as the sum over segments.
This does not include any concept of refinement between the two steps, as some gridbased semicoherent search algorithms do; both the persegment coherent Fstatistics and the incoherent sum are done at the same parameter space point.
The implementation is based on a simple trick using the transient Fstat map functionality: basic Fstat atoms are computed only once over the full data set, then the transient code with rectangular ‘windows’ is used to compute the persegment Fstats, and these are summed to get the semicoherent result.
Only parameters with a special meaning for SemiCoherentSearch itself are explicitly documented here. For all other parameters inherited from pyfstat.ComputeFStat see the documentation of that class.
 Parameters
label (str) – A label and directory to read/write data from/to.
outdir (str) – A label and directory to read/write data from/to.
tref (int) – GPS seconds of the reference time.
nsegs (int) – The (fixed) number of segments to split the data set into.
sftfilepattern (str) – Pattern to match SFTs using wildcards (*?) and ranges [09]; multiple patterns can be given separated by colons.
minStartTime (int) – Only use SFTs with timestamps starting from this range, following the XLALCWGPSinRange convention: halfopen intervals [minStartTime,maxStartTime]. Also used to set up segment boundaries, i.e. maxStartTimeminStartTime will be divided by nsegs to obtain the persegment coherence time Tcoh.
maxStartTime (int) – Only use SFTs with timestamps starting from this range, following the XLALCWGPSinRange convention: halfopen intervals [minStartTime,maxStartTime]. Also used to set up segment boundaries, i.e. maxStartTimeminStartTime will be divided by nsegs to obtain the persegment coherence time Tcoh.

init_semicoherent_parameters
()[source]¶ Set up a list of equallength segments and the corresponding transient windows.
For a requested number of segments self.nsegs, self.tboundaries will have self.nsegs+1 entries covering [self.minStartTime,self.maxStartTime] and self.Tcoh will be the total duration divided by self.nsegs.
Each segment is required to be at least two SFTs long.f

get_semicoherent_det_stat
(F0, F1, F2, Alpha, Delta, asini=None, period=None, ecc=None, tp=None, argp=None, record_segments=False)[source]¶ Computes the detection statistic (twoF or log10BSGL) semicoherently at a single point.
As the basic statistic of this class, self.twoF is always computed. If self.BSGL, additionally the singledetector 2Fstat values are saved in self.twoFX.
 Parameters
F0 (float) – Parameters at which to compute the statistic.
F1 (float) – Parameters at which to compute the statistic.
F2 (float) – Parameters at which to compute the statistic.
Alpha (float) – Parameters at which to compute the statistic.
Delta (float) – Parameters at which to compute the statistic.
asini (float, optional) – Optional: Binary parameters at which to compute the statistic.
period (float, optional) – Optional: Binary parameters at which to compute the statistic.
ecc (float, optional) – Optional: Binary parameters at which to compute the statistic.
tp (float, optional) – Optional: Binary parameters at which to compute the statistic.
argp (float, optional) – Optional: Binary parameters at which to compute the statistic.
record_segments (boolean) – If True, store the persegment Fstat values as self.twoF_per_segment and (if self.BSGL=True) the perdetector persegment Fstats as self.twoFX_per_segment.
 Returns
stat – A single value of the detection statistic (semicoherent twoF or log10BSGL) at the input parameter values. Also stored as self.twoF or self.log10BSGL.
 Return type
float

get_semicoherent_twoF
(F0, F1, F2, Alpha, Delta, asini=None, period=None, ecc=None, tp=None, argp=None, record_segments=False)[source]¶ Computes the semicoherent twoF statistic at a single point.
 Parameters
F0 (float) – Parameters at which to compute the statistic.
F1 (float) – Parameters at which to compute the statistic.
F2 (float) – Parameters at which to compute the statistic.
Alpha (float) – Parameters at which to compute the statistic.
Delta (float) – Parameters at which to compute the statistic.
asini (float, optional) – Optional: Binary parameters at which to compute the statistic.
period (float, optional) – Optional: Binary parameters at which to compute the statistic.
ecc (float, optional) – Optional: Binary parameters at which to compute the statistic.
tp (float, optional) – Optional: Binary parameters at which to compute the statistic.
argp (float, optional) – Optional: Binary parameters at which to compute the statistic.
record_segments (boolean) – If True, store the persegment Fstat values as self.twoF_per_segment.
 Returns
twoF – A single value of the semicoherent twoF statistic at the input parameter values. Also stored as self.twoF.
 Return type
float

get_semicoherent_single_IFO_twoFs
(record_segments=False)[source]¶ Computes the semicoherent singledetector Fstatss at a single point.
This requires self.get_semicoherent_twoF() to be run first.
 Parameters
record_segments (boolean) – If True, store the perdetector persegment Fstat values as self.twoFX_per_segment.
 Returns
twoFX – A list of the singledetector detection statistics twoF. Also stored as self.twoFX.
 Return type
list

get_semicoherent_log10BSGL
()[source]¶ Computes the semicoherent log10BSGL statistic at a single point.
This requires self.get_semicoherent_twoF() and self.get_semicoherent_single_IFO_twoFs() to be run first.
 Returns
log10BSGL – A single value of the semicoherent log10BSGL statistic at the input parameter values. Also stored as self.log10BSGL.
 Return type
float

class
pyfstat.core.
SearchForSignalWithJumps
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.BaseSearchClass
Internal helper class with some useful methods for glitches or timing noise.
Users should never need to interact with this class, just with the derived search classes.

class
pyfstat.core.
SemiCoherentGlitchSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.SearchForSignalWithJumps
,pyfstat.core.ComputeFstat
A semicoherent search for CW signals from sources with timing glitches.
This implements a basic semicoherent Fstat search in which the data is divided into segments either side of the proposed glitch epochs and the fullycoherent Fstat in each segment is summed to give the semicoherent Fstat.
Only parameters with a special meaning for SemiCoherentGlitchSearch itself are explicitly documented here. For all other parameters inherited from pyfstat.ComputeFStat see the documentation of that class.
 Parameters
label (str) – A label and directory to read/write data from/to.
outdir (str) – A label and directory to read/write data from/to.
tref (int) – GPS seconds of the reference time, and start and end of the data.
minStartTime (int) – GPS seconds of the reference time, and start and end of the data.
maxStartTime (int) – GPS seconds of the reference time, and start and end of the data.
nglitch (int) – The (fixed) number of glitches. This is also allowed to be zero, but occasionally this causes issues, in which case please use the basic ComputeFstat class instead.
sftfilepattern (str) – Pattern to match SFTs using wildcards (*?) and ranges [09]; multiple patterns can be given separated by colons.
theta0_idx (int) – Index (zerobased) of which segment the theta (searched parameters) refer to. This is useful if providing a tight prior on theta to allow the signal to jump to theta (and not just from).

get_semicoherent_nglitch_twoF
(F0, F1, F2, Alpha, Delta, *args)[source]¶ Returns the semicoherent glitch summed twoF.
 Parameters
F0 (float) – Parameters at which to compute the statistic.
F1 (float) – Parameters at which to compute the statistic.
F2 (float) – Parameters at which to compute the statistic.
Alpha (float) – Parameters at which to compute the statistic.
Delta (float) – Parameters at which to compute the statistic.
args (dict) – Additional arguments for the glitch parameters; see the source code for full details.
 Returns
twoFSum – A single value of the semicoherent summed detection statistic at the input parameter values.
 Return type
float
pyfstat.grid_based_searches module¶
PyFstat search classes using gridbased methods.

class
pyfstat.grid_based_searches.
GridSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.BaseSearchClass
A search evaluating the Fstatistic over a regular grid in parameter space.
This implements a simple ‘square box’ grid with fixed spacing and ranges in each dimension, i.e. for each parameter there’s a simple 1D list of grid points and the total grid is just the Cartesian product of these.
For N parameter space dimensions and a total of M points in the product grid, the basic output is a (N+1,M)dimensional array with the detection statistic (twoF or log10BSGL) appended.
NOTE: if a large number of grid points are used, checks against cached data may be slow as the array is loaded into memory. To avoid this, run with the clean option which uses a generator instead.
Most parameters are the same as for the core.ComputeFstat class, only the additional ones are documented here:
 Parameters
label (str) – Output filenames will be constructed using this label.
outdir (str) – Output directory.
F0s (tuple) – A length 3 tuple describing the grid for each parameter, e.g [F0min, F0max, dF0]. Alternatively, for a fixed value simply give [F0]. Unless input_arrays=True, then these are the exact arrays to search over.
F1s (tuple) – A length 3 tuple describing the grid for each parameter, e.g [F0min, F0max, dF0]. Alternatively, for a fixed value simply give [F0]. Unless input_arrays=True, then these are the exact arrays to search over.
F2s (tuple) – A length 3 tuple describing the grid for each parameter, e.g [F0min, F0max, dF0]. Alternatively, for a fixed value simply give [F0]. Unless input_arrays=True, then these are the exact arrays to search over.
Alphas (tuple) – A length 3 tuple describing the grid for each parameter, e.g [F0min, F0max, dF0]. Alternatively, for a fixed value simply give [F0]. Unless input_arrays=True, then these are the exact arrays to search over.
Deltas (tuple) – A length 3 tuple describing the grid for each parameter, e.g [F0min, F0max, dF0]. Alternatively, for a fixed value simply give [F0]. Unless input_arrays=True, then these are the exact arrays to search over.
nsegs (int) – Number of segments to split the data set into. If nsegs=1, the basic ComputeFstat class is used. If nsegs>1, the SemiCoherentSearch class is used.
input_arrays (bool) – If true, use the F0s, F1s, etc as arrays just as they are given (do not interpret as 3tuples of [min,max,step]).

tex_labels
= {'Alpha': '$\\alpha$', 'Delta': '$\\delta$', 'F0': '$f$', 'F1': '$\\dot{f}$', 'F2': '$\\ddot{f}$', 'log10BSGL': '$\\log_{10}\\mathcal{B}_{\\mathrm{SGL}}$', 'twoF': '$\\widetilde{2\\mathcal{F}}$'}¶ Formatted labels used for plot annotations.

tex_labels0
= {'Alpha': '$\\alpha_0$', 'Delta': '$\\delta_0$', 'F0': '$f_0$', 'F1': '$\\dot{f}_0$', 'F2': '$\\ddot{f}_0$'}¶ Formatted labels used for annotating central values in plots.

fmt_detstat
= '%.9g'¶ Standard output precision for detection statistics.

check_old_data_is_okay_to_use
()[source]¶ Check if an existing output file matches this search and reuse the results.
Results will be loaded from old output file, and no new search run, if all of the following checks pass:
Output file with matching name found in outdir.
Output file is not older than SFT files matching sftfilepattern.
Parameters string in file header matches current search setup.
Data in old file can be loaded successfully, its input parts (i.e. minus the detection statistic columns) matches in dimension with current grid, and the values in those input columns match with the current grid.
Through helper_functions.read_txt_file_with_header(), the existing file is read in with np.genfromtxt().

run
(return_data=False)[source]¶ Execute the actual search over the full grid.
This iterates over all points in the multidimensional product grid and the end result is either returned as a numpy array or saved to disk.
 Parameters
return_data (boolean) – If true, the final inputs+outputs data set is returned as a numpy array. If false, it is saved to disk and nothing is returned.
 Returns
data – The final inputs+outputs data set. Only if return_data=true.
 Return type
np.ndarray

save_array_to_disk
()[source]¶ Save the results array to a txt file.
This includes a header with version and parameters information.
It should be flexible enough to be reused by child classes, as long as the _get_savetxt_fmt_dict() method is suitably overridden to account for any additional parameters.

plot_1D
(xkey, ax=None, x0=None, xrescale=1, savefig=True, xlabel=None, ylabel=None, agg_chunksize=None)[source]¶ Make a plot of the detection statistic over a single grid dimension.
 Parameters
xkey (str) – The name of the search parameter to plot against.
ax (matplotlib.axes._subplots_AxesSubplot or None) – An optional preexisting axes set to draw into.
x0 (float or None) – Plot x values relative to this central value.
xrescale (float) – Rescale all x values by this factor.
savefig (bool) – If true, save the figure in self.outdir. If false, return an axis object without saving to disk.
xlabel (str or None) – Override default text label for the xaxis.
ylabel (str or None) – Override default text label for the yaxis.
agg_chunksize (int or None) – Set this to some high value to work around matplotlib ‘Exceeded cell block limit’ errors.
 Returns
ax – The axes object containing the plot, only if savefig=false.
 Return type
matplotlib.axes._subplots_AxesSubplot, optional

plot_2D
(xkey, ykey, ax=None, savefig=True, vmin=None, vmax=None, add_mismatch=None, xN=None, yN=None, flat_keys=[], rel_flat_idxs=[], flatten_method=<function amax>, title=None, predicted_twoF=None, cm=None, cbarkwargs={}, x0=None, y0=None, colorbar=False, xrescale=1, yrescale=1, xlabel=None, ylabel=None, zlabel=None)[source]¶ Plots the detection statistic over a 2D grid.
FIXME: this will currently fail if the search went over >2 dimensions.
 Parameters
xkey (str) – The name of the first search parameter to plot against.
ykey (str) – The name of the second search parameter to plot against.
ax (matplotlib.axes._subplots_AxesSubplot or None) – An optional preexisting axes set to draw into.
savefig (bool) – If true, save the figure in self.outdir. If false, return an axis object without saving to disk.
vmin (float or None) – Cutoffs for rescaling the colormap.
vmax (float or None) – Cutoffs for rescaling the colormap.
add_mismatch (tuple or None) – If given a tuple (xhat, yhat, Tseg), add a secondary axis with the metric mismatch from the point (xhat, yhat) with duration Tseg.
xN (int or None) – Number of tick label intervals.
yN (int or None) – Number of tick label intervals.
flat_keys (list) – Keys to be used in flattening higherdimensional arrays.
rel_flat_idxs (list) – Indices to be used in flattening higherdimensional arrays.
flatten_method (numpy function) – Function to use in flattening the flat_keys, default: np.max.
title (str or None) – Optional plot title text.
predicted_twoF (float or None) – Expected/predicted value of twoF, used to rescale the zaxis.
cm (matplotlib.colors.ListedColormap or None) – Override standard (viridis) colormap.
cbarkwargs (dict) – Additional arguments for colorbar formatting.
x0 (float) – Plot x values relative to this central value.
y0 (float) – Plot y values relative to this central value.
xrescale (float) – Rescale all x values by this factor.
yrescale (float) – Rescale all y values by this factor.
xlabel (str) – Override default text label for the xaxis.
ylabel (str) – Override default text label for the yaxis.
zlabel (str) – Override default text label for the zaxis.
 Returns
ax – The axes object containing the plot, only if savefig=false.
 Return type
matplotlib.axes._subplots_AxesSubplot, optional

get_max_det_stat
()[source]¶ Get the maximum detection statistic over the grid.
This requires the run() method to have been called before.
 Returns
d – Dictionary containing parameters and detection statistic at the maximum.
 Return type
dict

get_max_twoF
()[source]¶ Get the maximum twoF over the grid.
This requires the run() method to have been called before.
 Returns
d – Dictionary containing parameters and twoF value at the maximum.
 Return type
dict

print_max_twoF
()[source]¶ Get and print the maximum twoF point over the grid.
This prints out the full dictionary from get_max_twoF(), i.e. the maximum value and its corresponding parameters.

set_out_file
(extra_label=None)[source]¶ Set (or reset) the name of the main output file.
File will always be stored in self.outdir and the base of the name be determined from self.label and other parts of the search setup, but this method allows to attach an extra_label bit if desired.
 Parameters
extra_label (str) – Additional text bit to be attached at the end of the filename (but before the extension).

class
pyfstat.grid_based_searches.
TransientGridSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.grid_based_searches.GridSearch
A search for transient CWlike signals using the Fstatistic.
This is based on the transient signal model and transientFstat algorithm from Prix, Giampanis & Messenger (PRD 84, 023007, 2011): https://arxiv.org/abs/1104.1704
The frequency evolution parameters are searched over in a grid just like in the normal GridSearch, then at each point the timedependent ‘atoms’ are used to evaluate partial sums of the Fstatistic over a 2D array in transient start times t0 and duration parameters tau.
The signal templates are modulated by a ‘transient window function’ which can be
none (standard, persistent CW signal)
rect (rectangular: constant amplitude within [t0,t0+tau], zero outside)
exp (exponential decay over [t0,t0+3*tau], zero outside)
This class currently only supports fullycoherent searches (nsegs=1 is hardcoded).
Also see Keitel & Ashton (CQG 35, 205003, 2018): https://arxiv.org/abs/1805.05652 for a detailed discussion of the GPU implementation.
Most parameters are the same as for GridSearch and the core.ComputeFstat class, only the additional ones are documented here:
 Parameters
transientWindowType (str) – If rect or exp, allow for the Fstat to be computed over a transient range. (none instead of None explicitly calls the transientwindow function, but with the full range, for debugging.)
t0Band (int) – Search ranges for transient starttime t0 and duration tau. If >0, search t0 in (minStartTime,minStartTime+t0Band) and tau in (tauMin,2*Tsft+tauBand). If =0, only compute the continuouswave Fstat with t0=minStartTime, tau=maxStartTimeminStartTime.
tauBand (int) – Search ranges for transient starttime t0 and duration tau. If >0, search t0 in (minStartTime,minStartTime+t0Band) and tau in (tauMin,2*Tsft+tauBand). If =0, only compute the continuouswave Fstat with t0=minStartTime, tau=maxStartTimeminStartTime.
tauMin (int) – Minimum transient duration to cover, defaults to 2*Tsft.
dt0 (int) – Grid resolution in transient starttime, defaults to Tsft.
dtau (int) – Grid resolution in transient duration, defaults to Tsft.
outputTransientFstatMap (bool) – If true, write additional output files for (t0,tau) Fstat maps. (One file for each grid point!)
outputAtoms (bool) – If true, write additional output files for the Fstat atoms. (One file for each grid point!)
tCWFstatMapVersion (str) – Choose between implementations of the transient Fstatistic funcionality: standard lal implementation, pycuda for GPU version, and some others only for devel/debug.
cudaDeviceName (str) – GPU name to be matched against drv.Device output, only for tCWFstatMapVersion=pycuda.

run
(return_data=False)[source]¶ Execute the actual search over the full grid.
This iterates over all points in the multidimensional product grid and the end result is either returned as a numpy array or saved to disk.
If the outputTransientFstatMap or outputAtoms options have been set when initiating the search, additional files are written for each frequencyevolution parameterspace point (‘Doppler’ point).
 Parameters
return_data (boolean) – If true, the final inputs+outputs data set is returned as a numpy array. If false, it is saved to disk and nothing is returned.
 Returns
data – The final inputs+outputs data set. Only if return_data=true.
 Return type
np.ndarray

get_transient_fstat_map_filename
(param_point)[source]¶ Filename convention for given grid point: freq_alpha_delta_f1dot_f2dot
 Parameters
param_point (tuple, dict, list, np.void or np.ndarray) – A multidimensional parameter point. If not a type with named fields (e.g. a plain tuple or list), the order must match that of self.output_keys.
 Returns
f – The constructed filename.
 Return type
str

class
pyfstat.grid_based_searches.
SliceGridSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.DefunctClass

last_supported_version
= '1.9.0'¶


class
pyfstat.grid_based_searches.
GridUniformPriorSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.DefunctClass

last_supported_version
= '1.9.0'¶


class
pyfstat.grid_based_searches.
GridGlitchSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.grid_based_searches.GridSearch
A grid search using the SemiCoherentGlitchSearch class.
This implements a basic semicoherent Fstat search in which the data is divided into segments either side of the proposed glitch epochs and the fullycoherent Fstat in each segment is summed to give the semicoherent Fstat.
This class currently only works for a single glitch in the observing time.
Most parameters are the same as for GridSearch and the core.SemiCoherentGlitchSearch class, only the additional ones are documented here:
 Parameters
delta_F0s (tuple) – A length 3 tuple describing the grid of frequency jumps, or just [delta_F0] for a fixed value.
delta_F1s (tuple) – A length 3 tuple describing the grid of spindown parameter jumps, or just [delta_F1] for a fixed value.
tglitchs (tuple) – A length 3 tuple describing the grid of glitch epochs, or just [tglitch] for a fixed value. These are relative time offsets, referenced to zero at minStartTime.

class
pyfstat.grid_based_searches.
SlidingWindow
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.DefunctClass

last_supported_version
= '1.9.0'¶


class
pyfstat.grid_based_searches.
FrequencySlidingWindow
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.DefunctClass

last_supported_version
= '1.9.0'¶


class
pyfstat.grid_based_searches.
EarthTest
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.DefunctClass

last_supported_version
= '1.9.0'¶


class
pyfstat.grid_based_searches.
DMoff_NO_SPIN
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.DefunctClass

last_supported_version
= '1.9.0'¶

pyfstat.gridcorner module¶
A corner plotting tool for an array (grid) of dependent values.
Given an Ndimensional set of data (i.e. some function evaluated over a grid of coordinates), plot all possible 1D and 2D projections in the style of a ‘corner’ plot.
This code has been copied from Gregory Ashton’s repository https://gitlab.aei.unihannover.de/GregAshton/gridcorner and it uses both the central idea and some specific code from Daniel ForemanMackey’s https://github.com/dfm/corner.py reused under the following licence requirements:
Copyright (c) 20132020 Daniel ForemanMackey
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of the FreeBSD Project.

pyfstat.gridcorner.
log_mean
(loga, axis)[source]¶ Calculate the log(<a>) mean
Given N logged value log, calculate the log_mean log(<loga>)=log(sum(np.exp(loga)))  log(N). Useful for marginalizing over logged likelihoods for example.
 Parameters
loga (array_like) – Input_array.
axies (None or int or type of ints, optional) – Axis or axes over which the sum is taken. By default axis is None, and all elements are summed.
 Returns
log_mean – The logged average value (shape loga.shape)
 Return type
ndarry

pyfstat.gridcorner.
idx_array_slice
(D, axis, slice_idx)[source]¶ Return the slice along the given axis

pyfstat.gridcorner.
gridcorner
(D, xyz, labels=None, projection='max_slice', max_n_ticks=4, factor=2, whspace=0.05, showDvals=True, lines=None, label_offset=0.4, **kwargs)[source]¶ Generate a grid corner plot
 Parameters
D (array_like) – Ndimensional data to plot, D.shape should be (n1, n2,…, nN), where N, is the number of grid points along dimension i.
xyz (list) – List of 1dimensional arrays of coordinates. xyz[i] should have length N (see help for D).
labels (list) – N+1 length list of labels; the first N correspond to the coordinates labels, the final label is for the dependent (D) variable.
projection (str or func) – If a string, one of {“log_mean”, “max_slice”} to use inbuilt functions to calculate either the logged mean or maximum slice projection. Else a function to use for projection, must take an `axis argument. Default is gridcorner.max_slice(), to project out a slice along the maximum.
max_n_ticks (int) – Number of ticks for x and y axis of the pcolormesh plots.
factor (float) – Controls the size of one window.
showDvals (bool) – If true (default) show the D values on the righthandside of the 1D plots and add a label.
lines (array_like) – Ndimensional list of values to delineate.
 Returns
The figure and NxN set of axes
 Return type
fig, axes
pyfstat.helper_functions module¶
A collection of helpful functions to facilitate easeofuse of PyFstat.
Most of these are used internally by other parts of the package and are of interest mostly only for developers, but others can also be helpful for end users.

pyfstat.helper_functions.
set_up_optional_tqdm
()[source]¶ Provides local replacement for tqdm if it cannot be imported.

pyfstat.helper_functions.
set_up_matplotlib_defaults
()[source]¶ Sets some defaults for matplotlib plotting.

pyfstat.helper_functions.
set_up_command_line_arguments
()[source]¶ Parse global commandline arguments.

pyfstat.helper_functions.
get_ephemeris_files
()[source]¶ Set the ephemeris files to use for the Earth and Sun.
This looks first for a configuration file ~/.pyfstat.conf and next in the $LALPULSAR_DATADIR environment variable.
If neither source provides the necessary files, a warning is emitted and the user can still run PyFstat searches, but must then include ephemeris options manually on each class instantiation.
The ‘DE405’ ephemerides version provided with lalpulsar is expected.
 Returns
earth_ephem, sun_ephem – Paths of the two files containing positions of Earth and Sun.
 Return type
str

pyfstat.helper_functions.
round_to_n
(x, n)[source]¶ Simple rounding function for getting a fixed number of digits.
 Parameters
x (float) – The number to round.
n (int) – The number of digits to round to (before plus after the decimal separator).
 Returns
rounded – The rounded number.
 Return type
float

pyfstat.helper_functions.
texify_float
(x, d=2)[source]¶ Format float numbers nicely for LaTeX output, including rounding.
Numbers with absolute values between 0.01 and 100 will be returned in plain float format, while smaller or larger numbers will be returned in powersoften notation.
 Parameters
x (float) – The number to round and format.
n (int) – The number of digits to round to (before plus after the decimal separator).
 Returns
formatted – The formatted string.
 Return type
str

pyfstat.helper_functions.
initializer
(func)[source]¶ Decorator to automatically assign the parameters of a class instantiation to self.

pyfstat.helper_functions.
get_peak_values
(frequencies, twoF, threshold_2F, F0=None, F0range=None)[source]¶ Find a set of local peaks of twoF values over a 1D frequency list.
 Parameters
frequencies (np.ndarray) – 1D array of frequency values.
twoF (np.ndarray) – Corresponding 1D array of detection statistic values.
threshold_2F (float) – Only report peaks above this threshold.
F0 (float or None) – Only report peaks within [F0F0range,F0+F0range].
F0range (float or None) – Only report peaks within [F0F0range,F0+F0range].
 Returns
F0maxs (np.ndarray) – 1D array of peak frequencies.
twoFmaxs (np.ndarray) – 1D array of peak twoF values.
freq_errs (np.ndarray) – 1D array of peak frequency estimation error, taken as the spacing between neighbouring input frequencies.

pyfstat.helper_functions.
get_comb_values
(F0, frequencies, twoF, period, N=4)[source]¶ Check which points of a [frequencies,twoF] set correspond to a certain comb of frequencies.
 Parameters
F0 (float) – Base frequency for the comb.
frequencies (np.ndarray) – 1D array of frequency values.
twoF (np.ndarray) – Corresponding 1D array of detection statistic values.
period (str) – Modulation type of the comb, either sidereal or terrestrial.
N (int) – Number of comb harmonics.
 Returns
comb_frequencies (np.ndarray) – 1D array of relative frequency offsets for the comb harmonics.
comb_twoFs (np.ndarray) – 1D array of twoF values at the closestmatching frequencies.
freq_errs (np.ndarray) – 1D array of frequency match error, taken as the spacing between neighbouring input frequencies.

pyfstat.helper_functions.
run_commandline
(cl, log_level=20, raise_error=True, return_output=True)[source]¶ Run a string cmd as a subprocess, check for errors and return output.
 Parameters
cl (str) – Command to run
log_level (int) – Sets the logging level for some of this function’s messages. See https://docs.python.org/library/logging.html#logginglevels Default is ‘20’ (INFO). FIXME: Not used for all messages.
raise_error (bool) – If True, raise an error if the subprocess fails. If False, continue and just return 0.
return_output (bool) – If True, return the captured output of the subprocess (stdout and stderr). If False, return nothing on successful execution.
 Returns
out – The captured output of the subprocess (stdout and stderr) if return_output=True. 0 on failed execution if raise_error=False.
 Return type
str or int, optional

pyfstat.helper_functions.
convert_array_to_gsl_matrix
(array)[source]¶ Convert a numpy array to a LALwrapped GSL matrix.
 Parameters
array (np.ndarray) – The array to convert. array.shape must have 2 dimensions.
 Returns
gsl_matrix – The LALwrapped GSL matrix object.
 Return type
lal.gsl_matrix

pyfstat.helper_functions.
get_sft_array
(sftfilepattern, F0=None, dF0=None)[source]¶ Return the raw data (absolute values) from a set of SFTs.
FIXME: currently only returns data for first detector.
 Parameters
sftfilepattern (str) – Pattern to match SFTs using wildcards (*?) and ranges [09]; multiple patterns can be given separated by colons.
F0 (float or None) – Restrict frequency range to [F0dF0,F0+dF0].
dF0 (float or None) – Restrict frequency range to [F0dF0,F0+dF0].
 Returns
times (np.ndarray) – The SFT starttimes as a 1D array.
freqs (np.ndarray) – The frequency bins in each SFT. These will be the same for each SFT, so only a single 1D array is returned.
data (np.ndarray) – A 2D array of the absolute values of the SFT data in each frequency bin at each timestamp.

pyfstat.helper_functions.
get_covering_band
(tref, tstart, tend, F0, F1, F2, F0band=0.0, F1band=0.0, F2band=0.0, maxOrbitAsini=0.0, minOrbitPeriod=0.0, maxOrbitEcc=0.0)[source]¶ Get the covering band for CW signals for given time and parameter ranges.
This uses the lalpulsar function XLALCWSignalCoveringBand(), accounting for the spin evolution of the signals within the given [F0,F1,F2] ranges, the maximum possible Dopper modulation due to detector motion (i.e. for the worstcase sky locations), and for worstcase binary orbital motion.
 Parameters
tref (int) – Reference time (in GPS seconds) for the signal parameters.
tstart (int) – Start time (in GPS seconds) for the signal evolution to consider.
tend (int) – End time (in GPS seconds) for the signal evolution to consider.
F0 (float) – Minimum frequency and spindown of signals to be covered.
F1 (float) – Minimum frequency and spindown of signals to be covered.
F1 – Minimum frequency and spindown of signals to be covered.
F0band (float) – Ranges of frequency and spindown of signals to be covered.
F1band (float) – Ranges of frequency and spindown of signals to be covered.
F1band – Ranges of frequency and spindown of signals to be covered.
maxOrbitAsini (float) – Largest orbital projected semimajor axis to be covered.
minOrbitPeriod (float) – Shortest orbital period to be covered.
maxOrbitEcc (float) – Highest orbital eccentricity to be covered.
 Returns
minCoverFreq, maxCoverFreq – Estimates of the minimum and maximum frequencies of the signals from the given parameter ranges over the [tstart,tend] duration.
 Return type
float

pyfstat.helper_functions.
match_commandlines
(cl1, cl2, be_strict_about_full_executable_path=False)[source]¶ Check if two commandline strings match elementbyelement, regardless of order.
 Parameters
cl1 (str) – Commandline strings of executable –key1=val1 –key2=val2 etc format.
cl2 (str) – Commandline strings of executable –key1=val1 –key2=val2 etc format.
be_strict_about_full_executable_path (bool) – If False (default), only checks the basename of the executable. If True, requires its full path to match.
 Returns
match – Whether the executable and all key=val pairs of the two strings matched.
 Return type
bool

pyfstat.helper_functions.
get_version_string
()[source]¶ Get the canonical version string of the currently running PyFstat instance.
 Returns
version – The version string.
 Return type
str

pyfstat.helper_functions.
get_doppler_params_output_format
(keys)[source]¶ Set a canonical output precision for frequency evolution parameters.
This uses the same format (%.16g) as the write_FstatCandidate_to_fp() function of lalapps_ComputeFstatistic_v2.
This assigns that format to each parameter name in keys which matches a hardcoded list of known standard ‘Doppler’ parameters, and ignores any others.
 Parameters
keys (dict) – The parameter keys for which to select formats.
 Returns
fmt – A dictionary assigning the default format to each parameter key from the hardcoded list of standard ‘Doppler’ parameters.
 Return type
dict

pyfstat.helper_functions.
read_txt_file_with_header
(f, names=True, comments='#')[source]¶ Wrapper to np.genfromtxt with smarter handling of variablelength commented headers.
The header is identified as an uninterrupted block of lines from the beginning of the file, each starting with the given comments character.
After identifying a header of length Nhead, this function then tells np.genfromtxt() to skip Nhead1 lines (to allow for reading field names from the last commented line before the actual data starts).
 Parameters
f (str) – Name of the file to read.
names (bool) – Passed on to np.genfromtxt(): If True, the field names are read from the last header line.
comments (str) – The character used to indicate the start of a comment. Also passed on to np.genfromtxt().
 Returns
data – The data array read from the file after skipping the header.
 Return type
np.ndarray

pyfstat.helper_functions.
get_lalapps_commandline_from_SFTDescriptor
(descriptor)[source]¶ Extract a lalapps commandline from the ‘comment’ entry of a SFT descriptor.
Most SFT creation tools save their commandline into that entry, so we can extract it and reuse it to reproduce that data.
 Parameters
descriptor (SFTDescriptor) – Element of a lalpulsar.SFTCatalog structure.
 Returns
cmd – A lalapps commandline string, or an empty string if ‘lalapps’ not found in comment.
 Return type
str

pyfstat.helper_functions.
read_parameters_dict_lines_from_file_header
(outfile, comments='#', strip_spaces=True)[source]¶ Load a list of prettyprinted parameters dictionary lines from a commented file header.
Returns a list of lines from a commented file header that match the prettyprinted parameters dictionary format as generated by BaseSearchClass.get_output_file_header(). The opening/closing bracket lines ({,`}`) are not included. Newline characters at the end of each line are stripped.
 Parameters
outfile (str) – Name of a PyFstatproduced output file.
comments (str) – Comment character used to start header lines.
strip_spaces (bool) – Whether to strip leading/trailing spaces.
 Returns
dict_lines – A list of unparsed pprinted dictionary entries.
 Return type
list

pyfstat.helper_functions.
get_parameters_dict_from_file_header
(outfile, comments='#', eval_values=False)[source]¶ Load a parameters dict from a commented file header.
Returns a parameters dictionary, as generated by BaseSearchClass.get_output_file_header(), from an output file header. Always returns a proper python dictionary, but the values will be unparsed strings if not requested otherwise.
 Parameters
outfile (str) – Name of a PyFstatproduced output file.
comments (str) – Comment character used to start header lines.
eval_values (bool) – If False, return dictionary values as unparsed strings. If True, evaluate each of them. DANGER! Only do this if you trust the source of the file!
 Returns
params_dict – A dictionary of parameters (with values either as unparsed strings, or evaluated).
 Return type
dictionary

pyfstat.helper_functions.
read_par
(filename=None, label=None, outdir=None, suffix='par', comments=['%', '#'], raise_error=False)[source]¶ Read in a .par or .loudest file, returns a dictionary of the key=val pairs.
Notes
This can also be used to read in .loudest files produced by lalapps_ComputeFstatistic_v2, or any file which has rows of key=val data (in which the val can be understood using eval(val)).
 Parameters
filename (str) – Filename (path) containing rows of key=val data to read in.
label (str, optional) – If filename is None, form the file to read as outdir/label.suffix.
outdir (str, optional) – If filename is None, form the file to read as outdir/label.suffix.
suffix (str, optional) – If filename is None, form the file to read as outdir/label.suffix.
comments (str or list of strings, optional) – Characters denoting that a row is a comment.
raise_error (bool, optional) – If True, raise an error for lines which are not comments, but cannot be read.
 Returns
d – The key=val pairs as a dictionary.
 Return type
dict

pyfstat.helper_functions.
get_dictionary_from_lines
(lines, comments, raise_error)[source]¶ Return a dictionary of key=val pairs for each line in a list.
 Parameters
lines (list of strings) – The list of lines to parse.
comments (str or list of strings) – Characters denoting that a row is a comment.
raise_error (bool) – If True, raise an error for lines which are not comments, but cannot be read. Note that CFSv2 “loudest” files contain complex numbers which fill raise an error unless this is set to False.
 Returns
d – The key=val pairs as a dictionary.
 Return type
dict

pyfstat.helper_functions.
get_predict_fstat_parameters_from_dict
(signal_parameters)[source]¶ Extract a subset of parameters as needed for predicting Fstats.
Given a dictionary with arbitrary signal parameters, this extracts only those ones required by helper_functions.predict_fstat(): Freq, Alpha, Delta, h0, cosi, psi.
 Parameters
signal_parameters (dict) – Dictionary containing at least those signal parameters required by helper_functions.predict_fstat. This dictionary’s keys must follow the PyFstat convention (e.g. F0 instead of Freq).
 Returns
predict_fstat_params – The dictionary of selected parameters.
 Return type
dict

pyfstat.helper_functions.
predict_fstat
(h0=None, cosi=None, psi=None, Alpha=None, Delta=None, F0=None, sftfilepattern=None, timestampsFiles=None, minStartTime=None, duration=None, IFOs=None, assumeSqrtSX=None, tempory_filename='fs.tmp', earth_ephem=None, sun_ephem=None, transientWindowType='none', transientStartTime=None, transientTau=None)[source]¶ Wrapper to lalapps_PredictFstat for predicting expected Fstat values.
 Parameters
h0 (float) – Signal parameters, see lalapps_PredictFstat –help for more info.
cosi (float) – Signal parameters, see lalapps_PredictFstat –help for more info.
psi (float) – Signal parameters, see lalapps_PredictFstat –help for more info.
Alpha (float) – Signal parameters, see lalapps_PredictFstat –help for more info.
Delta (float) – Signal parameters, see lalapps_PredictFstat –help for more info.
F0 (float or None) – Signal frequency. Only needed for noise floor estimation when given sftfilepattern but assumeSqrtSX=None. The actual Fstat prediction is frequencyindependent.
sftfilepattern (str or None) – Pattern matching the SFT files to use for inferring detectors, timestamps and/or estimating the noise floor.
timestampsFiles (str or None) – Commaseparated list of perdetector files containing timestamps to use. Only used if sftfilepattern=None.
minStartTime (int or None) – If sftfilepattern given: used as optional constraints. If timestampsFiles given: ignored. If neither given: used as the interval for prediction.
duration (int or None) – If sftfilepattern given: used as optional constraints. If timestampsFiles given: ignored. If neither given: used as the interval for prediction.
IFOs (str or None) – Commaseparated list of detectors. Required if sftfilepattern=None, ignored otherwise.
assumeSqrtSX (float or str) – Assume stationary perdetector noisefloor instead of estimating from SFTs. Single float or str value: use same for all IFOs. Commaseparated string: must match len(IFOs) and/or the data in sftfilepattern. Detectors will be paired to list elements following alphabetical order. Required if sftfilepattern=None, optional otherwise..
tempory_filename (str) – Temporary file used for lalapps_PredictFstat output, will be deleted at the end.
earth_ephem (str or None) – Ephemerides files, defaults will be used if None.
sun_ephem (str or None) – Ephemerides files, defaults will be used if None.
transientWindowType (str) – Optional parameter for transient signals, see lalapps_PredictFstat –help. Default of none means a classical Continuous Wave signal.
transientStartTime (int or None) – Optional parameters for transient signals, see lalapps_PredictFstat –help.
transientTau (int or None) – Optional parameters for transient signals, see lalapps_PredictFstat –help.
 Returns
twoF_expected, twoF_sigma – The expectation and standard deviation of 2F.
 Return type
float

pyfstat.helper_functions.
parse_list_of_numbers
(val)[source]¶ Convert a number, list of numbers or commaseparated str into a list of numbers.
This is useful e.g. for sqrtSX inputs where the user can be expected to try either type of input.
 Parameters
val (float, list or str) – The input to be parsed.
 Returns
out – The parsed list.
 Return type
list
pyfstat.make_sfts module¶
PyFstat tools to generate and manipulate data in the form of SFTs.

exception
pyfstat.make_sfts.
KeyboardInterruptError
[source]¶ Bases:
Exception
Custom exception to allow overriding interrupts.

class
pyfstat.make_sfts.
InjectionParametersGenerator
(priors=None, seed=None)[source]¶ Bases:
object
Draw injection parameter samples from priors and return in dictionary format.
 Parameters
priors (dict) –
Each key refers to one of the signal’s parameters (following the PyFstat convention). Priors can be given as values in three formats (by order of evaluation):
1. Callable without required arguments: {“ParameterA”: np.random.uniform}.
2. Dict containing numpy.random distribution as key and kwargs in a dict as value: {“ParameterA”: {“uniform”: {“low”: 0, “high”:1}}}.
3. Constant value to be returned as is: {“ParameterA”: 1.0}.
seed – Argument to be fed to numpy.random.default_rng, with all of its accepted types.

set_priors
(new_priors)[source]¶ Set priors to draw parameter space points from.
 Parameters
new_priors (dict) – The new set of priors to update the object with.

class
pyfstat.make_sfts.
AllSkyInjectionParametersGenerator
(priors=None, seed=None)[source]¶ Bases:
pyfstat.make_sfts.InjectionParametersGenerator
Like InjectionParametersGenerator, but with hardcoded allsky priors.
This ensures uniform coverage of the 2D celestial sphere: uniform distribution in Alpha and sine distribution for Delta.
It assumes 1) PyFstat notation and 2) equatorial coordinates.
Alpha and Delta are given ‘restricted’ status to stop the user from changing them as long as using this special class.
 Parameters
priors (dict) –
Each key refers to one of the signal’s parameters (following the PyFstat convention). Priors can be given as values in three formats (by order of evaluation):
1. Callable without required arguments: {“ParameterA”: np.random.uniform}.
2. Dict containing numpy.random distribution as key and kwargs in a dict as value: {“ParameterA”: {“uniform”: {“low”: 0, “high”:1}}}.
3. Constant value to be returned as is: {“ParameterA”: 1.0}.
seed – Argument to be fed to numpy.random.default_rng, with all of its accepted types.

class
pyfstat.make_sfts.
Writer
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.BaseSearchClass
The main class for generating data in the form of SFTs.
Short Fourier Transforms (SFTs) are a standard data format used in LALSuite, containing the Fourier transform of strain data over a duration Tsft.
SFT data can be generated from scratch, including Gaussian noise and/or simulated CW signals or transient signals. Existing SFTs (real data or previously simulated) can also be reused through the noiseSFTs option, allowing to ‘inject’ additional signals into them.
This class currently relies on the lalapps_Makefakedata_v5 executable which will be run in a subprocess. See lalapps_Makefakedata_v5 –help for more detailed help with some of the parameters.
 Parameters
label (string) – A humanreadable label to be used in naming the output files.
tstart (int) – Starting GPS epoch of the data set.
duration (int) – Duration (in GPS seconds) of the total data set.
tref (float or None) – Reference time for simulated signals. Default is None, which sets the reference time to tstart.
F0 (float or None) – Frequency of a signal to inject. Also used (if Band is not None) as center of frequency band. Also needed when noiseonly (h0=None or h0==0) but no noiseSFTs given, in which case it is also used as center of frequency band.
F1 (float or None) – Additional frequency evolution and amplitude parameters for a signal. If h0=None or h0=0, these are all ignored. If h0>0, then at least [Alpha,Delta,cosi] need to be set explicitly.
F2 (float or None) – Additional frequency evolution and amplitude parameters for a signal. If h0=None or h0=0, these are all ignored. If h0>0, then at least [Alpha,Delta,cosi] need to be set explicitly.
Alpha (float or None) – Additional frequency evolution and amplitude parameters for a signal. If h0=None or h0=0, these are all ignored. If h0>0, then at least [Alpha,Delta,cosi] need to be set explicitly.
Delta (float or None) – Additional frequency evolution and amplitude parameters for a signal. If h0=None or h0=0, these are all ignored. If h0>0, then at least [Alpha,Delta,cosi] need to be set explicitly.
h0 (float or None) – Additional frequency evolution and amplitude parameters for a signal. If h0=None or h0=0, these are all ignored. If h0>0, then at least [Alpha,Delta,cosi] need to be set explicitly.
cosi (float or None) – Additional frequency evolution and amplitude parameters for a signal. If h0=None or h0=0, these are all ignored. If h0>0, then at least [Alpha,Delta,cosi] need to be set explicitly.
psi (float or None) – Additional frequency evolution and amplitude parameters for a signal. If h0=None or h0=0, these are all ignored. If h0>0, then at least [Alpha,Delta,cosi] need to be set explicitly.
phi (float or None) – Additional frequency evolution and amplitude parameters for a signal. If h0=None or h0=0, these are all ignored. If h0>0, then at least [Alpha,Delta,cosi] need to be set explicitly.
Tsft (int) – The SFT duration in seconds. Will be ignored if noiseSFTs are given.
outdir (str) – The directory where files are written to. Default: current working directory.
sqrtSX (float or list or str or None) – Singlesided PSD values for generating fake Gaussian noise. Single float or str value: use same for all detectors. List or commaseparated string: must match len(detectors). Detectors will be paired to list elements following alphabetical order.
noiseSFTs (str or None) – Existing SFT files on top of which signals will be injected. If not None, additional constraints can be applied using the arguments tstart and duration.
SFTWindowType (str or None) – LAL name of the windowing function to apply to the data.
SFTWindowBeta (float) – Optional parameter for some windowing functions.
Band (float or None) – If float, and F0 is also not None, then output SFTs cover [F0Band/2,F0+Band/2]. If None and noiseSFTs given, use their bandwidth. If None and no noiseSFTs given, a minimal covering band for a perfectlymatched singletemplate ComputeFstat analysis is estimated.
detectors (str or None) – Commaseparated list of detectors to generate data for.
earth_ephem (str or None) – Paths of the two files containing positions of Earth and Sun. If None, will check standard sources as per helper_functions.get_ephemeris_files().
sun_ephem (str or None) – Paths of the two files containing positions of Earth and Sun. If None, will check standard sources as per helper_functions.get_ephemeris_files().
transientWindowType (str) – If none, a fully persistent CW signal is simulated. If rect or exp, a transient signal with the corresponding amplitude evolution is simulated.
transientStartTime (int or None) – Start time for a transient signal.
transientTau (int or None) – Duration (rect case) or decay time (exp case) of a transient signal.
randSeed (int or None) – Optionally fix the random seed of Gaussian noise generation for reproducibility.

signal_parameter_labels
= ['tref', 'F0', 'F1', 'F2', 'Alpha', 'Delta', 'h0', 'cosi', 'psi', 'phi', 'transientWindowType']¶ Default convention of labels for the various signal parameters.

gps_time_and_string_formats_as_LAL
= {'refTime': ':10.9f', 'transientWindowType': ':s'}¶ Dictionary to ensure proper format handling for some special parameters.
GPS times should NOT be parsed using scientific notation. LAL routines would silently parse them wrongly.

tend
()[source]¶ Simple method to return tstart+duration.
If stored as an attribute, there would be the risk of it going out of sync with the other two values.

calculate_fmin_Band
()[source]¶ Set fmin and Band for the output SFTs to cover.
Either uses the userprovided Band and puts F0 in the middle, does nothing to later reuse the full bandwidth of noiseSFTs, or if F0!=None, noiseSFTs=None and Band=None it estimates a minimal band for just the injected signal: Fstat covering band plus extra bins for demod default parameters. This way a perfectly matched singletemplate ComputeFstat analysis should run through perfectly on the returned SFTs. For any widerband or mismatched search, one needs to set Band manually.
If you want to use noiseSFTs but autoestimate a minimal band, call helper_functions.get_covering_band() yourself and pass the results to Writer as fmin, Band.

make_cff
(verbose=False)[source]¶ Generates a .cff file including signal injection parameters.
This will be saved to self.config_file_name.
 Parameters
verbose (boolean) – If true, increase logging verbosity.

check_cached_data_okay_to_use
(cl_mfd)[source]¶ Check if SFT files already exist that can be reused.
This does not check the actual data contents of the SFTs, but only the following criteria:
filename
if injecting a signal, that the .cff file is older than the SFTs (but its contents should have been checked separately)
that the commandline stored in the (first) SFT header matches
 Parameters
cl_mfd (str) – The commandline we’d execute if not finding matching files.

run_makefakedata
()[source]¶ Generate the SFT data calling lalapps_Makefakedata_v5.
This first builds the full commandline, then calls check_cached_data_okay_to_use() to see if equivalent data files already exist, and else runs the actual generation code.

predict_fstat
(assumeSqrtSX=None)[source]¶ Predict the expected Fstatistic value for the injection parameters.
Through helper_functions.predict_fstat(), this wraps the lalapps_PredictFstat executable.
 Parameters
assumeSqrtSX (float, str or None) – If None, PSD is estimated from self.sftfilepath. Else, assume this stationary perdetector noisefloor instead. Single float or str value: use same for all IFOs. Commaseparated string: must match len(self.detectors) and the data in self.sftfilepath. Detectors will be paired to list elements following alphabetical order.

class
pyfstat.make_sfts.
BinaryModulatedWriter
(*args, **kwargs)[source]¶ Bases:
pyfstat.make_sfts.Writer
Special Writer variant for simulating a CW signal for a source in a binary system.
Most parameters are the same as for the basic Writer class, only the additional ones are documented here:
 Parameters
tp – binary orbit parameters
argp – binary orbit parameters
asini – binary orbit parameters
ecc – binary orbit parameters
period – binary orbit parameters

class
pyfstat.make_sfts.
GlitchWriter
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.SearchForSignalWithJumps
,pyfstat.make_sfts.Writer
Special Writer variant for simulating a CW signal containing a timing glitch.
Most parameters are the same as for the basic Writer class, only the additional ones are documented here:
 Parameters
dtglitch (float or None) – Time (in GPS seconds) of the glitch after tstart. To create data without a glitch, set dtglitch=None.
delta_phi (float) – Instantaneous glitch magnitudes in rad, Hz, and Hz/s respectively.
delta_F0 (float) – Instantaneous glitch magnitudes in rad, Hz, and Hz/s respectively.
delta_F1 (float) – Instantaneous glitch magnitudes in rad, Hz, and Hz/s respectively.

class
pyfstat.make_sfts.
FrequencyModulatedArtifactWriter
(*args, **kwargs)[source]¶ Bases:
pyfstat.make_sfts.Writer
Specialized Writer variant to generate SFTs containing simulated instrumental artifacts.
Contrary to the main Writer class, this calls the older lalapps_Makefakedata_v4 executable which supports the special –lineFeature option. See lalapps_Makefakedata_v4 –help for more detailed help with some of the parameters.
 Parameters
label (string) – A humanreadable label to be used in naming the output files.
outdir (str) – The directory where files are written to. Default: current working directory.
tstart (int) – Starting GPS epoch of the data set.
duration (int) – Duration (in GPS seconds) of the total data set.
F0 (float) – Frequency of the artifact.
F1 (float) – Frequency drift of the artifact.
tref (float or None) – Reference time for simulated signals. Default is None, which sets the reference time to tstart.
h0 (float) – Amplitude of the artifact.
Tsft (int) – The SFT duration in seconds. Will be ignored if noiseSFTs are given.
sqrtSX (float) – Background detector noise level.
Band (float) – Output SFTs cover [F0Band/2,F0+Band/2].
Pmod (float) – Modulation period of the artifact.
Pmod_phi (float) – Additional parameters for modulation of the artifact.
Pmod_amp (float) – Additional parameters for modulation of the artifact.
Alpha (float or None) – If not none: add an orbital modulation to the artifact corresponding to a signal from that sky position, in radians.
Delta (float or None) – If not none: add an orbital modulation to the artifact corresponding to a signal from that sky position, in radians.
detectors (str or None) – Commaseparated list of detectors to generate data for.
earth_ephem (str or None) – Paths of the two files containing positions of Earth and Sun. If None, will check standard sources as per helper_functions.get_ephemeris_files().
sun_ephem (str or None) – Paths of the two files containing positions of Earth and Sun. If None, will check standard sources as per helper_functions.get_ephemeris_files().
randSeed (int or None) – Optionally fix the random seed of Gaussian noise generation for reproducibility.

get_frequency
(t)[source]¶ Evolve the artifact frequency in time.
This includes a drift term and optionally, if Alpha and Delta are not None, a simulated orbital modulation.
 Parameters
t (float) – Time stamp to evaluate the frequency at.
 Returns
f – Frequency at time t.
 Return type
float

get_h0
(t)[source]¶ Evaluate the artifact amplitude at a given time.
NOTE: Here it’s actually implemented as a constant!
 Parameters
t (float) – Time stamp to evaluate at.
 Returns
h0 – Amplitude at time t.
 Return type
float

pre_compute_evolution
()[source]¶ Precomputes evolution parameters for the artifact.
This computes midtimes, frequencies, phases and amplitudes over the list of SFT timestamps.

class
pyfstat.make_sfts.
FrequencyAmplitudeModulatedArtifactWriter
(*args, **kwargs)[source]¶ Bases:
pyfstat.make_sfts.FrequencyModulatedArtifactWriter
A variant of FrequencyModulatedArtifactWriter with evolving amplitude.
 Parameters
label (string) – A humanreadable label to be used in naming the output files.
outdir (str) – The directory where files are written to. Default: current working directory.
tstart (int) – Starting GPS epoch of the data set.
duration (int) – Duration (in GPS seconds) of the total data set.
F0 (float) – Frequency of the artifact.
F1 (float) – Frequency drift of the artifact.
tref (float or None) – Reference time for simulated signals. Default is None, which sets the reference time to tstart.
h0 (float) – Amplitude of the artifact.
Tsft (int) – The SFT duration in seconds. Will be ignored if noiseSFTs are given.
sqrtSX (float) – Background detector noise level.
Band (float) – Output SFTs cover [F0Band/2,F0+Band/2].
Pmod (float) – Modulation period of the artifact.
Pmod_phi (float) – Additional parameters for modulation of the artifact.
Pmod_amp (float) – Additional parameters for modulation of the artifact.
Alpha (float or None) – If not none: add an orbital modulation to the artifact corresponding to a signal from that sky position, in radians.
Delta (float or None) – If not none: add an orbital modulation to the artifact corresponding to a signal from that sky position, in radians.
detectors (str or None) – Commaseparated list of detectors to generate data for.
earth_ephem (str or None) – Paths of the two files containing positions of Earth and Sun. If None, will check standard sources as per helper_functions.get_ephemeris_files().
sun_ephem (str or None) – Paths of the two files containing positions of Earth and Sun. If None, will check standard sources as per helper_functions.get_ephemeris_files().
randSeed (int or None) – Optionally fix the random seed of Gaussian noise generation for reproducibility.
pyfstat.mcmc_based_searches module¶
PyFstat search & followup classes using MCMCbased methods
The general approach is described in Ashton & Prix (PRD 97, 103020, 2018): https://arxiv.org/abs/1802.05450 and we use the ptemcee sampler described in Vousden et al. (MNRAS 455, 19191937, 2016): https://arxiv.org/abs/1501.05823 and based on ForemanMackey et al. (PASP 125, 306, 2013): https://arxiv.org/abs/1202.3665
Defining the prior¶
The MCMC based searches (i.e. pyfstat.MCMC*) require a prior specification for each model parameter, implemented via a python dictionary. This is best explained through a simple example, here is the prior for a directed search with a uniform prior on the frequency and a normal prior on the frequency derivative:
theta_prior = {'F0': {'type': 'unif',
'lower': 29.9,
'upper': 30.1},
'F1': {'type': 'norm',
'loc': 0,
'scale': 1e10},
'F2': 0,
'Alpha': 2.3,
'Delta': 1.8
}
For the sky positions Alpha
and Delta
, we give the fixed values (i.e. they are considered known by
the MCMC simulation), the same is true for F2
, the second derivative of the frequency which we fix at 0
.
Meanwhile, for the frequency F0
and first frequency derivative F1
we give a dictionary specifying their
prior distribution. This dictionary must contain three arguments: the type
(in this case either unif
or
norm
) which specifies the type of distribution, then two shape arguments. The shape parameters will depend
on the type
of distribution, but here we use lower
and upper
, required for the unif
prior while
loc
and scale
are required for the norm
prior.
Currently, two other types of prior are implemented: halfnorm
, neghalfnorm
(both of which require loc
and scale
shape parameters). Further priors can be added by modifying pyfstat.MCMCSearch._generic_lnprior
.

class
pyfstat.mcmc_based_searches.
MCMCSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.core.BaseSearchClass
MCMC search using ComputeFstat.
Evaluates the coherent Fstatistic across a parameter space region corresponding to an isolated/binarymodulated CW signal.
 Parameters
theta_prior (dict) – Dictionary of priors and fixed values for the search parameters. For each parameters (key of the dict), if it is to be held fixed the value should be the constant float, if it is be searched, the value should be a dictionary of the prior.
tref (int) – GPS seconds of the reference time, start time and end time. While tref is requirede, minStartTime and maxStartTime default to None in which case all available data is used.
minStartTime (int) – GPS seconds of the reference time, start time and end time. While tref is requirede, minStartTime and maxStartTime default to None in which case all available data is used.
maxStartTime (int) – GPS seconds of the reference time, start time and end time. While tref is requirede, minStartTime and maxStartTime default to None in which case all available data is used.
label (str) – A label and output directory (optional, default is data) to name files
outdir (str) – A label and output directory (optional, default is data) to name files
sftfilepattern (str, optional) – Pattern to match SFTs using wildcards (*?) and ranges [09]; mutiple patterns can be given separated by colons.
detectors (str, optional) – Two character reference to the detectors to use, specify None for no contraint and comma separated strings for multiple references.
nsteps (list (2,), optional) – Number of burnin and production steps to take, [nburn, nprod]. See pyfstat.MCMCSearch.setup_initialisation() for details on adding initialisation steps.
nwalkers (int, optional) – The number of walkers and temperates to use in the parallel tempered PTSampler.
ntemps (int, optional) – The number of walkers and temperates to use in the parallel tempered PTSampler.
log10beta_min (float < 0, optional) – The log_10(beta) value. If given, the set of betas passed to PTSampler are generated from np.logspace(0, log10beta_min, ntemps) (given in descending order to ptemcee).
theta_initial (dict, array, optional) – A dictionary of distribution about which to distribute the initial walkers about.
rhohatmax (float, optional) – Upper bound for the SNR scale parameter (required to normalise the Bayes factor)  this needs to be carefully set when using the evidence.
binary (bool, optional) – If true, search over binary orbital parameters.
BSGL (bool, optional) – If true, use the BSGL statistic.
SSBPrec (int, optional) – SSBPrec (SSB precision) to use when calling ComputeFstat. See core.ComputeFstat.
RngMedWindow (int, optional) – RunningMedian window size (number of bins) for ComputeFstat. See core.ComputeFstat.
minCoverFreq (float, optional) – Minimum and maximum instantaneous frequency which will be covered over the SFT time span as passed to CreateFstatInput. See core.ComputeFstat.
maxCoverFreq (float, optional) – Minimum and maximum instantaneous frequency which will be covered over the SFT time span as passed to CreateFstatInput. See core.ComputeFstat.
injectSources (dict, optional) – If given, inject these properties into the SFT files before running the search. See core.ComputeFstat.
assumeSqrtSX (float or list or str) – Don’t estimate noisefloors, but assume (stationary) perIFO sqrt{SX}. See core.ComputeFstat.
transientWindowType (str) – If ‘rect’ or ‘exp’, compute atoms so that a transient (t0,tau) map can later be computed. (‘none’ instead of None explicitly calls the transientwindow function, but with the full range, for debugging). See core.ComputeFstat. Currently only supported for nsegs=1.
tCWFstatMapVersion (str) – Choose between standard ‘lal’ implementation, ‘pycuda’ for gpu, and some others for devel/debug.

symbol_dictionary
= {'Alpha': '$\\alpha$', 'Delta': '$\\delta$', 'F0': '$f$', 'F1': '$\\dot{f}$', 'F2': '$\\ddot{f}$', 'argp': 'argp', 'asini': 'asini', 'ecc': 'ecc', 'period': 'P', 'tp': 'tp'}¶ Key, val pairs of the parameters (F0, F1, …), to LaTeX math symbols for plots

unit_dictionary
= {'Alpha': 'rad', 'Delta': 'rad', 'F0': 'Hz', 'F1': 'Hz/s', 'F2': 'Hz/s$^2$', 'argp': '', 'asini': '', 'ecc': '', 'period': 's', 'tp': 's'}¶ Key, val pairs of the parameters (i.e. F0, F1), and the units (i.e. Hz)

transform_dictionary
= {}¶ Key, val pairs of the parameters (i.e. F0, F1), where the key is itself a dictionary which can item multiplier, subtractor, or unit by which to transform by and update the units.

setup_initialisation
(nburn0, scatter_val=1e10)[source]¶ Add an initialisation step to the MCMC run
If called prior to run(), adds an intial step in which the MCMC simulation is run for nburn0 steps. After this, the MCMC simulation continues in the usual manner (i.e. for nburn and nprod steps), but the walkers are reset scattered around the maximum likelihood position of the initialisation step.
 Parameters
nburn0 (int) – Number of initialisation steps to take.
scatter_val (float) – Relative number to scatter walkers around the maximum likelihood position after the initialisation step. If the maximum likelihood point is located at p, the new walkers are randomly drawn from a multivariate gaussian distribution centered at p with standard deviation diag(scatter_val * p).

run
(proposal_scale_factor=2, save_pickle=True, export_samples=True, save_loudest=True, plot_walkers=True, walker_plot_args=None, window=50)[source]¶ Run the MCMC simulatation
 Parameters
proposal_scale_factor (float) – The proposal scale factor a > 1 used by the sampler. See Goodman & Weare (Comm App Math Comp Sci, Vol 5, No. 1, 2010): 10.2140/camcos.2010.5.65. The bigger the value, the wider the range to draw proposals from. If the acceptance fraction is too low, you can raise it by decreasing the a parameter; and if it is too high, you can reduce it by increasing the a parameter. See ForemanMackay et al. (PASP 125 306, 2013): https://arxiv.org/abs/1202.3665.
save_pickle (bool) – If true, save a pickle file of the full sampler state.
export_samples (bool) – If true, save ASCII samples file to disk. See MCMCSearch.export_samples_to_disk.
save_loudest (bool) – If true, save a CFSv2 .loudest file to disk. See MCMCSearch.generate_loudest.
plot_walkers (bool) – If true, save trace plots of the walkers.
walker_plot_args – Dictionary passed as kwargs to _plot_walkers to control the plotting. Histogram of sampled detection statistic values can be retrieved setting “plot_det_stat” to True. Parameters corresponding to an injected signal can be passed through “injection_parameters” as a dictionary containing the parameters of said signal. All parameters being searched for must be present, otherwise this option is ignored. If both “fig” and “axes” entries are set, the plot is not saved to disk directly, but (fig, axes) are returned.
window (int) – The minimum number of autocorrelation times needed to trust the result when estimating the autocorrelation time (see ptemcee.Sampler.get_autocorr_time for further details.

plot_corner
(figsize=(10, 10), add_prior=False, nstds=None, label_offset=0.4, dpi=300, rc_context={}, tglitch_ratio=False, fig_and_axes=None, save_fig=True, **kwargs)[source]¶ Generate a corner plot of the posterior
Using the corner package (https://pypi.python.org/pypi/corner/), generate estimates of the posterior from the production samples.
 Parameters
figsize (tuple (7, 7)) – Figure size in inches (passed to plt.subplots)
add_prior (bool, str) – If true, plot the prior as a red line. If ‘full’ then for uniform priors plot the full extent of the prior.
nstds (float) – The number of standard deviations to plot centered on the median. Standard deviation is computed from the samples using numpy.std.
label_offset (float) – Offset the labels from the plot: useful to prevent overlapping the tick labels with the axis labels. This option is passed to ax.[xy]axis.set_label_coords.
dpi (int) – Passed to plt.savefig.
rc_context (dict) – Dictionary of rc values to set while generating the figure (see matplotlib rc for more details).
tglitch_ratio (bool) – If true, and tglitch is a parameter, plot posteriors as the fractional time at which the glitch occurs instead of the actual time.
fig_and_axes (tuple) – (fig, axes) tuple to plot on. The axes must be of the right shape, namely (ndim, ndim)
save_fig (bool) – If true, save the figure, else return the fig, axes.
**kwargs – Passed to corner.corner. Use “truths” to plot the true parameters of a signal.
 Returns
The matplotlib figure and axes, only returned if save_fig = False.
 Return type
fig, axes

plot_chainconsumer
(save_fig=True, label_offset=0.25, dpi=300, **kwargs)[source]¶ Generate a corner plot of the posterior using the chaniconsumer package.
chainconsumer is an optional dependency of PyFstat. See https://samreay.github.io/ChainConsumer/.
Parameters are akin to the ones described in MCMCSearch.plot_corner. Only the differing parameters are explicitly described.
 Parameters
**kwargs – Passed to chainconsumer.plotter.plot. Use “truths” to plot the true parameters of a signal.

plot_prior_posterior
(normal_stds=2, injection_parameters=None, fig_and_axes=None, save_fig=True)[source]¶ Plot the prior and posterior probability distributions in the same figure
 Parameters
normal_stds (int) – Bounds of priors in terms of their standard deviation. Only used if norm, halfnorm, neghalfnorm or lognorm priors are given, otherwise ignored.
injection_parameters (dict) – Dictionary containing the parameters of a signal. All parameters being searched must be present as dictionary keys, otherwise this option is ignored.
fig_and_axes (tuple) – (fig, axes) tuple to plot on.
save_fig (bool) – If true, save the figure, else return the fig, axes.
 Returns
(fig, ax) – If save_fig evaluates to False, return figure and axes.
 Return type
(matplotlib.pyplot.figure, matplotlib.pyplot.axes)

plot_cumulative_max
(**kwargs)[source]¶ Plot the cumulative twoF for the maximum posterior estimate.
This method accepts the same arguments as pyfstat.core.ComputeFstat.plot_twoF_cumulative, except for CFS_input, which is taken from the loudest candidate; and label and outdir, which are taken from the instance of this class.
For example, one can pass signal arguments to predic_twoF_cumulative through PFS_kwargs, or set the number of segments using num_segments_(CFSPFS). The same applies for other options such as tstart, tend or savefig. Every single of these arguments will be passed to pyfstat.core.ComputeFstat.plot_twoF_cumulative as they are, using their default argument otherwise.
Keep in mind that one has to explicitely set savefig=True to output the figure!
See pyfstat.core.ComputeFstat.plot_twoF_cumulative for a comprehensive list of accepted arguments and their default values.

get_saved_data_dictionary
()[source]¶ Read the data saved in self.pickel_path and return it as a dictionary.
 Returns
d – Dictionary containing the data saved in the pickle self.pickle_path.
 Return type
dict

get_max_twoF
()[source]¶ Get the max. likelihood (loudest) sample and the compute its corresponding detection statistic.
The employed detection statistic depends on self.BSGL (i.e. 2F if self.BSGL evaluates to False, log10BSGL otherwise).
 Returns
d (dict) – Parameters of the loudest sample.
maxtwoF (float) – Detection statistic (2F or log10BSGL) corresponding to the loudest sample.

get_summary_stats
()[source]¶ Returns a dict of point estimates for all production samples.
Point estimates are computed on the MCMC samples using numpy.mean, numpy.std and numpy.quantiles with q=[0.005, 0.05, 0.25, 0.5, 0.75, 0.95, 0.995].
 Returns
d – Dictionary containing point estimates corresponding to [“mean”, “std”, “lower99”, “lower90”, “lower50”, “median”, “upper50”, “upper90”, “upper99”].
 Return type
dict

check_if_samples_are_railing
(threshold=0.01)[source]¶ Returns a boolean estimate of if the samples are railing
 Parameters
threshold (float [0, 1]) – Fraction of the uniform prior to test (at upper and lower bound)
 Returns
return_flag – IF true, the samples are railing
 Return type
bool

write_par
(method='median')[source]¶ Writes a .par of the bestfit params with an estimated std
 Parameters
method (str) – How to select the bestfit params. Available methods: “median”, “mean”, “twoFmax”.

get_p_value
(delta_F0=0, time_trials=0)[source]¶ Gets the pvalue for the maximum twoFhat value assuming Gaussian noise
 Parameters
delta_F0 (float) – Frequency variation due to a glitch.
time_trials (int, optional) – Number of trials in each glitch + 1.

compute_evidence
(make_plots=False, write_to_file=None)[source]¶ Computes the evidence/marginal likelihood for the model.
 Parameters
make_plots (bool) – Plot the results and save them to os.path.join(self.outdir, self.label + “_beta_lnl.png”)
write_to_file (str) – If given, dump evidence and uncertainty estimation to the specified path.
 Returns
log10evidence (float) – Estimation of the log10 evidence.
log10evidence_err (float) – Log10 uncertainty of the evidence estimation.

static
read_evidence_file_to_dict
(evidence_file_name='Evidences.txt')[source]¶ Read evidence file and put it into an OrderedDict
An evidence file contains paris (log10evidence, log10evidence_err) for each considered model. These pairs are prepended by the self.label variable.
 Parameters
evidence_file_name (str) – Filename to read.
 Returns
EvidenceDict – Dictionary with the contents of evidence_file_name
 Return type
dict

class
pyfstat.mcmc_based_searches.
MCMCGlitchSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.mcmc_based_searches.MCMCSearch
MCMC search using the SemiCoherentGlitchSearch
See parent MCMCSearch for a list of all additional parameters, here we list only the additional init parameters of this class.
 Parameters
nglitch (int) – The number of glitches to allow
dtglitchmin (int) – The minimum duration (in seconds) of a segment between two glitches or a glitch and the start/end of the data
theta0_idx – Index (zerobased) of which segment the theta refers to  useful if providing a tight prior on theta to allow the signal to jump too theta (and not just from)
int – Index (zerobased) of which segment the theta refers to  useful if providing a tight prior on theta to allow the signal to jump too theta (and not just from)

symbol_dictionary
= {'Alpha': '$\\alpha$', 'Delta': '$\\delta$', 'F0': '$f$', 'F1': '$\\dot{f}$', 'F2': '$\\ddot{f}$', 'delta_F0': '$\\delta f$', 'delta_F1': '$\\delta \\dot{f}$', 'tglitch': '$t_\\mathrm{glitch}$'}¶ Key, val pairs of the parameters (F0, F1, …), to LaTeX math symbols for plots

glitch_symbol_dictionary
= {'delta_F0': '$\\delta f$', 'delta_F1': '$\\delta \\dot{f}$', 'tglitch': '$t_\\mathrm{glitch}$'}¶ Key, val pairs of glitch parameters (dF0, dF1, tglitch), to LaTeX math symbols for plots. This dictionary included within self.symbol_dictionary.

unit_dictionary
= {'Alpha': 'rad', 'Delta': 'rad', 'F0': 'Hz', 'F1': 'Hz/s', 'F2': 'Hz/s$^2$', 'delta_F0': 'Hz', 'delta_F1': 'Hz/s', 'tglitch': 's'}¶ Key, val pairs of the parameters (F0, F1, …, including glitch parameters), and the units (Hz, Hz/s, …).

transform_dictionary
= {'tglitch': {'label': '$t^{g}_0$ \\n [d]', 'multiplier': 1.1574074074074073e05, 'subtractor': 'minStartTime', 'unit': 'day'}}¶ Key, val pairs of the parameters (F0, F1, …), where the key is itself a dictionary which can item multiplier, subtractor, or unit by which to transform by and update the units.

plot_cumulative_max
(savefig=False)[source]¶ Override MCMCSearch.plot_cumulative_max implementation to dea with the split at gltiches.
 Parameters
savefig (boolean) – included for consistency with core plot_twoF_cumulative() function. If true, save the figure in outdir. If false, return an axis object.

class
pyfstat.mcmc_based_searches.
MCMCSemiCoherentSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.mcmc_based_searches.MCMCSearch
MCMC search for a signal using the semicoherent ComputeFstat.
Evaluates the semicoherent Fstatistic acros a parameter space region corresponding to an isolated/binarymodulated CW signal.
See MCMCSearch for a list of additional parameters, here we list only the additional init parameters of this class.
 Parameters
nsegs (int) – The number of segments into which the input datastream will be devided. Coherence time is computed internally as (maxStartTime  minStarTime) / nsegs.

class
pyfstat.mcmc_based_searches.
MCMCFollowUpSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.mcmc_based_searches.MCMCSemiCoherentSearch
Hierarchical followup procedure
Executes MCMC runs with increasing coherence times in order to follow up a parameter space region. The main idea is to use an MCMC run to identify an interesting parameter space region to then zoomin said region using a finer “effective resolution” by increasing the coherence time. See Ashton & Prix (PRD 97, 103020, 2018): https://arxiv.org/abs/1802.05450
See MCMCSemiCoherentSearch for a list of additional parameters, here we list only the additional init parameters of this class.
 Parameters
nsegs (int) – The number of segments into which the input datastream will be devided. Coherence time is computed internally as (maxStartTime  minStarTime) / nsegs.

run
(run_setup=None, proposal_scale_factor=2, NstarMax=10, Nsegs0=None, save_pickle=True, export_samples=True, save_loudest=True, plot_walkers=True, walker_plot_args=None, log_table=True, gen_tex_table=True, window=50)[source]¶ Run the followup with the given run_setup.
See MCMCSearch.run’s docstring for a description of the remainder arguments.
 Parameters
run_setup – See MCMCFollowUpSearch.init_run_setup.
log_table – See MCMCFollowUpSearch.init_run_setup.
gen_tex_table – See MCMCFollowUpSearch.init_run_setup.
NstarMax – See pyfstat.optimal_setup_functions.get_optimal_setup.
Nsegs0 – See pyfstat.optimal_setup_functions.get_optimal_setup.

init_run_setup
(run_setup=None, NstarMax=1000, Nsegs0=None, log_table=True, gen_tex_table=True)[source]¶ Initialize the setup of the followup run computing the required quantities fro, NstarMax and Nsegs0.
 Parameters
NstarMax (int) – Required parameters to create a new followup setup. See pyfstat.optimal_setup_functions.get_optimal_setup.
Nsegs0 (int) – Required parameters to create a new followup setup. See pyfstat.optimal_setup_functions.get_optimal_setup.
run_setup (optional) – If None, a new setup will be created from NstarMax and Nsegs0. Use MCMCFollowUpSearch.read_setup_input_file to read a previous setup file.
log_table (bool) – Log followup setup using logging.info as a table.
gen_tex_table (bool) – Dump followup setup into a text file as a tex table. File is constructed as os.path.join(self.outdir, self.label + “_run_setup.tex”).
 Returns
run_setup – List containing the setup of the followup run.
 Return type
list

class
pyfstat.mcmc_based_searches.
MCMCTransientSearch
(*args, **kwargs)[source]¶ Bases:
pyfstat.mcmc_based_searches.MCMCSearch
MCMC search for a transient signal using ComputeFstat
 Parameters
theta_prior (dict) – Dictionary of priors and fixed values for the search parameters. For each parameters (key of the dict), if it is to be held fixed the value should be the constant float, if it is be searched, the value should be a dictionary of the prior.
tref (int) – GPS seconds of the reference time, start time and end time. While tref is requirede, minStartTime and maxStartTime default to None in which case all available data is used.
minStartTime (int) – GPS seconds of the reference time, start time and end time. While tref is requirede, minStartTime and maxStartTime default to None in which case all available data is used.
maxStartTime (int) – GPS seconds of the reference time, start time and end time. While tref is requirede, minStartTime and maxStartTime default to None in which case all available data is used.
label (str) – A label and output directory (optional, default is data) to name files
outdir (str) – A label and output directory (optional, default is data) to name files
sftfilepattern (str, optional) – Pattern to match SFTs using wildcards (*?) and ranges [09]; mutiple patterns can be given separated by colons.
detectors (str, optional) – Two character reference to the detectors to use, specify None for no contraint and comma separated strings for multiple references.
nsteps (list (2,), optional) – Number of burnin and production steps to take, [nburn, nprod]. See pyfstat.MCMCSearch.setup_initialisation() for details on adding initialisation steps.
nwalkers (int, optional) – The number of walkers and temperates to use in the parallel tempered PTSampler.
ntemps (int, optional) – The number of walkers and temperates to use in the parallel tempered PTSampler.
log10beta_min (float < 0, optional) – The log_10(beta) value. If given, the set of betas passed to PTSampler are generated from np.logspace(0, log10beta_min, ntemps) (given in descending order to ptemcee).
theta_initial (dict, array, optional) – A dictionary of distribution about which to distribute the initial walkers about.
rhohatmax (float, optional) – Upper bound for the SNR scale parameter (required to normalise the Bayes factor)  this needs to be carefully set when using the evidence.
binary (bool, optional) – If true, search over binary orbital parameters.
BSGL (bool, optional) – If true, use the BSGL statistic.
SSBPrec (int, optional) – SSBPrec (SSB precision) to use when calling ComputeFstat. See core.ComputeFstat.
RngMedWindow (int, optional) – RunningMedian window size (number of bins) for ComputeFstat. See core.ComputeFstat.
minCoverFreq (float, optional) – Minimum and maximum instantaneous frequency which will be covered over the SFT time span as passed to CreateFstatInput. See core.ComputeFstat.
maxCoverFreq (float, optional) – Minimum and maximum instantaneous frequency which will be covered over the SFT time span as passed to CreateFstatInput. See core.ComputeFstat.
injectSources (dict, optional) – If given, inject these properties into the SFT files before running the search. See core.ComputeFstat.
assumeSqrtSX (float or list or str) – Don’t estimate noisefloors, but assume (stationary) perIFO sqrt{SX}. See core.ComputeFstat.
transientWindowType (str) – If ‘rect’ or ‘exp’, compute atoms so that a transient (t0,tau) map can later be computed. (‘none’ instead of None explicitly calls the transientwindow function, but with the full range, for debugging). See core.ComputeFstat. Currently only supported for nsegs=1.
tCWFstatMapVersion (str) – Choose between standard ‘lal’ implementation, ‘pycuda’ for gpu, and some others for devel/debug.

symbol_dictionary
= {'Alpha': '$\\alpha$', 'Delta': '$\\delta$', 'F0': '$f$', 'F1': '$\\dot{f}$', 'F2': '$\\ddot{f}$', 'transient_duration': '$\\Delta T$', 'transient_tstart': '$t_\\mathrm{start}$'}¶ Key, val pairs of the parameters (F0, F1, …), to LaTeX math symbols for plots

unit_dictionary
= {'Alpha': 'rad', 'Delta': 'rad', 'F0': 'Hz', 'F1': 'Hz/s', 'F2': 'Hz/s$^2$', 'transient_duration': 's', 'transient_tstart': 's'}¶ Key, val pairs of the parameters (F0, F1, …, including glitch parameters), and the units (Hz, Hz/s, …).

transform_dictionary
= {'transient_duration': {'multiplier': 1.1574074074074073e05, 'symbol': 'Transient duration', 'unit': 'day'}, 'transient_tstart': {'label': 'Transient starttime \n days after minStartTime', 'multiplier': 1.1574074074074073e05, 'subtractor': 'minStartTime', 'unit': 'day'}}¶ Key, val pairs of the parameters (F0, F1, …), where the key is itself a dictionary which can item multiplier, subtractor, or unit by which to transform by and update the units.
pyfstat.optimal_setup_functions module¶
Provides functions to aid in calculating the optimal setup for zoom follow up

pyfstat.optimal_setup_functions.
get_optimal_setup
(NstarMax, Nsegs0, tref, minStartTime, maxStartTime, prior, detector_names)[source]¶ Using an optimisation step, calculate the optimal setup ladder
The details of the methods are described in Sec Va of arXiv:1802.05450. Here we provide implementation details. All equation numbers refer to arXiv:1802.05450.
 Parameters
NstarMax (float) – The ratio of the size at the old coherence time to the new coherence time for each step, see Eq. (31). Larger values allow a more rapid “zoom” of the search space at the cost of convergence. Smaller values are more conservative at the cost of additional computing time. The exact choice should be optimized for the problem in hand, but values of 1001000 are typically okay.
Nsegs0 (int) – The number of segments for the initial step of the ladder
tref (int) – GPS times of the reference, start, and end time.
minStartTime (int) – GPS times of the reference, start, and end time.
maxStartTime (int) – GPS times of the reference, start, and end time.
prior (dict) – Prior dictionary, each item must either be a fixed scalar value, or a uniform prior.
detector_names (list or str) – Names of the detectors to use
 Returns
nsegs, Nstar – Ladder of segment numbers and the corresponding Nstar
 Return type
list

pyfstat.optimal_setup_functions.
get_Nstar_estimate
(nsegs, tref, minStartTime, maxStartTime, prior, detector_names)[source]¶ Returns N* estimated from the supersky metric
 Parameters
nsegs (int) – Number of semicoherent segments
tref (int) – Reference time in GPS seconds
minStartTime (int) – Minimum and maximum SFT timestamps
maxStartTime (int) – Minimum and maximum SFT timestamps
prior (dict) – The prior dictionary
detector_names (array) – Array of detectors to average over
 Returns
Nstar – The estimated approximate number of templates to cover the prior parameter space at a mismatch of unity, assuming the normalised thickness is unity.
 Return type
int
pyfstat.tcw_fstat_map_funcs module¶
Additional helper functions dealing with transientCW F(t0,tau) maps.
See Prix, Giampanis & Messenger (PRD 84, 023007, 2011): https://arxiv.org/abs/1104.1704 for the algorithm in general and Keitel & Ashton (CQG 35, 205003, 2018): https://arxiv.org/abs/1805.05652 for a detailed discussion of the GPU implementation.

class
pyfstat.tcw_fstat_map_funcs.
pyTransientFstatMap
(N_t0Range=None, N_tauRange=None, transientFstatMap_t=None)[source]¶ Bases:
object
Simplified object class for a F(t0,tau) Fstat map.
This is based on LALSuite’s transientFstatMap_t type, replacing the gsl matrix with a numpy array.
Here, t0 is a transient start time, tau is a transient duration parameter, and F(t0,tau) is the Fstatistic (not 2F)! evaluated for a signal with those parameters (and an implicit window function, which is not stored inside this object).
The ‘map’ covers a range of different (t0,tau) pairs.

F_mn
¶ 2D array of F values (not 2F!), with m an index over starttimes t0, and n an index over duration parameters tau, in steps of dt0 in [t0, t0+t0Band], and dtau in [tau, tau+tauBand].
 Type
np.ndarray

maxF
¶ Maximum of F (not 2F!) over the array.
 Type
float

t0_ML
¶ Maximum likelihood estimate of the transient start time t0.
 Type
float

tau_ML
¶ Maximum likelihood estimate of the transient duration tau.
 Type
float
The class can be initialized with the following:
 Parameters
N_t0Range (int) – Number of t0 values covered.
N_tauRange (int) – Number of tau values covered.
transientFstatMap_t (lalpulsar.transientFstatMap_t) – preallocated matrix from lalpulsar.

get_maxF_idx
()[source]¶ Gets the 2Dunravelled index pair of the maximum of the F_mn map
 Returns
idx – The m,n indices of the map entry with maximal F value.
 Return type
tuple

write_F_mn_to_file
(tCWfile, windowRange, header=[])[source]¶ Format a 2D transientFstat matrix over (t0,tau) and write as a text file.
Apart from the optional extra header lines, the format is consistent with lalpulsar.write_transientFstatMap_to_fp().
 Parameters
tCWfile (str) – Name of the file to write to.
windowRange (lalpulsar.transientWindowRange_t) – A lalpulsar structure containing the transient parameters.
header (list) – A list of additional header lines to print at the start of the file.


pyfstat.tcw_fstat_map_funcs.
fstatmap_versions
= {'lal': <function <lambda>>, 'pycuda': <function <lambda>>}¶ Dictionary of the actual callable transient Fstat map functions this module supports.
Actual runtime availability depends on the corresponding external modules being available.

pyfstat.tcw_fstat_map_funcs.
init_transient_fstat_map_features
(wantCuda=False, cudaDeviceName=None)[source]¶ Initialization of available modules (or ‘features’) for computing transient Fstat maps.
Currently, two implementations are supported and checked for through the _optional_import() method:
lal: requires both lal and lalpulsar packages to be importable.
2. pycuda: requires the pycuda package to be importable along with its modules driver, gpuarray, tools and compiler.
 Parameters
wantCuda (bool) – Only if this is True and it was possible to import pycuda, a CUDA device context is created and returned.
cudaDeviceName (str or None) – Request a CUDA device with this name. Partial matches are allowed.
 Returns
features (dict) – A dictionary of available method names, to match fstatmap_versions. Each key’s value is set to True only if all required modules are importable on this system.
gpu_context (pycuda.driver.Context or None) – A CUDA device context object, if assigned.

pyfstat.tcw_fstat_map_funcs.
call_compute_transient_fstat_map
(version, features, multiFstatAtoms=None, windowRange=None)[source]¶ Call a version of the ComputeTransientFstatMap function.
This checks if the requested version is available, and if so, executes the computation of a transient Fstatistic map over the windowRange.
 Parameters
version (str) – Name of the method to call (currently supported: ‘lal’ or ‘pycuda’).
features (dict) – Dictionary of available features, as obtained from init_transient_fstat_map_features().
multiFstatAtoms (lalpulsar.MultiFstatAtomVector or None) – The timedependent Fstat atoms previously computed by ComputeFstat.
windowRange (lalpulsar.transientWindowRange_t or None) – The structure defining the transient parameters.
 Returns
FstatMap (pyTransientFstatMap or lalpulsar.transientFstatMap_t) – The output of the called function, including the evaluated transient Fstatistic map over the windowRange.
timingFstatMap (float) – Execution time of the called function.

pyfstat.tcw_fstat_map_funcs.
lalpulsar_compute_transient_fstat_map
(multiFstatAtoms, windowRange)[source]¶ Wrapper for the standard lalpulsar function for computing a transient Fstatistic map.
See https://lscsoft.docs.ligo.org/lalsuite/lalpulsar/_transient_c_w__utils_8h.html for the wrapped function.
 Parameters
multiFstatAtoms (lalpulsar.MultiFstatAtomVector) – The timedependent Fstat atoms previously computed by ComputeFstat.
windowRange (lalpulsar.transientWindowRange_t) – The structure defining the transient parameters.
 Returns
FstatMap – The computed results, see the class definition for details.
 Return type

pyfstat.tcw_fstat_map_funcs.
reshape_FstatAtomsVector
(atomsVector)[source]¶ Make a dictionary of ndarrays out of an Fstat atoms ‘vector’ structure.
 Parameters
atomsVector (lalpulsar.FstatAtomVector) – The atoms in a ‘vector’like structure: iterating over timestamps as the higher hierarchical level, with a set of ‘atoms’ quantities defined at each timestamp.
 Returns
atomsDict – A dictionary with an entry for each quantity, which then is a 1D ndarray over timestamps for that one quantity.
 Return type
dict

pyfstat.tcw_fstat_map_funcs.
pycuda_compute_transient_fstat_map
(multiFstatAtoms, windowRange)[source]¶ GPU version of computing a transient Fstatistic map.
This is based on XLALComputeTransientFstatMap from LALSuite, (C) 2009 Reinhard Prix, licensed under GPL.
The ‘map’ consists of Fstatistics evaluated over a range of different (t0,tau) pairs (transient starttimes and duration parameters).
This is a highlevel wrapper function; the actual CUDA computations are performed in one of the functions pycuda_compute_transient_fstat_map_rect() or pycuda_compute_transient_fstat_map_exp(), depending on the window functon defined in windowRange.
 Parameters
multiFstatAtoms (lalpulsar.MultiFstatAtomVector) – The timedependent Fstat atoms previously computed by ComputeFstat.
windowRange (lalpulsar.transientWindowRange_t) – The structure defining the transient parameters.
 Returns
FstatMap – The computed results, see the class definition for details.
 Return type

pyfstat.tcw_fstat_map_funcs.
pycuda_compute_transient_fstat_map_rect
(atomsInputMatrix, windowRange, tCWparams)[source]¶ GPU computation of the transient Fstat map for rectangular windows.
As discussed in Keitel & Ashton (CQG 35, 205003, 2018): https://arxiv.org/abs/1805.05652 this version only does GPU parallization for the outer loop, keeping the partial sums of the inner loop local to each individual kernel using the ‘memory trick’.
 Parameters
atomsInputMatrix (np.ndarray) – A 2D array of stacked named columns containing the Fstat atoms.
windowRange (lalpulsar.transientWindowRange_t) – The structure defining the transient parameters.
tCWparams (dict) – A dictionary of miscellaneous parameters.
 Returns
F_mn – A 2D array of the computed transient Fstat map over the [t0,tau] range.
 Return type
np.ndarray

pyfstat.tcw_fstat_map_funcs.
pycuda_compute_transient_fstat_map_exp
(atomsInputMatrix, windowRange, tCWparams)[source]¶ GPU computation of the transient Fstat map for exponential windows.
As discussed in Keitel & Ashton (CQG 35, 205003, 2018): https://arxiv.org/abs/1805.05652 this version does full GPU parallization of both the inner and outer loop.
 Parameters
atomsInputMatrix (np.ndarray) – A 2D array of stacked named columns containing the Fstat atoms.
windowRange (lalpulsar.transientWindowRange_t) – The structure defining the transient parameters.
tCWparams (dict) – A dictionary of miscellaneous parameters.
 Returns
F_mn – A 2D array of the computed transient Fstat map over the [t0,tau] range.
 Return type
np.ndarray