---
title: "Principal Curves of Oriented Points"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Principal Curves of Oriented Points}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

`Rpcop` computes principal curves of oriented points (PCOP) following Delicado
(2001) and Delicado and Huerta (2003). The package wraps the original C++
implementation with an R interface and returns both the original PCOP table and
a `princurve`-style projected curve.

The main function is `pcop()`. It accepts a finite numeric matrix or numeric
data frame, where rows are observations and columns are coordinates.

```{r}
library(Rpcop)

set.seed(1)
n <- 120
t <- runif(n, -1, 1)
x <- cbind(t, t^2 + rnorm(n, sd = 0.08))

fit <- pcop(x, Ch = 1.5, Cd = 0.3, plot.true = FALSE)
names(fit)
head(fit$pcop.f1)
summary(fit)
```

`pcop.f1` stores the PCOP output in the original tabular format. `pcop.f2`
stores the projected curve in the format returned by `princurve`, including the
curve coordinates in `fit$pcop.f2$s`.

```{r}
str(fit$pcop.f2, max.level = 1)
```

The `Ch` argument controls the smoothing bandwidth relative to the normal
reference rule. The `Cd` argument controls the approximate spacing between
consecutive principal oriented points relative to that bandwidth. The accepted
ranges are documented in `?pcop`.

PCOP is distance-based, so coordinate scaling can affect the fitted curve. The
wrapper first runs the native backend on the submitted scale. If that backend
fails, it retries on internally standardized coordinates and maps the returned
curve coordinates back to the submitted scale. The submitted data are not
modified.

The wrapper rejects missing, infinite, and non-numeric inputs before calling the
native backend. Plotting is available for two-dimensional inputs:

```{r, fig.width=5, fig.height=4}
pcop(x, plot.true = TRUE, lwd = 2, col = 2)
```