GRAVI Pipeline Reference Manual 1.9.2
Loading...
Searching...
No Matches
Data Structures | Typedefs | Functions
gravi_pca.c File Reference
#include <gsl/gsl_linalg.h>
#include <gsl/gsl_matrix.h>
#include <gsl/gsl_bspline.h>
#include <gsl/gsl_sort_vector.h>
#include <gsl/gsl_multifit.h>
#include <gsl/gsl_multimin.h>
#include <gsl/gsl_statistics.h>
#include "gravi_pca.h"
#include "gravi_utils.h"

Go to the source code of this file.

Data Structures

struct  _gravi_pca_result_
 Type to hold results of a PCA decomposition. More...
 
struct  _gravi_pca_model_
 Type to hold average (median) components obtained from a set of PCA decompositions and/or best-fit model to average components. More...
 
struct  _gravi_pca_model_params_
 Type to hold parameters for fitting PCA components to data. More...
 

Typedefs

typedef struct _gravi_pca_model_params_ gravi_pca_model_params
 Type to hold parameters for fitting PCA components to data.
 

Functions

static double _gsl_vector_sum (const gsl_vector *a)
 
void gravi_pca_result_delete (gravi_pca_result *self)
 Deallocate a gravi_pca_result object.
 
void gravi_pca_model_delete (gravi_pca_model *self)
 Deallocate a gravi_pca_model object.
 
static int svd_wrapper (gsl_matrix **A, gsl_matrix **V, gsl_vector **S)
 Handle computing SVD for MxN matrix, M<N.
 
static void svd_flip (gsl_matrix *U, gsl_matrix *V)
 Adjust U and V so that loadings for most significant components are positive.
 
gravi_pca_resultgravi_pca_create_result (const cpl_matrix *data, const cpl_matrix *mask)
 Construct a new gravi_pca_result object from a matrix of visphi data.
 
cpl_error_code gravi_pca_decomp_matrix_svd (gravi_pca_result *self)
 Perform PCA decomposition by calculating singular value decomposition.
 
static double gravi_pca_get_component_sign (const gsl_vector *visphi, const gsl_vector *wave)
 Calculate sign convention on visphi components.
 
cpl_error_code gravi_pca_set_component_signs (gravi_pca_result *self, const cpl_array *wave, const int ncomp)
 Impose sign convention on PCA components.
 
gravi_pca_modelgravi_pca_create_model (const gravi_pca_result **results, int nres, int ncomp)
 Compute median values of PCA components over a set of decomposition results.
 
gravi_pca_modelgravi_pca_load_model (const cpl_matrix *components)
 Create PCA model from existing set of components.
 
cpl_error_code gravi_pca_fit_components_bspline (gravi_pca_model *self, const cpl_array *wave, int degree, int ncomp)
 Fit B-spline model to each of a set of median-averaged PCA components.
 
cpl_error_code gravi_pca_fit_components_polynomial (gravi_pca_model *self, const cpl_array *wave, int degree, int ncomp)
 Fit polynomial model to each of a set of median-averaged PCA components.
 
cpl_error_code gravi_pca_refine_mean (gravi_pca_result *self, const cpl_matrix *residual)
 Override the mean component calculated from the PCA decomposition. In conjunction with the fit_mean_subtracted option to the gravi_pca_fit_model function, this can be used to obtain an improved fit.
 
cpl_vector * gravi_pca_get_component_median (const gravi_pca_model *self, int component)
 Get median-averaged component from a set of PCA decompositions.
 
cpl_vector * gravi_pca_get_component_fit (const gravi_pca_model *self, int component)
 Get fit to components from PCA decomposition.
 
static double gravi_pca_model_chi2 (const gsl_vector *x, void *params)
 Evaluate chi^2 statistic for fit.
 
cpl_error_code gravi_pca_fit_model (gravi_pca_result *self, const gravi_pca_model *model, cpl_boolean fit_mean_subtracted, cpl_boolean verbose)
 Fit model formed from linear combination of PCA components to data.
 
cpl_vector * gravi_pca_get_component (const gravi_pca_result *self, int component)
 Get components from PCA decomposition.
 
cpl_matrix * gravi_pca_get_data_fit (const gravi_pca_result *self)
 Get noise-free model.
 
cpl_matrix * gravi_pca_get_data_residual (const gravi_pca_result *self)
 Get residual (data - model).
 

Typedef Documentation

◆ gravi_pca_model_params

Type to hold parameters for fitting PCA components to data.

Function Documentation

◆ _gsl_vector_sum()

static double _gsl_vector_sum ( const gsl_vector *  a)
static

Definition at line 45 of file gravi_pca.c.

Referenced by gravi_pca_create_result(), and gravi_pca_refine_mean().

◆ gravi_pca_create_model()

gravi_pca_model * gravi_pca_create_model ( const gravi_pca_result **  results,
int  nres,
int  ncomp 
)

Compute median values of PCA components over a set of decomposition results.

Parameters
resultsArray of gravi_pca_result objects.
num_resultsNumber of PCA results present.
num_componentsNumber of PCA components to calculate medians for.
Returns
Newly-allocated gravi_pca_model object. This object must be deallocated with gravi_pca_model_delete.

Definition at line 423 of file gravi_pca.c.

References _gravi_pca_model_::component_fits, _gravi_pca_model_::median_components, _gravi_pca_model_::n_comp, _gravi_pca_result_::n_wave, and _gravi_pca_model_::n_wave.

Referenced by gravi_compute_pca().

◆ gravi_pca_create_result()

gravi_pca_result * gravi_pca_create_result ( const cpl_matrix *  data,
const cpl_matrix *  mask 
)

Construct a new gravi_pca_result object from a matrix of visphi data.

Parameters
dataSource data matrix. The matrix should have size MxN, with M the number of observations and N the number of wavelengths.
maskMask matrix. Should match the size of data. Nonzero values denote invalid elements. If NULL, all data will be used.
Returns
Newly-allocated gravi_pca_result object. This object must be deallocated with gravi_pca_result_delete.

Definition at line 219 of file gravi_pca.c.

References _gsl_vector_sum(), _gravi_pca_result_::data, _gravi_pca_result_::data_fit, _gravi_pca_result_::mask, _gravi_pca_result_::mean, _gravi_pca_result_::n_comp, _gravi_pca_result_::n_obs, _gravi_pca_result_::n_valid, _gravi_pca_result_::n_wave, _gravi_pca_result_::S, _gravi_pca_result_::signs, and _gravi_pca_result_::Vt.

Referenced by gravi_compute_pca(), and gravi_flatten_vis().

◆ gravi_pca_decomp_matrix_svd()

cpl_error_code gravi_pca_decomp_matrix_svd ( gravi_pca_result self)

Perform PCA decomposition by calculating singular value decomposition.

Parameters
selfThe gravi_pca_result object to perform the decomposition on.

Definition at line 283 of file gravi_pca.c.

References _gravi_pca_result_::data, _gravi_pca_result_::n_obs, _gravi_pca_result_::n_valid, _gravi_pca_result_::n_wave, _gravi_pca_result_::S, svd_flip(), svd_wrapper(), and _gravi_pca_result_::Vt.

Referenced by gravi_compute_pca().

◆ gravi_pca_fit_components_bspline()

cpl_error_code gravi_pca_fit_components_bspline ( gravi_pca_model self,
const cpl_array *  wave,
int  degree,
int  ncomp 
)

Fit B-spline model to each of a set of median-averaged PCA components.

Parameters
selfThe gravi_pca_model object obtained from a previous call to gravi_pca_create_model.
waveArray of wavlength values.
degreeDegree of fit (number of B-spline coefficients).
ncompNumber of components to fit.

Definition at line 511 of file gravi_pca.c.

References _gravi_pca_model_::component_fits, _gravi_pca_model_::median_components, _gravi_pca_model_::n_comp, and _gravi_pca_model_::n_wave.

Referenced by gravi_compute_pca().

◆ gravi_pca_fit_components_polynomial()

cpl_error_code gravi_pca_fit_components_polynomial ( gravi_pca_model self,
const cpl_array *  wave,
int  degree,
int  ncomp 
)

Fit polynomial model to each of a set of median-averaged PCA components.

Parameters
selfThe gravi_pca_model object obtained from a previous call to gravi_pca_create_model.
waveArray of wavlength values.
degreeDegree of fit (order of polynomial).
ncompNumber of components to fit.

Definition at line 587 of file gravi_pca.c.

References _gravi_pca_model_::component_fits, _gravi_pca_model_::median_components, _gravi_pca_model_::n_comp, and _gravi_pca_model_::n_wave.

Referenced by gravi_compute_pca().

◆ gravi_pca_fit_model()

cpl_error_code gravi_pca_fit_model ( gravi_pca_result self,
const gravi_pca_model model,
cpl_boolean  fit_mean_subtracted,
cpl_boolean  verbose 
)

Fit model formed from linear combination of PCA components to data.

Parameters
selfThe gravi_pca_result object containing data to fit.
modelThe gravi_pca_model object containing the model PCA component to fit with.
fit_mean_subtractedIf True, fit to the mean-subtracted data, otherwise add the mean back on first.

Definition at line 792 of file gravi_pca.c.

References _gravi_pca_model_::component_fits, _gravi_pca_result_::data, _gravi_pca_result_::data_fit, gravi_pca_model_chi2(), _gravi_pca_result_::mask, _gravi_pca_result_::mean, _gravi_pca_result_::n_comp, _gravi_pca_model_::n_comp, _gravi_pca_model_params_::n_data, _gravi_pca_result_::n_obs, and _gravi_pca_model_::n_wave.

Referenced by gravi_compute_pca(), and gravi_flatten_vis().

◆ gravi_pca_get_component()

cpl_vector * gravi_pca_get_component ( const gravi_pca_result self,
int  component 
)

Get components from PCA decomposition.

Parameters
selfThe gravi_pca_result object obtained from a previous decomposition.
componentThe component to return. 0 will return the mean, 1 the first PCA component, etc.
Returns
Vector of components with length N, the number of observations in the original data.

Definition at line 907 of file gravi_pca.c.

References _gravi_pca_result_::mean, _gravi_pca_result_::n_wave, _gravi_pca_result_::signs, and _gravi_pca_result_::Vt.

Referenced by gravi_compute_pca().

◆ gravi_pca_get_component_fit()

cpl_vector * gravi_pca_get_component_fit ( const gravi_pca_model self,
int  component 
)

Get fit to components from PCA decomposition.

Parameters
selfThe gravi_pca_model object obtained from a previous call to gravi_pca_create_model. One of the functions gravi_pca_fit_components_{polynomial,spline} must have previously been called.
componentThe component to return the fit for, indexed from 1.
Returns
Vector of fitted values with length n_wave.

Definition at line 716 of file gravi_pca.c.

References _gravi_pca_model_::component_fits, and _gravi_pca_model_::n_wave.

Referenced by gravi_compute_pca().

◆ gravi_pca_get_component_median()

cpl_vector * gravi_pca_get_component_median ( const gravi_pca_model self,
int  component 
)

Get median-averaged component from a set of PCA decompositions.

Parameters
selfThe gravi_pca_model object obtained from a previous call to gravi_pca_create_model.
componentThe component to return, indexed from 1.
Returns
Vector of components with length n_wave.

Definition at line 694 of file gravi_pca.c.

References _gravi_pca_model_::median_components, and _gravi_pca_model_::n_wave.

Referenced by gravi_compute_pca().

◆ gravi_pca_get_component_sign()

static double gravi_pca_get_component_sign ( const gsl_vector *  visphi,
const gsl_vector *  wave 
)
static

Calculate sign convention on visphi components.

Parameters
visphiArray of visphi component values.
waveArray of wavelength values.
Returns
value by which components should be multiplied, either +1 or -1.

Definition at line 337 of file gravi_pca.c.

Referenced by gravi_pca_set_component_signs().

◆ gravi_pca_get_data_fit()

cpl_matrix * gravi_pca_get_data_fit ( const gravi_pca_result self)

Get noise-free model.

Parameters
selfThe gravi_pca_result object obtained from a previous decomposition.
Returns
Matrix of fitted values with same dimensions as original data.

Definition at line 935 of file gravi_pca.c.

References _gravi_pca_result_::data_fit, _gravi_pca_result_::n_obs, and _gravi_pca_result_::n_wave.

Referenced by gravi_flatten_vis().

◆ gravi_pca_get_data_residual()

cpl_matrix * gravi_pca_get_data_residual ( const gravi_pca_result self)

Get residual (data - model).

Parameters
selfThe gravi_pca_result object obtained from a previous decomposition.
Returns
Matrix of residual values with same dimensions as original data.

Definition at line 956 of file gravi_pca.c.

References _gravi_pca_result_::data, _gravi_pca_result_::data_fit, _gravi_pca_result_::mean, _gravi_pca_result_::n_obs, and _gravi_pca_result_::n_wave.

Referenced by gravi_compute_pca(), and gravi_flatten_vis().

◆ gravi_pca_load_model()

gravi_pca_model * gravi_pca_load_model ( const cpl_matrix *  components)

Create PCA model from existing set of components.

Parameters
componentsMatrix of component values, size (n_components, n_wave). First row is mean, second is primary component, etc.
Returns
Newly-allocated gravi_pca_model object. This object must be deallocated with gravi_pca_model_delete.

Definition at line 483 of file gravi_pca.c.

References _gravi_pca_model_::component_fits, _gravi_pca_model_::median_components, _gravi_pca_model_::n_comp, and _gravi_pca_model_::n_wave.

Referenced by gravi_flatten_vis().

◆ gravi_pca_model_chi2()

static double gravi_pca_model_chi2 ( const gsl_vector *  x,
void *  params 
)
static

Evaluate chi^2 statistic for fit.

Parameters
xVector of coefficients C_i.
paramsFit parameter values, of actual type gravi_pca_model_params.

Definition at line 745 of file gravi_pca.c.

References _gravi_pca_model_params_::components, _gravi_pca_model_params_::data, _gravi_pca_model_params_::mask, _gravi_pca_model_params_::n_components, and _gravi_pca_model_params_::n_data.

Referenced by gravi_pca_fit_model().

◆ gravi_pca_model_delete()

void gravi_pca_model_delete ( gravi_pca_model self)

Deallocate a gravi_pca_model object.

Parameters
selfmodel object to free.

Definition at line 118 of file gravi_pca.c.

References _gravi_pca_model_::component_fits, FREE, and _gravi_pca_model_::median_components.

Referenced by gravi_compute_pca(), and gravi_flatten_vis().

◆ gravi_pca_refine_mean()

cpl_error_code gravi_pca_refine_mean ( gravi_pca_result self,
const cpl_matrix *  residual 
)

Override the mean component calculated from the PCA decomposition. In conjunction with the fit_mean_subtracted option to the gravi_pca_fit_model function, this can be used to obtain an improved fit.

Parameters
selfThe gravi_pca_model object obtained from a previous call to gravi_pca_create_model.
residualThe matrix of residuals with dimensions (n_obs, n_wave) equal to the original data.

Definition at line 652 of file gravi_pca.c.

References _gsl_vector_sum(), _gravi_pca_result_::data, _gravi_pca_result_::mean, _gravi_pca_result_::n_obs, and _gravi_pca_result_::n_wave.

Referenced by gravi_compute_pca().

◆ gravi_pca_result_delete()

void gravi_pca_result_delete ( gravi_pca_result self)

Deallocate a gravi_pca_result object.

Parameters
selfresult object to free.

Definition at line 99 of file gravi_pca.c.

References _gravi_pca_result_::data, _gravi_pca_result_::data_fit, FREE, _gravi_pca_result_::mask, _gravi_pca_result_::mean, _gravi_pca_result_::S, _gravi_pca_result_::signs, and _gravi_pca_result_::Vt.

Referenced by gravi_compute_pca(), and gravi_flatten_vis().

◆ gravi_pca_set_component_signs()

cpl_error_code gravi_pca_set_component_signs ( gravi_pca_result self,
const cpl_array *  wave,
const int  ncomp 
)

Impose sign convention on PCA components.

Note
The SVD of a matrix is unique up to the sign of the component values, so we arbitrarily enforce a convention that the components should be positive for 2.02 < lambda(um) < 2.04 and 2.34 < lambda(um) < 2.36.
Parameters
resultgravi_pca_result object.
waveArray of wavelength values.
num_componentsNumber of components to compute signs for.

Definition at line 393 of file gravi_pca.c.

References gravi_pca_get_component_sign(), _gravi_pca_result_::n_wave, _gravi_pca_result_::signs, and _gravi_pca_result_::Vt.

Referenced by gravi_compute_pca().

◆ svd_flip()

static void svd_flip ( gsl_matrix *  U,
gsl_matrix *  V 
)
static

Adjust U and V so that loadings for most significant components are positive.

Parameters
Uthe U matrix.
Vthe V matrix.
Note
See: https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/utils/extmath.py#L766 but note that their V is actually Vt, which is not the case here.

Definition at line 175 of file gravi_pca.c.

Referenced by gravi_pca_decomp_matrix_svd().

◆ svd_wrapper()

static int svd_wrapper ( gsl_matrix **  A,
gsl_matrix **  V,
gsl_vector **  S 
)
static

Handle computing SVD for MxN matrix, M<N.

Parameters
[in,out]APointer to the matrix to decompose. Will be replaced with the value U.
[in,out]VPointer to hold matrix of right singular vectors.
[out]SVector of singular values.
Note
The arguments V and S are allocated and assigned by this function. They should be deallocated using gsl_{matrix,vector}_free. The argument A is modified and may be reassigned by this function.

Definition at line 138 of file gravi_pca.c.

Referenced by gravi_pca_decomp_matrix_svd().