Author: Wenjie Wang
Date: 2021-02-20

# Using splines2 with Rcpp

#### Wenjie Wang

#### 2021-02-20

In this package vignette, we introduce how to use the C++ header-only library that splines2 contains with the Rcpp package (Eddelbuettel 2013) for constructing spline basis functions. The introduction is intended for package developers who would like to use splines2 package at C++ level.

## Header File and Name Space

Different with the procedure based functions at R level, splines2 provides several spline classes in its C++ interface for ease of usage and maintenance. The implementations use the Armadillo (Sanderson 2016) library with help of RcppArmadillo (Eddelbuettel and Sanderson 2014) and require C++11. We may include the header file named `splines2Armadillo.h` to get the access to all the classes and implementations in the name space `splines2`.

    #include <RcppArmadillo.h>
    // [[Rcpp::plugins(cpp11)]]

    // include header file from splines2 package
    #include <splines2Armadillo.h>

    // for ease of demonstration
    using arma
    using splines2

## B-splines

The `BSpline` class is for creating B-spline basis functions.

### Constructors

There are four constructors in addition to the default constructor: `BSpline()`.

The first non-default constructor is called when internal knots are explicitly specified.

    // 1. specified internal_knots
    BSpline(const vec& x,
            const vec& internal_knots,
            const unsigned int degree = 3,
            const vec& boundary_knots = vec())

The second non-default constructor is called when an unsigned integer representing the degree of freedom of the complete spline basis functions (different with `df` in the R interface) is specified. Then the number of internal knots is computed as `spline_df - degree - 1` and the placement of internal knots uses quantiles of specified `x`.

    // 2. specified spline degree of freedom (df)
    BSpline(const vec& x,
            const unsigned int spline_df,
            const unsigned int degree = 3,
            const vec& boundary_knots = vec())

The third non-default constructor is intended for basis functions with an extended knot sequence. The multiplicities of knots in the sequence can be different but should not be greater than `degree + 1`.

    // 3. specified degree and (extended) knot sequence
    BSpline(const rvec& x,
            const unsigned int degree,
            const rvec& knot_sequence)

The fourth non-default constructor is explicit and takes a pointer to a base class object. It can be useful when we want to create a new object using the same specification (degree, internal_knots, boundary_knots, etc.) of an existing object.

    // 4. create a new object from a base class pointer
    BSpline(const SplineBase* pSplineBase)

### Function Members

The main methods are

- `basis()` for spline basis matrix
- `derivative()` for derivatives of spline basis
- `integral()` for integrals of spline basis

The specific function signatures are as follows:

    mat basis(const bool complete_basis = true)
    mat derivative(const unsigned int derivs = 1,
                   const bool complete_basis = true)
    mat integral(const bool complete_basis = true)

In addition, we may set and get the spline specifications through the following setter and getter functions, respectively.

    // setter functions
    SplineBase* set_x(const vec&);
    SplineBase* set_x(const double);
    SplineBase* set_internal_knots(const vec&);
    SplineBase* set_boundary_knots(const vec&);
    SplineBase* set_knot_sequence(const vec&);
    SplineBase* set_degree(const unsigned int);
    SplineBase* set_order(const unsigned int);

    // getter functions
    vec get_x();
    vec get_internal_knots();
    vec get_boundary_knots();
    vec get_knot_sequence();
    unsigned int get_degree();
    unsigned int get_order();
    unsigned int get_spline_df();

The setter function returns a pointer to the current object so that the specification can be chained for convenience. For example,

    vec x { arma::regspace(0, 0.1, 1) }; // 0, 0.1, ..., 1
    BSpline obj { x, 5 };                // df = 5 (and degree = 3, by default)
    // change degree to 2 and get basis
    mat basis_mat { obj.set_degree(2)->basis() };

## M-splines, I-splines, C-splines, and Natural Cubic Splines

The class `MSpline` for M-splines, `ISpline` for I-splines, `CSpline` for C-splines, and `NaturalSpline` have the exactly same constructors and function members with `BSpline` except there is no available `integral()` method for `CSpline` and no `degree` related methods for `NaturalSpline`. The class `PeriodicMSpline` for periodic M-splines also have the same non-default constructors and function members except that it does not have provide constructor and methods for extended knot sequence.

## Generalized Bernstein Polynomials

The `BernsteinPoly` class is implemented for the generalized Bernstein polynomials.

### Constructors

The main non-default constructor is as follows:

    BernsteinPoly(const vec& x,
                  const unsigned int degree,
                  const vec& boundary_knots = vec())

### Function Members

Same with `BSpline`, the main methods are

- `basis()` for basis matrix
- `derivative()` for derivatives of basis functions
- `integral()` for integrals of basis functions

The specific function signatures are as follows:

    mat basis(const bool complete_basis = true)
    mat derivative(const unsigned int derivs = 1,
                   const bool complete_basis = true)
    mat integral(const bool complete_basis = true)

In addition, we may similarly set and get the specifications through the following setter and getter functions, respectively.

    // setter functions
    SplineBase* set_x(const vec&);
    SplineBase* set_x(const double);
    SplineBase* set_degree(const unsigned int);
    SplineBase* set_order(const unsigned int);
    SplineBase* set_boundary_knots(const vec&);

    // getter functions
    vec get_x();
    unsigned int get_degree();
    unsigned int get_order();
    vec get_boundary_knots();

The setter function also returns a pointer to the current object.

## Reference

Eddelbuettel, Dirk. 2013. Seamless R and C++ Integration with Rcpp. Springer.

Eddelbuettel, Dirk, and Conrad Sanderson. 2014. “RcppArmadillo: Accelerating R with High-Performance C++ Linear Algebra.” Computational Statistics and Data Analysis 71: 1054–63. http://dx.doi.org/10.1016/j.csda.2013.02.005.

Sanderson, Conrad. 2016. “Armadillo: An Open Source C++ Linear Algebra Library for Fast Prototyping and Computationally Intensive Experiments.” Journal of Open Source Software 1: 26.