makeSparseMatrix {GENESIS} | R Documentation

## Make a sparse matrix from a dense matrix or a table of pairwise values

### Description

`makeSparseMatrix` is used to create a sparse block-diagonal matrix from a dense matrix or a table of pairwise values, using a user-specified threshold for sparsity. An object of class `Matrix` will be returned. A sparse matrix may be useful for fitting the association test null model with `fitNullModel` when working with very large sample sizes.

### Usage

    ## S4 method for signature 'data.table'
    makeSparseMatrix(x, thresh = NULL, sample.include = NULL, diag.value = NULL,
                     verbose = TRUE)
    ## S4 method for signature 'data.frame'
    makeSparseMatrix(x, thresh = NULL, sample.include = NULL, diag.value = NULL,
                     verbose = TRUE)
    ## S4 method for signature 'matrix'
    makeSparseMatrix(x, thresh = 2^(-11/2), sample.include = NULL, diag.value = NULL,
                     verbose = TRUE)
    ## S4 method for signature 'Matrix'
    makeSparseMatrix(x, thresh = 2^(-11/2), sample.include = NULL, diag.value = NULL,
                     verbose = TRUE)

### Arguments

`x` | An object to coerce to a sparse matrix. May be of class `matrix`, `Matrix`, `data.frame`, or `data.table`. When a `matrix` or `Matrix`, row and column names should be set to sample.ids; when a data.frame or data.table, should have 3 columns: ID1, ID2, and value.
`thresh` | Value threshold for clustering samples to make the output matrix sparse block-diagonal. When `NULL`, no clustering is done. See 'Details'.
`sample.include` | An optional vector of sample.id indicating all samples that should be included in the output matrix; see 'Details' for usage.
`diag.value` | When `NULL` (by Default), values for the diagonal of the output matrix should be provided in `x`. Setting `diag.value` to a numeric value will make all values on the diagonal of the output matrix that value.
`verbose` | A logical indicating whether or not to print status updates to the console; the default is TRUE.

### Details

`sample.include` has two primary functions: 1) It can be used to subset samples provided in `x`. 2) `sample.include` can include sample.id not in `x`; these additional samples will be included in the output matrix, with a value of 0 for all off-diagonal elements, and the value provided by `diag.value` for the diagonal elements. When left `NULL`, the function will determine the list of samples from what is observed in `x`.

`thresh` sets a threhsold for clustering samples such that any pair with a value greater than `thresh` is in the same cluster. All values within a cluster are kept, even if they are below `thresh`. All values between clusters are set to 0, creating a sparse, block-diagonal matrix. When `thresh` is `NULL`, no clustering is done and all samples are returned in one block. This feature is useful when converting a data.frame of kinship estimates to a matrix.

### Value

An object of class '`Matrix`'. Samples may be in a different order than in the input `x`, as samples are sorted by ID or rowname within each block (including within the block of unrelateds).

### Author(s)

Matthew P. Conomos

### See Also

`kingToMatrix` and `pcrelateToMatrix` for functions that use this function.

[Package GENESIS version 2.20.1 Index]