# bpca Overview

## Introduction

`bpca` is an S3-based package for principal component biplot analysis. It supports:

- 2D and 3D biplots;
- multiple factorization methods (`hj`, `sqrt`, `jk`, `gh`);
- graphical diagnostics for representation quality;
- tabular summaries for reporting.

This vignette presents a practical end-to-end workflow.

## Load Package and Data

    library(bpca)
    data(gabriel1971)
    data(ontario)

`gabriel1971` is a classic biplot matrix and works well for reproducible examples.

## 2D Biplot: Core Workflow

    bp2 <- bpca(gabriel1971,
      d = 1:2
    )
    class(bp2)
    #> [1] "bpca.2d" "bpca"    "list"
    bp2$number
    #> [1] 1 2
    round(bp2$importance, 3)
    #>         explained
    #> general     0.973
    #> partial     0.973

Key returned components include:

- `eigenvalues`, `eigenvectors`;
- `number` (selected principal components);
- `importance` (retained variance);
- `coord$objects` and `coord$variables`.

    names(bp2)
    #> [1] "call"         "eigenvalues"  "eigenvectors" "number"       "importance"
    #> [6] "coord"        "var.rb"       "var.rd"
    str(bp2$coord)
    #> List of 2
    #>  $ objects  : num [1:8, 1:8] 3.976 2.593 -2.193 1.746 -0.929 ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>   .. ..$ : chr [1:8] "toilet" "kitchen" "bath" "eletricity" ...
    #>   .. ..$ : chr [1:8] "PC1" "PC2" "PC3" "PC4" ...
    #>  $ variables: num [1:9, 1:8] 2.58 2.6 2.58 2.6 2.43 ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>   .. ..$ : chr [1:9] "CRISTIAN" "ARMENIAN" "JEWISH" "MOSLEM" ...
    #>   .. ..$ : chr [1:8] "PC1" "PC2" "PC3" "PC4" ...

## Summary Output

    summary(bp2)
    #>  Eigenvalue(s):               7.627198 1.771676 1.09626 0.506433 0.3456395 0.3150429 0.1001889 5.766751e-16
    #>   - Considered on reduction:      7.627198 1.771676
    #>   - Variance retained by each:        0.9233991 0.04982279
    #>   - Cumulative variance retained:     0.9233991 0.9732219
    #>   - Prop. of total variance retained:     0.973
    summary(bp2,
      presentation = TRUE
    )
    #>  Eigenvalue(s):               7.627198 1.771676 1.09626 0.506433 0.3456395 0.3150429 0.1001889 5.766751e-16
    #>   - Considered on reduction:      7.627198 1.771676
    #>   - Variance retained by each:        0.9233991 0.04982279
    #>   - Cumulative variance retained:     0.9233991 0.9732219
    #>   - Prop. of total variance retained:     0.973

## Factorization Methods

    methods <- c("hj", "sqrt", "jk", "gh")
    retained <- sapply(
      methods,
      function(m) {
        bp <- bpca(gabriel1971,
          method = m,
          d = 1:2
        )
        as.numeric(bp$importance["general", "explained"])
      }
    )
    retained
    #>    hj  sqrt    jk    gh
    #> 0.973 0.973 0.973 0.973

The retained variance can be similar across methods, but geometric interpretation differs.

## Representation Quality Diagnostics

`var.rb` stores projected correlations among variables under the selected biplot reduction.

    bp2_q <- bpca(gabriel1971,
      d = 1:2,
      var.rb = TRUE
    )
    round(bp2_q$var.rb, 2)
    #>          CRISTIAN ARMENIAN JEWISH MOSLEM MODERN.1 MODERN.2 OTHER.1 OTHER.2  RUR
    #> CRISTIAN     1.00     1.00   1.00   1.00     0.88     0.87    0.98    1.00 0.99
    #> ARMENIAN     1.00     1.00   1.00   1.00     0.87     0.86    0.98    1.00 0.99
    #> JEWISH       1.00     1.00   1.00   1.00     0.83     0.82    0.97    0.99 1.00
    #> MOSLEM       1.00     1.00   1.00   1.00     0.86     0.85    0.98    1.00 1.00
    #> MODERN.1     0.88     0.87   0.83   0.86     1.00     1.00    0.95    0.90 0.80
    #> MODERN.2     0.87     0.86   0.82   0.85     1.00     1.00    0.94    0.89 0.79
    #> OTHER.1      0.98     0.98   0.97   0.98     0.95     0.94    1.00    0.99 0.95
    #> OTHER.2      1.00     1.00   0.99   1.00     0.90     0.89    0.99    1.00 0.98
    #> RUR          0.99     0.99   1.00   1.00     0.80     0.79    0.95    0.98 1.00

`qbpca()` compares observed vs projected correlations in vectorized form.

    q2 <- qbpca(
      gabriel1971,
      bp2_q
    )
    head(q2)
    #>                             obs    var.rb
    #> CRISTIAN vs. ARMENIAN 0.9973894 0.9999397
    #> CRISTIAN vs. JEWISH   0.9561588 0.9961640
    #> CRISTIAN vs. MOSLEM   0.9857920 0.9991587
    #> CRISTIAN vs. MODERN.1 0.8665372 0.8773237
    #> CRISTIAN vs. MODERN.2 0.8216573 0.8674140
    #> CRISTIAN vs. OTHER.1  0.9520075 0.9849207

`var.rd` highlights poorly represented variable correlations for a chosen threshold (`limit`).

    bp2_rd <- bpca(gabriel1971,
      d = 1:2,
      var.rb = TRUE,
      var.rd = TRUE,
      limit = 3
    )
    bp2_rd$var.rd
    #>          CRISTIAN ARMENIAN JEWISH MOSLEM MODERN.1 MODERN.2 OTHER.1 OTHER.2 RUR
    #> CRISTIAN        -               *                        *       *       *   *
    #> ARMENIAN                 -      *                        *                   *
    #> JEWISH          *        *      -                                            *
    #> MOSLEM                                 -                                     *
    #> MODERN.1                                        -                            *
    #> MODERN.2        *        *                               -
    #> OTHER.1         *                                                -           *
    #> OTHER.2         *                                                        -   *
    #> RUR             *        *      *      *        *                *       *   -

## 3D Workflow

    bp3 <- bpca(gabriel1971,
      d = 1:3,
      var.rb = TRUE
    )
    bp3$number
    #> [1] 1 2 3
    round(bp3$importance, 3)
    #>         explained
    #> general     0.992
    #> partial     0.992

## Plot Types and Examples

The `plot.bpca.2d` method supports several analysis-oriented views via `type`:

- `"bp"`: basic biplot;
- `"eo"`: evaluate one object;
- `"ev"`: evaluate one variable;
- `"co"` / `"cv"`: compare objects / variables;
- `"ww"`, `"dv"`, `"ms"`, `"ro"`, `"rv"` for GGE-style diagnostics.

Examples (kept as non-evaluated chunks to keep vignette deterministic):

    # Basic 2D
    plot(bp2)

    # Evaluate one object
    plot(bpca(ontario),
      type = "eo",
      obj.id = 7
    )

    # Evaluate one variable
    plot(bpca(ontario),
      type = "ev",
      var.id = "E7"
    )

    # Compare two objects
    plot(bpca(ontario),
      type = "co",
      obj.id = c("g7", "g13")
    )

3D rendering can be static (`scatterplot3d`) or interactive (`rgl`):

    # Static 3D
    plot(bp3)

    # Interactive 3D
    plot(bp3,
      rgl.use = TRUE
    )

## Tabular Reporting with xtable

The package provides an `xtable` method for `bpca` objects.

    if (requireNamespace("xtable", quietly = TRUE)) {
      tbl <- xtable::xtable(bp2)
      tbl[1:6, , drop = FALSE]
    }
    #> % latex table generated in R 4.7.0 by xtable 1.8-8 package
    #> % Mon May 25 13:33:24 2026
    #> \begin{table}[ht]
    #> \centering
    #> \begin{tabular}{lrrr}
    #>   \hline
    #>   &&\multicolumn{2}{c}{Eigenvectors\_MOSLEM} \\ \cline{3-4}
    #>  &&  PC1 $(\lambda_1=0.34)$& PC2 $(\lambda_2=0.21)$ \\
    #>   \hline
    #>  \multirow{3}{*}{Eigenvectors}&CRISTIAN&0.34&0.15 \\
    #> &ARMENIAN & 0.34 & 0.17 \\
    #>   &JEWISH & 0.34 & 0.28 \\
    #>    \hline
    #> &Eigenvectors\_MODERN.1 & 0.32 & -0.58 \\
    #>   &Eigenvectors\_MODERN.2 & 0.31 & -0.60 \\
    #>    \hline
    #> \end{tabular}
    #> \end{table}

Use `print()` (S3) so the `xtable.bpca` formatter runs; `xtable::print.xtable()` does not dispatch to it.

### HTML (this vignette)

For HTML output (including this `html_vignette`), pass `type="html"`. The chunk must use `results='asis'` so the table is inserted as raw HTML.

    if (requireNamespace("xtable",
      quietly = TRUE
    )) {
      tbl <- xtable::xtable(bp2)
      print(tbl,
        type = "html"
      )
    }

| PC1 (λ1=7.63) | PC2 (λ2=1.77)
--- | --- | ---
CRISTIAN | 0.34 | 0.15
ARMENIAN | 0.34 | 0.17
JEWISH | 0.34 | 0.28
MOSLEM | 0.34 | 0.21
MODERN.1 | 0.32 | -0.58
MODERN.2 | 0.31 | -0.60
OTHER.1 | 0.35 | -0.11
OTHER.2 | 0.34 | 0.07
RUR | 0.32 | 0.34
Variance retained | 0.92 | 0.05
Variance accumulated | 0.92 | 0.97

### LaTeX (PDF reports)

To generate the biplot-style LaTeX table (e.g. `pdf_document` or Sweave), use the default `type` and call `print()`:

    tbl <- xtable::xtable(bp2,
      caption = "Biplot summary",
      label = "tab:bp2"
    )
    rn <- rownames(tbl)
    idx_retained <- which(rn == "Variance retained")
    hlines <- c(-1, 0, nrow(tbl) - 1L)
    if (length(idx_retained) == 1L && idx_retained > 1L) {
      hlines <- c(hlines, idx_retained - 1L)
    }
    hlines <- sort(unique(hlines))
    print(tbl,
      hline.after = hlines
    )

## Notes

- Use `d=1:2` for 2D and `d=1:3` for 3D.
- Prefer `var.rb=TRUE` and `var.rd=TRUE` when diagnosis quality is part of your analysis workflow.
- For scripts and reproducibility, prefer explicit package namespaces in custom reporting code (`xtable::`, `rgl::`).