Checking, manipulating and inverting the Fisher matrix¶

gwfast provides various functions to manipulate the FIM and deal with its inversion, to compute the covariance matrix. We here review and list the available tools.

To have more reliable estimations, most of the functions use the mpmath library for precision arithmetics.

Note

All the following functions assume that the FIM is a 3-D array of matrices with shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\) where \(N_{\rm parameters}\) is the number of parameters used in the analysis and \(N_{\rm events}\) the number of simulated events.

Sanity checks on the Fisher matrix¶

gwfast features a function to compute the eigenvalues and eigenvectors of FIMs, checking if some are negative, as well as their condition number, i.e. the ratio of the largest to smallest eigenvalue. If the condition number is larger than the inverse machine precision (\(\varepsilon^{-1} = 10^{15}\) in our default case), the covariance matrix will likely be unreliable for some elements.

gwfast.fisherTools.CheckFisher(FisherM, condNumbMax=1000000000000000.0, use_mpmath=True, verbose=False)[source]¶

Perform some sanity checks on the Fisher matrix, in particular:

compute the eigenvalues and eigenvectors;

compute the condition number (ratio of the largest to smallest eigenvalue) and check this is not large;

Parameters

FisherM (array) – Array containing the Fisher matrix(ces) to check, of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
condNumbMax (float) – Maximum allowed condition number, depending on the machine precision.
use_mpmath (bool, optional) –
Boolean specifying if the checks have to be performed using the mpmath library.
verbose (bool, optional) – Boolean specifying if the code has to print additional details during execution.

Returns

Eigenvalues, eigenvectors and condition number(s) of the input Fisher matrix(ces).

Return type

tuple(array, array, array)

Computing the covariance matrix¶

One of the most delicate point of the Fisher matrix analysis is dealing with its inversion, to compute the covariance matrix. The inversion can be unreliable if the FIM is ill-conditioned, with some care in handling the inversion procedure, a better stability can be achieved.

In particular, in gwfast each row and column is normalized to the square root of the diagonal of the FIM before inversion, so that the resulting matrix has adimensional entries with ones on the diagonal and the remaining elements in the interval \([−1,\, 1]\), as in arXiv:2205.02499. The inverse transformation is then applied after the inversion to yield the inverse of the original matrix. This transformation is not applied in case the matrix has a zero element on the diagonal.

The mpmath library for precision arithmetics is employed, and various possible techniques are availeble to find the inverse, namely:

'inv' : the inverse as computed by mpmath library;

'cho' : the inverse is computed by means of the Cholesky decomposition, i.e. the (Hermitian, positive–definite) FIM is expressed as a product of a lower triangular matrix and its conjugate transpose, and the latter is inverted;

Note

In some case, the FIM may be not positive–definite due to the presence of very small eigenvalues that can assume negative values due to numerical fluctuations, in which case the Cholesky decomposition cannot be found.

'svd' : the singular value decomposition, SVD, of the FIM is used to invert the matrix. In this case, there is the additional option of truncating the smallest singular values to the minimum allowed numerical precision, that can help regularizing badly conditioned matrices. In this case, for each singular value \(s_i\), if the ratio of its absolute value to the absolute value of the largest singular value, \({\rm max}(s_i)\), is smaller than a threshold \(\lambda\), the singular value \(s_i\) is replaced with \(\lambda \times {\rm max}(s_i)\).

'svd_reg' : the singular value decomposition, SVD, of the FIM is used to invert the matrix, and eigenvalues smaller than a specified threshold are not included in the inversion. This ensures that the error on badly constrained parameters is not propagated to the other ones, see arXiv:2205.02499. However, it might result in underestimating the uncertainty for the parameters whose eigenvalues are excluded, and the effect should be carefully checked.

'lu' : the nverse is computed by means of the Lower-Upper, LU, decomposition, i.e. the factorization of the FIM into the product of one lower triangular matrix and one upper triangular matrix. This can be useful since, as for the Cholesky decomposition, the inversion of a triangular matrix is easier than the one of a full matrix and, differently from the Cholesky decomposition, the original matrix does not have to be Hermitian and positive–definite, which can make this method more stable against numerical noise for badly–conditioned matrices.

A useful quantity that can be used to check the reliability of the inversion is the inversion error, defined as

\[\epsilon = {\rm max}_{ij} |(\Gamma \cdot \Gamma^{-1} - \mathbb{1} )_{ij}|\]

The covariance matrix and the inversion error can be computed using the function

gwfast.fisherTools.CovMatr(FisherMatrix, invMethodIn='cho', condNumbMax=1e+50, truncate=False, svals_thresh=1e-15, verbose=False, alt_method='svd')[source]¶

Invert the Fisher matrix(ces), obtaining the covariance matrix(ces).

Parameters

FisherMatrix (array) – Array containing the Fisher matrix(ces) to invert, of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
invMethodIn (str) – Inversion method to use. To be chosen among 'inv', 'cho', 'svd', 'svd_reg' and 'lu'.
condNumbMax (float) – Maximum allowed condition number, above which the inverse matrix is not computed. The default value is 1e50, so the code will try to invert every matrix, irrespectively of the conditioning.
truncate (bool, optional) – Boolean specifying if, when using the 'svd' method, the function has to truncate the smallest singular values to the minimum allowed numerical precision.
svals_thresh (float) – Threshold value to truncate the singular values when using the 'svd' method, or to exclude the singular values from the inversion when using the 'svd_reg' method.
verbose (bool, optional) – Boolean specifying if the code has to print additional details during execution.
alt_method (str) – Inversion method to use in case the inverison with invMethodIn fails. To be chosen among 'inv', 'cho', 'svd', 'svd_reg' and 'lu'. It has to be different from invMethodIn.

Returns

Covariance matrix(ces) (3-D array) and inversion error(s) (1-D array). The covariance matrix(ces) have the same shape of FisherMatrix, i.e. \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).

Return type

tuple(array, array)

It is also possible to compute the inversion error alone, if having already computed the Fisher and covariance matrices, using the function

gwfast.fisherTools.compute_inversion_error(Fisher, Cov)[source]¶

Compute the inversion error given the Fisher and covariance matrices.

Parameters

Fisher (array) – Array containing the Fisher matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
Cov (array) – Array containing the covariance matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).

Returns

Inversion error for the given matrices.

Return type

1-D array

Checks on the covariance matrix¶

gwfast features functions to check the stability of the FIM inversion.

To add a random perturbations to the FIM to a specified decimal point, and check if the inversion remains stable, it is possible to use

gwfast.fisherTools.perturb_Fisher(totF, eps=1e-10, **kwargs)[source]¶

Add random small perturbations to the FIM to a specified decimal and prints the relative errors, to check if the inversion remains stable.

Parameters

totF (array) – Array containing the Fisher matrix(ces) to check, of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
eps (float) – Decimal at which to add the random perturbation.
kwargs – Optional arguments to be passed to gwfast.fisherTools.CovMatr, such as invMethodIn.

To compute the inversion error, print the difference between \(\Gamma \cdot \Gamma^{-1}\) and the identity on the diagonal, and the off–diagonal elements of \(\Gamma \cdot \Gamma^{-1}\) higher than a given threshold, it is possible to use

gwfast.fisherTools.check_covariance(FisherM, Cov, tol=1e-10)[source]¶

Compute the inversion error, print the difference between the product of Fisher and covariance matrices and the identity matrix on the diagonal, and print the off–diagonal elements of the product of Fisher and covariance matrices higher than a threshold.

Parameters

FisherM (array) – Array containing the Fisher matrix(ces) to check, of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
Cov (array) – Array containing the covariance matrix(ces) to check, of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
tol (float) – Threshold above which to print the off–diagonal elements of the product of Fisher and covariance matrices.

Returns

Product of Fisher and covariance matrices, of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).

Return type

3-D array

Adding priors to the Fisher matrix¶

To add a Gaussian prior on some parameters, one can add to the FIM a prior matrix \(P_{ij}\) corresponding to the inverse covariance of the prior. gwfast supports the addition of a diagonal prior matrix, using the function

gwfast.fisherTools.addPrior(Matr, vals, ParNums, ParAdd)[source]¶

Add a Gaussian priors to the Fisher matrix on one or multiple parameters.

Parameters

Matr (array) – Array containing the Fisher matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
vals (list(float)) – List of values to be added on the diagonal of the Fisher matrix.
ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.
ParAdd (list(str)) – List of the names of parameters on which the prior should be added.

Returns

Fisher matrix with Gaussian priors added at the chosen positions, of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).

Return type

3-D array

Fix parameters in the Fisher matrix¶

To fix some parameters to their fiducial values, one has to remove from the FIM the corresponding rows and columns before inverting it. This can done using the function

gwfast.fisherTools.fixParams(MatrIn, ParNums_inp, ParMarg)[source]¶

Fix one or multiple parameters to their fiducial values in the Fisher matrix.

Parameters

MatrIn (array) – Array containing the Fisher matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
ParNums_inp (dict(int)) – Dictionary specifying the position of each parameter in the input Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.
ParMarg (list(str)) – List of the names of parameters to fix.

Returns

Fisher matrix with parameters fixed, of shape \((\tilde{N}_{\rm parameters}\), \(\tilde{N}_{\rm parameters}\), \(N_{\rm events})\), and dictionary specifying the position of each parameter in the new Fisher matrix. \(\tilde{N}_{\rm parameters}\) is the original \(N_{\rm parameters}\) minus the number of parameters that have been fixed.

Return type

tuple(array, dict(int))

Compute the localisation region¶

From the covariance matrix it is possible to compute the localisation region of the event. This is obtained as (see arXiv:gr-qc/0310125 and arXiv:1003.2504)

\[\Delta\Omega_{{\rm X}\%} = -2\pi |{\rm sin}\theta|\sqrt{\left(\Gamma^{-1}\right)_{\theta\theta}\, \left(\Gamma^{-1}\right)_{\phi\phi} - \left(\Gamma^{-1}\right)_{\theta\phi}^2}\ {\rm ln}{\left(1 - \frac{{\rm X}}{100}\right)}\]

and can be computed using the function

gwfast.fisherTools.compute_localization_region(Cov, parNum, thFid, perc_level=90, units='SqDeg')[source]¶

Compute the localisation region of one or multiple events.

Parameters

Cov (array) – Array containing the covariance matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters}\), \(N_{\rm events})\).
parNum (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.
thFid (array) – Array containing the \(\theta\) sky position angle(s) of the event(s), in \(\rm rad\).
perc_level (float) – The percent level at which to compute the localisation region, from 0 to 100.
units (str) – The units to use for the output, to choose among square degrees, 'SqDeg', or steradians, 'Sterad'.

Returns

Localisation region(s) of the event(s).

Return type

1-D array

Changing parameters in Fisher and covariance matrix¶

gwfast features functions to perform some parameters transformations of the Fisher and covariance matrices.

Transformation from \({\rm log}(d_L)\) to \(d_L\)¶

To transform a Fisher matrix from \({\rm log}(d_L)\) to \(d_L\) it is possible to use the function
gwfast.fisherTools.log_dL_to_dL_derivative_fish(or_matrix, ParNums, evParams)[source]¶
Change variables in the Fisher matrix from \({\rm log}(d_L)\) to \(d_L\).
Parameters
or_matrix (array) – Array containing the Fisher matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.

evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.
Returns

Fisher matrix in \(d_L\), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

Return type

2-D array
To transform a covariance matrix from \({\rm log}(d_L)\) to \(d_L\) it is possible to use the function
gwfast.fisherTools.log_dL_to_dL_derivative_cov(or_matrix, ParNums, evParams)[source]¶
Change variables in the covariance matrix from \({\rm log}(d_L)\) to \(d_L\).
Parameters
or_matrix (array) – Array containing the covariance matrix, of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.

evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.
Returns

Covariance matrix in \(d_L\), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

Return type

2-D array

Transformation from \((m_1,\, m_2)\) to \(({\cal M}_c,\, \eta)\)¶

To transform a Fisher matrix from \(m_1\) and \(m_2\) to \({\cal M}_c\) and \(\eta\) it is possible to use the function
gwfast.fisherTools.m1m2_to_Mceta_fish(or_matrix, ParNums, evParams)[source]¶
Change variables in the Fisher matrix from \(m_1\) and \(m_2\) to \({\cal M}_c\) and \(\eta\).
Parameters
or_matrix (array) – Array containing the Fisher matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.

evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.
Returns

Fisher matrix in \({\cal M}_c\) and \(\eta\), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

Return type

2-D array
To transform a Fisher matrix from \(m_1\) and \(m_2\) to \({\cal M}_c\) and \(\eta\) it is possible to use the function
gwfast.fisherTools.m1m2_to_Mceta_cov(or_matrix, ParNums, evParams)[source]¶
Change variables in the covariance matrix from \(m_1\) and \(m_2\) to \({\cal M}_c\) and \(\eta\).
Parameters
or_matrix (array) – Array containing the covariance matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.

evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.
Returns

Covariance matrix in \({\cal M}_c\) and \(\eta\), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

Return type

2-D array

Transformation from \(({\cal M}_c,\, \eta)\) to \((m_1,\, m_2)\)¶

To transform a Fisher matrix from \({\cal M}_c\) and \(\eta\) to \(m_1\) and \(m_2\) it is possible to use the function
gwfast.fisherTools.Mceta_to_m1m2_fish(or_matrix, ParNums, evParams)[source]¶
Change variables in the Fisher matrix from \({\cal M}_c\) and \(\eta\) to \(m_1\) and \(m_2\).
Parameters
or_matrix (array) – Array containing the Fisher matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.

evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.
Returns

Fisher matrix in \(m_1\) and \(m_2\), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

Return type

2-D array
To transform a Fisher matrix from \({\cal M}_c\) and \(\eta\) to \(m_1\) and \(m_2\) it is possible to use the function
gwfast.fisherTools.Mceta_to_m1m2_cov(or_matrix, ParNums, evParams)[source]¶
Change variables in the covariance matrix from \({\cal M}_c\) and \(\eta\) to \(m_1\) and \(m_2\).
Parameters
or_matrix (array) – Array containing the covariance matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.

evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.
Returns

Covariance matrix in \(m_1\) and \(m_2\), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

Return type

2-D array

Transformation from \((\chi_s,\, \chi_a)\) to \((\chi_{1,z},\, \chi_{2,z})\)¶

To transform a Fisher matrix from \(\chi_s\) and \(\chi_a\) to \(\chi_{1,z}\) and \(\chi_{2,z}\) it is possible to use the function

gwfast.fisherTools.chiSchiA_to_chi1chi2_fish(or_matrix, ParNums, evParams)[source]¶

Change variables in the Fisher matrix from \(\chi_s\) and \(\chi_a\) to \(\chi_{1,z}\) and \(\chi_{2,z}\).

Parameters

or_matrix (array) – Array containing the Fisher matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).
ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.
evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.

Returns

Fisher matrix in \(\chi_{1,z}\) and \(\chi_{2,z}\), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

Return type

2-D array

Transformation from \((\chi_{1,z},\, \chi_{2,z})\) to \((\chi_{\rm eff},\, \Delta\chi)\)¶

To transform a Fisher matrix from \(\chi_{1,z}\) and \(\chi_{2,z}\) to \(\chi_{\rm eff}\) and \(\Delta\chi\) it is possible to use the function

gwfast.fisherTools.chi1chi2_to_chieffDeltachi_fish(or_matrix, ParNums, evParams)[source]¶

Change variables in the Fisher matrix from \(\chi_{1,z}\) and \(\chi_{2,z}\) to \(\chi_{\rm eff}\) and \(\Delta\chi\).

Parameters

or_matrix (array) – Array containing the Fisher matrix(ces), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).
ParNums (dict(int)) – Dictionary specifying the position of each parameter in the Fisher matrix, as gwfast.waveforms.WaveFormModel.ParNums.
evParams (dict(array, array, ...)) – Dictionary containing the parameters of the event(s), as in events.

Returns

Fisher matrix in \(\chi_{\rm eff}\) and \(\Delta\chi\), of shape \((N_{\rm parameters}\), \(N_{\rm parameters})\).

Return type

2-D array

Note

\(\chi_{\rm eff}\) and \(\Delta\chi\) are defined as

\begin{eqnarray} \chi_{\rm eff} & \equiv & \frac{m_1 \chi_{1,z} + m_2 \chi_{2,z}}{m_1 + m_2} \\ \Delta\chi & \equiv & \chi_{1,z} - \chi_{2,z} = 2 \chi_a \end{eqnarray}