Detailed API reference#

Fisher matrix computation#

GWFish.modules.fishermatrix.compute_network_errors(network: GWFish.modules.detection.Network, parameter_values: pandas.DataFrame, fisher_parameters: Optional[list[str]] = None, waveform_model: str = wf.DEFAULT_WAVEFORM_MODEL, waveform_class=wf.LALFD_Waveform, use_duty_cycle: bool = False, redefine_tf_vectors: bool = False, save_matrices: bool = False, save_matrices_path: Union[pathlib.Path, str] = Path('.'), matrix_naming_postfix: str = '') → tuple[numpy.ndarray, numpy.ndarray, Optional[numpy.ndarray]][source]

Compute Fisher matrix errors for a network whose SNR and Fisher matrices have already been calculated.

Will only return output for the n_above_thr signals for which the network SNR is above network.detection_SNR[1].

Parameters

  • network – detector network to use

  • parameter_values – dataframe with parameters for one or more signals

  • fisher_parameters – list of parameters to use for the Fisher matrix analysis - if None (default), all waveform parameters are used

  • waveform_model – waveform model to use - refer to choosing an approximant

  • waveform_model – waveform class to use - refer to choosing an approximant

  • redefine_tf_vectors – Whether to redefine the time-frequency vectors in order to correctly model signals with small frequency evolution. Defaults to False.

  • use_duty_cycle – Whether to use the detector duty cycle (i.e. stochastically set the SNR to zero some of the time); defaults to False

  • save_matrices – Whether to save the Fisher matrices and their inverses to disk; defaults to False

  • save_matrices_path – Path (expressed with Pathlib or through a string) where to save the Fisher matrices and their inverses to disk; defaults to Path('.') (the current folder)

  • matrix_naming_postfix – string to be appended to the names of the Fisher matrices and their inverses: they will look like fisher_matrices_postfix.npy and inv_fisher_matrices_postfix.npy

Returns

  • detected: array with shape (n_above_thr,) - array of indices for the detected signals.

  • network_snr: array with shape (n_signals,) - Network SNR for all signals.

  • parameter_errors: array with shape (n_signals, n_parameters) - One-sigma Fisher errors for the parameters.

  • sky_localization: array with shape (n_signals,) or None - One-sigma sky localization area in steradians, returned if the signals have both right ascension and declination, or None otherwise.

GWFish.modules.fishermatrix.compute_detector_fisher(detector: GWFish.modules.detection.Detector, signal_parameter_values: Union[pandas.DataFrame, dict[str, float]], fisher_parameters: Optional[list[str]] = None, waveform_model: str = wf.DEFAULT_WAVEFORM_MODEL, waveform_class: type(wf.Waveform) = wf.LALFD_Waveform, use_duty_cycle: bool = False, redefine_tf_vectors: bool = False) → tuple[numpy.ndarray, float][source]

Compute the Fisher matrix and SNR for a single detector.

Example usage:

>>> from GWFish.modules.detection import Detector
>>> detector = Detector('ET')
>>> params = {
...    'mass_1': 10.,
...    'mass_2': 10.,
...    'luminosity_distance': 1000.,
...    'theta_jn': 0.,
...    'ra': 0.,
...    'dec': 0.,
...    'phase': 0.,
...    'psi': 0.,
...    'geocent_time': 1e9,
...    }
>>> fisher, detector_SNR_square = compute_detector_fisher(detector, params)
>>> print(fisher.shape)
(9, 9)
>>> print(f'{np.sqrt(detector_SNR_square):.0f}')
260
Parameters

  • detector – The detector to compute the Fisher matrix for

  • signal_parameter_values – The parameter values for the signal. They can be a dictionary of parameter names and values, or a single-row pandas DataFrame with the parameter names as columns.

  • fisher_parameters – The parameters to compute the Fisher matrix for. If None, all parameters are used.

  • waveform_model – The waveform model to use (see choosing an approximant);

  • waveform_class – The waveform class to use (see choosing an approximant);

  • use_duty_cycle – Whether to use the detector duty cycle (i.e. stochastically set the SNR to zero some of the time); defaults to False

  • redefine_tf_vectors – Whether to redefine the time-frequency vectors in order to correctly model signals with small frequency evolution. Defaults to False.

Returns

The Fisher matrix, and the square of the detector SNR.

Utility functions#

GWFish.modules.fishermatrix.sky_localization_percentile_factor(percentile: float = 90.0) → float[source]

Conversion factor \(C_{X\%}\) to go from the sky localization area provided by GWFish (one sigma, in steradians) to the X% contour, in degrees squared.

\[ \Delta \Omega_{X\%} = C_{X\%} \Delta \Omega_{\text{GWFish output}} \]
Parameters

percentile – Percentile of the sky localization area.

Returns

Conversion factor \(C_{X\%}\)

Horizon computation#

GWFish.modules.horizon.horizon(params: dict, detector: Union[GWFish.modules.detection.Detector, GWFish.modules.detection.Network], target_SNR: float = 9.0, waveform_model: str = DEFAULT_WAVEFORM_MODEL, waveform_class: type(Waveform) = LALFD_Waveform, cosmology_model: astropy.cosmology.Cosmology = Planck18, source_frame_masses: bool = True, redefine_tf_vectors: bool = False)[source]

Given the parameters for a GW signal and a detector, this function computes the luminosity distance and corresponding redshift (as connected by a given cosmology) which the signal would need to be at in order to have a given SNR - by default, 9.

Parameters

  • params – fixed parameters for the signal (should not include redshift or luminosity distance)

  • detector – Detector or Network object to compute the horizon for

  • target_SNR – the function will compute the distance such the signal will have this SNR in the given detector

  • waveform_model – waveform model to use - refer to choosing an approximant

  • waveform_model – waveform class to use - refer to choosing an approximant

  • cosmology_model – (astropy) cosmology model to use to relate the redshift to the luminosity distance

  • source_frame_masses – whether to assume the given mass is in the source frame, therefore it needs to be redshifted in order to compute the detected one. Default is True.

  • redefine_tf_vectors – whether to redefine the time and frequency vectors (useful when computing horizons for sources with very small frequency variation). Default is False.

Returns

  • luminosity_distance in Mpc,

  • corresponding redshift