README.Rmd

---
output:
  github_document:
    pandoc_args: [ "--wrap=preserve", "--columns=80" ]
bibliography: inst/REFERENCES.bib
link-citations: yes
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```


# grasps <img src="man/figures/logo.png" align="right" alt="" width="150">


## Groupwise Regularized Adaptive Sparse Precision Solution


[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/grasps)](https://CRAN.R-project.org/package=grasps)
[![GitHub R package version](https://img.shields.io/github/r-package/v/Carol-seven/grasps?label=R%20in%20dev&color=green)](https://github.com/Carol-seven/grasps/blob/main/DESCRIPTION)
[![GitHub last commit](https://img.shields.io/github/last-commit/Carol-seven/grasps)](https://github.com/Carol-seven/grasps/commits/main)
[![R-CMD-check](https://github.com/Carol-seven/grasps/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/Carol-seven/grasps/actions/workflows/R-CMD-check.yaml)
[![GitHub License](https://img.shields.io/github/license/Carol-seven/grasps?color=blue)](https://github.com/Carol-seven/grasps/blob/main/LICENSE.md)


The goal of **grasps** is to provide a collection of statistical methods that
incorporate both element-wise and group-wise penalties to estimate a precision
matrix, making them user-friendly and useful for researchers and practitioners.


$$
\hat{\Omega}(\lambda,\alpha,\gamma) = {\arg\min}_{\Omega \succ 0}
\{ -\log\det(\Omega) + \text{tr}(S\Omega) + \mathcal{P}_{\lambda,\alpha,\gamma}(\Omega) \},
$$
$$
\mathcal{P}_{\lambda,\alpha,\gamma}(\Omega)
= \alpha \mathcal{P}^\text{idv}_{\lambda,\gamma}(\Omega) + (1-\alpha) \mathcal{P}^\text{grp}_{\lambda,\gamma}(\Omega),
$$
$$
\mathcal{P}^\text{idv}_{\lambda,\gamma}(\Omega)
= \sum_{i,j} P_{\lambda,\gamma}(\lvert\omega_{ij}\rvert),
$$
$$
\mathcal{P}^\text{grp}_{\lambda,\gamma}(\Omega)
= \sum_{g,g^\prime} P_{\lambda,\gamma}(\lVert\Omega_{gg^\prime}\rVert_F).
$$


For more details, see the vignette
[Penalized Precision Matrix Estimation in grasps](https://shiying-xiao.com/grasps/articles/pen_est#sparse-group-estimator).


![](https://raw.githubusercontent.com/Carol-seven/grasps/refs/heads/main/man/figures/workflow.png)


## Penalties


The package **grasps** provides functions to estimate precision matrices using
the following penalties:


| Penalty | Reference |
|:--------|:----------|
| Lasso (`penalty = "lasso"`) | @tibshirani1996regression; @friedman2008sparse |
| Adaptive lasso (`penalty = "adapt"`) | @zou2006adaptive; @fan2009network |
| Atan (`penalty = "atan"`) | @wang2016variable |
| Exp (`penalty = "exp"`) | @wang2018variable |
| Lq (`penalty = "lq"`) | @frank1993statistical; @fu1998penalized; @fan2001variable |
| LSP (`penalty = "lsp"`) | @candes2008enhancing |
| MCP (`penalty = "mcp"`) | @zhang2010nearly |
| SCAD (`penalty = "scad"`) | @fan2001variable; @fan2009network |


See the vignette
[Penalized Precision Matrix Estimation in grasps](https://shiying-xiao.com/grasps/articles/pen_est#penalties)
for more details.


## Installation


+ You can install the released version of **grasps** from
[CRAN](https://cran.r-project.org/package=grasps) with:


```
install.packages("grasps")
```


+ You can install the development version of **grasps** from
[GitHub](https://github.com/Carol-seven/grasps) with:


```
# install.packages("pak")
pak::pkg_install("Carol-seven/grasps")
```


## Example


```{r}
library(grasps)

## reproducibility for everything
set.seed(1234)

## block-structured precision matrix based on SBM
sim <- gen_prec_sbm(p = 30, K = 3,
                    within.prob = 0.25, between.prob = 0.05,
                    weight.dists = list("gamma", "unif"),
                    weight.paras = list(c(shape = 20, rate = 10),
                                        c(min = 0, max = 5)),
                    cond.target = 100)
## ground truth visualization
plot(sim)

## n-by-p data matrix
library(MASS)
X <- mvrnorm(n = 20, mu = rep(0, 30), Sigma = sim$Sigma)

## precision matrix: adaptive lasso; BIC
prec <- grasps(X = X, membership = sim$membership, penalty = "adapt", crit = "BIC")

## precision matrix visualization
plot(prec)

## performance
performance(hatOmega = prec$hatOmega, Omega = sim$Omega)

## adjacency matrix: diagonal = 0; raw partial correlations;
##                   no thresholding; weighted network
adj <- prec_to_adj(prec$hatOmega,
                   diag.zero = TRUE, absolute = FALSE,
                   threshold = NULL, weighted = TRUE)

## adjacency matrix visualization
plot(adj)
```


## Reference {-}