# Chapter 9 Matrix

## 9.1 Creating Matrix object

`Matrix` objects can be created in several ways.

``````// Create a Matrix object equivalent to
// m <- matrix(0, nrow=2, ncol=2)
NumericMatrix m1( 2 );

// m <- matrix(0, nrow=2, ncol=3)
NumericMatrix m2( 2 , 3 );

// m <- matrix(v, nrow=2, ncol=3)
NumericMatrix m3( 2 , 3 , v.begin() );``````

In addition, a matrix object in R is actually a vector that the number of rows and columns are set in the attribute `dim`. Thus, if you create a vector with attribute `dim` in Rcpp and return it to R, it will be treated as a matrix.

``````// [[Rcpp::export]]
NumericVector rcpp_matrix(){
// Creating a vector object
NumericVector v = {1,2,3,4};

// Set the number of rows and columns to attribute dim of the vector object.
v.attr("dim") = Dimension(2, 2);

// Return the vector to R
return v;
}``````

Execution result

``````> rcpp_matrix()
[,1] [,2]
[1,]    1    3
[2,]    2    4``````

However, even if you set a value to attribute `dim` of a `Vector` object, the type of the object remains a `Vector` type in Rcpp code. Thus, if you want to convert it to `Matrix` type in Rcpp, you need to use `as<T>()` function.

``````// Set number of rows and columns to attribute dim
v.attr("dim") = Dimension(2, 2);

// Converting to Rcpp Matrix type
NumericMatrix m = as<NumericMatrix>(v);``````

## 9.2 Accessing to Matrix elements

By using the `()` operator, you can get from and assign to the values of elements of a `Matrix` object by specifying its column number and row number. As in the case of vectors, row numbers and column numbers in `Matrix` start with 0. If you want to access a specific row or column, use the symbol `_`.

You can also use the `[]` operator to access an element as a vector connecting the columns of a matrix.

``````// Creating a 5x5 numerical matrix
NumericMatrix m( 5, 5 );

// Retrieving the element of row 0 and column 2
double x = m( 0 , 2 );

// Copying the value of row 0 to the vector v
NumericVector v = m( 0 , _ );

// Copying the value of column 2 to the vector v
NumericVector v = m( _ , 2 );

// Copying the row (0 to 1) and column (2 to 3) to the matrix m2
NumericMatrix m2 = m( Range(0,1) , Range(2,3) );

// Accessing matrix element as vector
m[5]; // This points to the same element as m(0,1)``````

### 9.2.1 Accessing as reference to row, column and sub matrix

Rcpp also provides types that hold “references” to specific parts of a matrix.

``````NumericMatrix::Column col = m( _ , 1);  // Reference to the column 1
NumericMatrix::Row    row = m( 1 , _ ); // Reference to the row 1
NumericMatrix::Sub    sub = m( Range(0,1) , Range(2,3) ); // Reference to sub matrix``````

Assigning a value to a “reference” object of a matrix is equivalent to assigning the value to its original matrix. For example, assigning a value to `col` will assign a value to the column 1 of `m`.

``````// Reference to the column 1
NumericMatrix::Column col = m( _ , 1);

// The value of the column 1 of matrix m will be doubled
col = 2 * col;

// Synonymous with the above example
m( _ , 1) = 2 * m( _ , 1 );``````

## 9.3 Member functions

Since `Matrix` is actually `Vector`, `Matrix` basically has the same member functions as `Vector`. Thus, member functions unique to `Matrix` are only presented below.

### 9.3.1 nrow() rows()

Returns the number of rows.

### 9.3.2 ncol()　cols()

Returns the number of columns.

### 9.3.3 row( i )

Return a reference `Vector::Row` to the `i`th　row.

### 9.3.4 column( i )

Return a reference `Vector::Column` to the `i`th　column.

### 9.3.5 fill_diag( x )

Fill diagonal elements with scalar value `x`.

### 9.3.6 offset( i, j )

Returns the numerical index in the original vector of the matrix corresponding to the element of row `i` and column `j`.

## 9.4 Static member functions

`Matrix` basically has the same static member function as `Vector`. The static member functions unique to `Matrix` are shown below.

### 9.4.1 Matrix::diag( size, x )

Returns a diagonal matrix whose number of rows and columns equals to “size” and the value of the diagonal element is “x”.