R: An R6 Class to represent a PLNfit in a PCA framework

PLNPCAfit {PLNmodels} | R Documentation

## An R6 Class to represent a PLNfit in a PCA framework

### Description

The function `PLNPCA()` produces a collection of models which are instances of object with class `PLNPCAfit`. This class comes with a set of methods, some of them being useful for the user: See the documentation for the methods inherited by `PLNfit` and the `plot()` methods for PCA visualization

### Super class

`PLNmodels::PLNfit` -> `PLNPCAfit`

### Active bindings

`rank`

  the dimension of the current model

`nb_param`

  number of parameters in the current PLN model

`entropy`

  entropy of the variational distribution

`latent_pos`

  a matrix: values of the latent position vector (Z) without covariates effects or offset

`model_par`

  a list with the matrices associated with the estimated parameters of the pPCA model: Theta (covariates), Sigma (latent covariance) and B (latent loadings)

`percent_var`

  the percent of variance explained by each axis

`corr_circle`

  a matrix of correlations to plot the correlation circles

`scores`

  a matrix of scores to plot the individual factor maps (a.k.a. principal components)

`rotation`

  a matrix of rotation of the latent space

`eig`

  description of the eigenvalues, similar to percent_var but for use with external methods

`var`

  a list of data frames with PCA results for the variables: `coord` (coordinates of the variables), `cor` (correlation between variables and dimensions), `cos2` (Cosine of the variables) and `contrib` (contributions of the variable to the axes)

`ind`

  a list of data frames with PCA results for the individuals: `coord` (coordinates of the individuals), `cos2` (Cosine of the individuals), `contrib` (contributions of individuals to an axis inertia) and `dist` (distance of individuals to the origin).

`call`

  Hacky binding for compatibility with factoextra functions

### Methods

#### Public methods

- `PLNPCAfit$new()`

- `PLNPCAfit$update()`

- `PLNPCAfit$optimize()`

- `PLNPCAfit$VEstep()`

- `PLNPCAfit$project()`

- `PLNPCAfit$setVisualization()`

- `PLNPCAfit$postTreatment()`

- `PLNPCAfit$compute_fisher()`

- `PLNPCAfit$plot_individual_map()`

- `PLNPCAfit$plot_correlation_circle()`

- `PLNPCAfit$plot_PCA()`

- `PLNPCAfit$show()`

- `PLNPCAfit$clone()`

Inherited methods

- `PLNmodels::PLNfit$compute_standard_error()`

- `PLNmodels::PLNfit$predict()`

- `PLNmodels::PLNfit$print()`

- `PLNmodels::PLNfit$set_R2()`

#### Method `new()`

Initialize a `PLNPCAfit` object

##### Usage

    PLNPCAfit$new(
      rank,
      responses,
      covariates,
      offsets,
      weights,
      formula,
      xlevels,
      control
    )

##### Arguments

`rank`

  rank of the PCA (or equivalently, dimension of the latent space)

`responses`

  the matrix of responses (called Y in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`covariates`

  design matrix (called X in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`offsets`

  offset matrix (called O in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`weights`

  an optional vector of observation weights to be used in the fitting process.

`formula`

  model formula used for fitting, extracted from the formula in the upper-level call

`xlevels`

  named listed of factor levels included in the models, extracted from the formula in the upper-level call and used for predictions.

`control`

  a list for controlling the optimization. See details.

#### Method `update()`

Update a `PLNPCAfit` object

##### Usage

    PLNPCAfit$update(
      Theta = NA,
      Sigma = NA,
      B = NA,
      M = NA,
      S2 = NA,
      Z = NA,
      A = NA,
      Ji = NA,
      R2 = NA,
      monitoring = NA
    )

##### Arguments

`Theta`

  matrix of regression matrix

`Sigma`

  variance-covariance matrix of the latent variables

`B`

  matrix of PCA loadings (in the latent space)

`M`

  matrix of mean vectors for the variational approximation

`S2`

  matrix of variance vectors for the variational approximation

`Z`

  matrix of latent vectors (includes covariates and offset effects)

`A`

  matrix of fitted values

`Ji`

  vector of variational lower bounds of the log-likelihoods (one value per sample)

`R2`

  approximate R^2 goodness-of-fit criterion

`monitoring`

  a list with optimization monitoring quantities

##### Returns

Update the current `PLNPCAfit` object

#### Method `optimize()`

Call to the C++ optimizer and update of the relevant fields

##### Usage

    PLNPCAfit$optimize(responses, covariates, offsets, weights, control)

##### Arguments

`responses`

  the matrix of responses (called Y in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`covariates`

  design matrix (called X in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`offsets`

  offset matrix (called O in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`weights`

  an optional vector of observation weights to be used in the fitting process.

`control`

  a list for controlling the optimization. See details.

#### Method `VEstep()`

Result of one call to the VE step of the optimization procedure: optimal variational parameters (M, S) and corresponding log likelihood values for fixed model parameters (B, Theta). Intended to position new data in the latent space for further use with PCA.

##### Usage

    PLNPCAfit$VEstep(
      covariates,
      offsets,
      responses,
      weights = rep(1, nrow(responses)),
      control = list()
    )

##### Arguments

`covariates`

  design matrix (called X in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`offsets`

  offset matrix (called O in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`responses`

  the matrix of responses (called Y in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`weights`

  an optional vector of observation weights to be used in the fitting process.

`control`

  a list for controlling the optimization. See details.

##### Returns

A list with three components:

- the matrix `M` of variational means,

- the matrix `S2` of variational variances

- the vector `log.lik` of (variational) log-likelihood of each new observation

#### Method `project()`

Project new samples into the PCA space using one VE step

##### Usage

    PLNPCAfit$project(newdata, control = list(), envir = parent.frame())

##### Arguments

`newdata`

  A data frame in which to look for variables, offsets and counts with which to predict.

`control`

  a list for controlling the optimization. See `PLN()` for details.

`envir`

  Environment in which the projection is evaluated

##### Returns

- the named matrix of scores for the newdata, expressed in the same coordinate system as `self$scores`

#### Method `setVisualization()`

Compute PCA scores in the latent space and update corresponding fields.

##### Usage

    PLNPCAfit$setVisualization(scale.unit = FALSE)

##### Arguments

`scale.unit`

  Logical. Should PCA scores be rescaled to have unit variance

#### Method `postTreatment()`

Update R2, fisher, std_err fields and set up visualization after optimization

##### Usage

    PLNPCAfit$postTreatment(responses, covariates, offsets, weights, nullModel)

##### Arguments

`responses`

  the matrix of responses (called Y in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`covariates`

  design matrix (called X in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`offsets`

  offset matrix (called O in the model). Will usually be extracted from the corresponding field in `PLNfamily`

`weights`

  an optional vector of observation weights to be used in the fitting process.

`nullModel`

  null model used for approximate R2 computations. Defaults to a GLM model with same design matrix but not latent variable.

#### Method `compute_fisher()`

Safely compute the fisher information matrix (FIM)

##### Usage

    PLNPCAfit$compute_fisher(type = c("wald", "louis"), X = NULL)

##### Arguments

`type`

  approximation scheme to compute the fisher information matrix. Either `wald` (default) or `louis`. `type = "louis"` results in smaller confidence intervals.

`X`

  design matrix used to compute the FIM

##### Returns

a sparse matrix with sensible dimension names

#### Method `plot_individual_map()`

Plot the factorial map of the PCA

##### Usage

    PLNPCAfit$plot_individual_map(
      axes = 1:min(2, self$rank),
      main = "Individual Factor Map",
      plot = TRUE,
      cols = "default"
    )

##### Arguments

`axes`

  numeric, the axes to use for the plot when map = "individual" or "variable". Default it c(1,min(rank))

`main`

  character. A title for the single plot (individual or variable factor map). If NULL (the default), an hopefully appropriate title will be used.

`plot`

  logical. Should the plot be displayed or sent back as ggplot object

`cols`

  a character, factor or numeric to define the color associated with the individuals. By default, all individuals receive the default color of the current palette.

##### Returns

a `ggplot` graphic

#### Method `plot_correlation_circle()`

Plot the correlation circle of a specified axis for a `PLNLDAfit` object

##### Usage

    PLNPCAfit$plot_correlation_circle(
      axes = 1:min(2, self$rank),
      main = "Variable Factor Map",
      cols = "default",
      plot = TRUE
    )

##### Arguments

`axes`

  numeric, the axes to use for the plot when map = "individual" or "variable". Default it c(1,min(rank))

`main`

  character. A title for the single plot (individual or variable factor map). If NULL (the default), an hopefully appropriate title will be used.

`cols`

  a character, factor or numeric to define the color associated with the variables. By default, all variables receive the default color of the current palette.

`plot`

  logical. Should the plot be displayed or sent back as ggplot object

##### Returns

a `ggplot` graphic

#### Method `plot_PCA()`

Plot a summary of the `PLNPCAfit` object

##### Usage

    PLNPCAfit$plot_PCA(
      nb_axes = min(3, self$rank),
      ind_cols = "ind_cols",
      var_cols = "var_cols",
      plot = TRUE
    )

##### Arguments

`nb_axes`

  scalar: the number of axes to be considered when map = "both". The default is min(3,rank).

`ind_cols`

  a character, factor or numeric to define the color associated with the individuals. By default, all variables receive the default color of the current palette.

`var_cols`

  a character, factor or numeric to define the color associated with the variables. By default, all variables receive the default color of the current palette.

`plot`

  logical. Should the plot be displayed or sent back as ggplot object

##### Returns

a `grob` object

#### Method `show()`

User friendly print method

##### Usage

    PLNPCAfit$show()

#### Method `clone()`

The objects of this class are cloneable with this method.

##### Usage

    PLNPCAfit$clone(deep = FALSE)

##### Arguments

`deep`

  Whether to make a deep clone.

### See Also

The function `PLNPCA`, the class `PLNPCAfamily`

### Examples

    data(trichoptera)
    trichoptera <- prepare_data(trichoptera$Abundance, trichoptera$Covariate)
    myPCAs <- PLNPCA(Abundance ~ 1 + offset(log(Offset)), data = trichoptera, ranks = 1:5)
    myPCA <- getBestModel(myPCAs)
    class(myPCA)
    print(myPCA)

[Package PLNmodels version 0.11.6 Index]