### Initialize cancereffectsizeR Environment

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/cancereffectsizeR.html

Basic setup required to start an analysis, loading the necessary libraries for data manipulation and effect sizing.

```R
library(cancereffectsizeR)
library(data.table)
```

--------------------------------

### Install Reference Data Set

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/cancereffectsizeR.html

Downloads and installs the hg38 reference data set (refset) required for genomic annotations and mutational signature definitions.

```R
options(timeout = 600)
remotes::install_github("Townsend-Lab-Yale/ces.refset.hg38@*release")
```

--------------------------------

### Install cancerEffectSizeR Package

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/user_guide/cancereffectsizeR_user_guide.md

Installs the 'cancereffectsizeR' R package and its dependencies. This includes installing 'devtools' and then installing 'cancereffectsizeR' from GitHub. For users new to R, it also includes installing Bioconductor packages like 'rtracklayer', 'GenomicRanges', 'BSgenome', and 'BSgenome.Hsapiens.UCSC.hg19', as well as 'deconstructSigs' and 'dndscv'.

```r
install.packages("devtools",repos = "https://cloud.r-project.org")
devtools::install_github("Townsend-Lab-Yale/cancereffectsizeR@0.1.0")
```

```r
source("https://bioconductor.org/biocLite.R")
biocLite("rtracklayer")
biocLite("GenomicRanges")
biocLite("BSgenome")
biocLite("BSgenome.Hsapiens.UCSC.hg19")
install.packages("deconstructSigs",repos = "https://cloud.r-project.org")
install.packages("devtools",repos = "https://cloud.r-project.org")
devtools::install_github("im3sanger/dndscv@0.1.0")
devtools::install_github("Townsend-Lab-Yale/cancereffectsizeR@0.1.0")
```

--------------------------------

### Install cancereffectsizeR and Dependencies

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/cancereffectsizeR.html

Installs the cancereffectsizeR package along with its required dependencies from GitHub and Bioconductor. It includes a timeout adjustment to ensure large package downloads complete successfully.

```R
options(timeout = 600)
install.packages(c("remotes", "BiocManager"))
remotes::install_github("Townsend-Lab-Yale/cancereffectsizeR", dependencies = TRUE, repos = BiocManager::repositories())
```

--------------------------------

### GET /reference/cosmic

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/index.html

Retrieves information regarding COSMIC mutational signatures.

```APIDOC
## GET /cosmic_signature_info

### Description
Retrieves descriptions and metadata for COSMIC mutational signatures.

### Method
GET

### Endpoint
/cosmic_signature_info

### Parameters
#### Query Parameters
- **signature_set** (string) - Optional - The name of the signature set to query.

### Response
#### Success Response (200)
- **info** (data.frame) - Table containing signature descriptions and metadata.
```

--------------------------------

### GET /cosmic_signature_info

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/cosmic_signature_info.html

Retrieves a table containing descriptions and metadata for COSMIC signatures.

```APIDOC
## GET /cosmic_signature_info

### Description
Returns a table describing COSMIC signatures. Includes all signatures from v3.0 to v3.4 with information derived from the official COSMIC website.

### Method
GET

### Endpoint
cosmic_signature_info()

### Parameters
None

### Request Example
N/A (Function call)

### Response
#### Success Response (200)
- **data** (table) - A table object containing signature IDs, descriptions, and associated metadata.

#### Response Example
{
  "signature": "SBS1",
  "description": "Clock-like signature associated with spontaneous deamination of 5-methylcytosine."
}
```

--------------------------------

### Save and Reload Analysis with save_cesa / load_cesa

Source: https://context7.com/townsend-lab-yale/cancereffectsizer/llms.txt

Provides functions to save a CESAnalysis object to disk and reload it later, preserving all analysis data and results. Note that the reference data (refset) must be installed when reloading.

```r
# Save analysis
save_cesa(cesa, file = "my_analysis.rds")

# Reload analysis
cesa <- load_cesa("my_analysis.rds")
```

--------------------------------

### Initialize Tutorial Directory

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/cancereffectsizeR.html

Creates and sets a dedicated working directory to organize tutorial data and output files.

```R
dir.create("CES_tutorial")
setwd("CES_tutorial")
```

--------------------------------

### Initialize environment and load reference data

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/create_custom_covariates.html

Sets up the necessary R libraries and retrieves gene identifiers and genomic intervals from a reference set for covariate processing.

```R
library(data.table)
library(rtracklayer)
library(GenomicRanges)
library(ces.refset.hg19)

# Get gene names and gene IDs; remove version number suffixes for short IDs
refset_genes = rbindlist(lapply(ces.refset.hg19$RefCDS, '[', c("gene_id", "gene_name")))
refset_genes[, short_gene_id := gsub('\\..*', '', gene_id)]
setkey(refset_genes, "short_gene_id")

# Get genomic intervals for each gene
gene_gr = ces.refset.hg19$gr_genes
```

--------------------------------

### POST /CESAnalysis

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/index.html

Initializes a new cancereffectsizeR analysis project to manage data and calculations.

```APIDOC
## POST /CESAnalysis

### Description
Creates a new CESAnalysis object to serve as the container for all subsequent analysis steps, including data loading and effect size calculations.

### Method
POST

### Endpoint
/CESAnalysis

### Parameters
#### Request Body
- **genome** (string) - Required - The genome build to be used (e.g., "hg19", "hg38").
- **sample_data** (data.frame) - Optional - Initial sample-level metadata.

### Request Example
{
  "genome": "hg38"
}

### Response
#### Success Response (200)
- **object** (CESAnalysis) - A new analysis object instance.

#### Response Example
{
  "status": "success",
  "cesa_id": "analysis_001"
}
```

--------------------------------

### GET /epistasis/variant

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/index.html

Calculates variant-level pairwise epistasis.

```APIDOC
## GET /ces_gene_epistasis

### Description
Calculates variant-level pairwise epistasis for specified variants.

### Method
GET

### Endpoint
/ces_gene_epistasis

### Parameters
#### Query Parameters
- **cesa** (CESAnalysis) - Required - The CESAnalysis object containing the data.
- **variants** (data.frame) - Required - A table of variants to analyze.

### Response
#### Success Response (200)
- **results** (data.frame) - The calculated epistatic effects.
```

--------------------------------

### Initialize CESAnalysis and Load MAF Data

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/cancereffectsizeR.html

Creates a new CESAnalysis object using a specified reference set and imports MAF data. The maf_name parameter is used to label the dataset, and users can specify covered_regions or coverage type for accuracy.

```R
cesa <- CESAnalysis(refset = "ces.refset.hg38")
cesa <- load_maf(cesa = cesa, maf = tcga_maf, maf_name = "BRCA")
```

--------------------------------

### GET /plot/prevalence

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/plot_effects.html

Configures the visualization of variant prevalence and confidence intervals for genomic mutation data.

```APIDOC
## GET /plot/prevalence

### Description
Generates a ggplot visualization representing variant prevalence. Users can toggle between raw mutation counts, percentages, or both, and include confidence intervals.

### Method
GET

### Endpoint
/plot/prevalence

### Parameters
#### Query Parameters
- **value** (string) - Optional - The metric to display: 'count' (default), 'percent', or 'both'.
- **show_ci** (boolean) - Optional - Whether to depict confidence intervals in the plot (default: TRUE).

### Request Example
{
  "value": "percent",
  "show_ci": true
}

### Response
#### Success Response (200)
- **plot** (ggplot) - A ggplot object representing the requested variant prevalence data.

#### Response Example
{
  "status": "success",
  "data": "[ggplot_object]"
}
```

--------------------------------

### CESAnalysis - Create a cancereffectsizeR analysis

Source: https://context7.com/townsend-lab-yale/cancereffectsizer/llms.txt

Initializes a CESAnalysis object, which serves as the central data structure for all subsequent cancereffectsizeR workflows.

```APIDOC
## CESAnalysis(refset)

### Description
Creates a new CESAnalysis object using a specified genome reference set.

### Method
Constructor

### Parameters
#### Path Parameters
- **refset** (string) - Required - The reference data set to use (e.g., "ces.refset.hg38", "ces.refset.hg19").

### Request Example
cesa <- CESAnalysis(refset = "ces.refset.hg38")

### Response
- **cesa** (CESAnalysis object) - An initialized analysis object.
```

--------------------------------

### GET get_gr_from_table

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/get_gr_from_table.html

Converts a variant table into a GRanges object using 1-based, closed coordinates.

```APIDOC
## get_gr_from_table

### Description
Converts a data.table containing variant information (chr, start, end) into a GRanges object. This function is primarily designed to handle output from select_variants().

### Method
Function Call (R)

### Parameters
#### Arguments
- **variant_table** (data.table) - Required - A table containing variant coordinates, assumed to be 1-based and closed.

### Request Example
get_gr_from_table(variant_table = my_variant_data)

### Response
#### Success Response
- **GRanges** (object) - A GRanges object representing the genomic ranges of the input variants.
```

--------------------------------

### GET get_PathScore_coding_regions

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/get_PathScore_coding_regions.html

Retrieves GRanges objects representing the coding sequence definitions used for PathScore calculations.

```APIDOC
## GET get_PathScore_coding_regions

### Description
Returns GRanges that represent the coding sequence (CDS) definitions used by PathScore. The hg19 version is derived from hg38 intervals using liftOver.

### Method
GET (Function Call)

### Endpoint
get_PathScore_coding_regions(genome)

### Parameters
#### Query Parameters
- **genome** (string) - Optional - Genome build to use. Options are "hg38" (default) or "hg19".

### Request Example
get_PathScore_coding_regions(genome = "hg38")

### Response
#### Success Response (200)
- **GRanges** (object) - A GenomicRanges object containing the coding sequence intervals.

#### Response Example
GRanges object with 230456 ranges and 0 metadata columns
```

--------------------------------

### samples_with Function

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/samples_with.html

A convenience function to identify samples with specific variants.

```APIDOC
## samples_with

### Description
A convenience function to identify samples with specific variants.

### Method
N/A (R function)

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **cesa** (CESAnalysis) - Required - The input CESAnalysis object.
- **any_of** (character vector, optional) - Select samples with ANY of the given variant names/IDs, such as c("8:142506482_C>G", "KRAS G12C"). When a gene has multiple transcripts in reference data, you may wish to use full IDs, such as "KRAS_G12C_ENSP00000256078".

### Request Example
N/A (R function)

### Response
N/A (R function - returns a subset of the CESAnalysis object or sample identifiers)
```

--------------------------------

### Initialize CESAnalysis Object

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/CESAnalysis.html

Initializes a new CESAnalysis object which serves as the central data structure for the analysis. The function requires a reference dataset (refset) to be specified, which can be a pre-built set or a custom directory path.

```R
library(cancereffectsizeR)
# Initialize with a standard refset
ces <- CESAnalysis(refset = "pcawg")

# Or initialize with a path to custom reference data
# ces <- CESAnalysis(refset = "/path/to/custom/refset")
```

--------------------------------

### GET /get_ref_data

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/get_ref_data.html

Retrieves the requested reference data for the reference set associated with a CESAnalysis object or directory.

```APIDOC
## GET get_ref_data

### Description
Reads in the requested reference data for the reference set associated with the CESAnalysis object or a provided directory.

### Method
GET

### Endpoint
get_ref_data(data_dir_or_cesa, datatype)

### Parameters
#### Path Parameters
- **data_dir_or_cesa** (object/string) - Required - A CESAnalysis object or the path to a directory containing reference data.
- **datatype** (string) - Required - The specific type of reference data to retrieve.

### Request Example
get_ref_data(cesa, "signature_data")

### Response
#### Success Response (200)
- **data** (object) - The requested reference data object.

#### Response Example
{
  "status": "success",
  "data": "[Reference Data Object]"
}
```

--------------------------------

### GET /aac_to_snv_ids

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/aac_to_snv_ids.html

Retrieves the list of SNVs that can cause a specific amino acid substitution for a given transcript.

```APIDOC
## GET /aac_to_snv_ids

### Description
An internal function to identify the SNVs that can cause a given amino acid substitution in a transcript.

### Method
GET

### Endpoint
/aac_to_snv_ids

### Parameters
#### Query Parameters
- **refcds_entry_name** (string) - Required - The name of the RefCDS entry for the relevant transcript.
- **aa_pos** (integer) - Required - The position of the substitution on the transcript.
- **aa_alt** (string) - Required - The identity of the substitution, either a three-letter code (e.g., "Lys") or "STOP".
- **bsg** (object) - Required - A BSgenome object for the genome build associated with the RefCDS entry.
- **refcds** (object) - Required - The RefCDS data structure.

### Request Example
{
  "refcds_entry_name": "ENST00000269305",
  "aa_pos": 123,
  "aa_alt": "Lys"
}

### Response
#### Success Response (200)
- **snv_ids** (array) - A list of SNV identifiers that result in the specified amino acid change.

#### Response Example
{
  "snv_ids": ["chr1:123456:A>G", "chr1:123456:A>T"]
}
```

--------------------------------

### Retrieve Sample Metadata using get_sample_info

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/get_sample_info.html

This function retrieves a data.table containing information about all samples stored within a CESAnalysis object. It requires a valid CESAnalysis object as input and returns a structured table of sample metadata.

```R
get_sample_info(cesa = NULL)
```

--------------------------------

### lift_bed - Convert BED intervals between genome builds

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/lift_bed.html

Converts BED intervals from one genome build to another using a specified chain file. It takes a BED file or GRanges object and a chain file as input, and optionally saves the lifted intervals to an output file.

```APIDOC
## lift_bed

### Description
Converts BED intervals between genome builds using liftOver.

### Method
N/A (This is an R function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Arguments
- **bed** (Pathname or GRanges) - Required - Pathname of a BED file, or a GRanges object.
- **chain** (UCSC-style chain file or Chain object) - Required - A UCSC-style chain file, or a Chain object.
- **outfile** (character or NULL) - Optional - If not NULL, the returned GRanges will be saved to the specified path.

### Request Example
```R
# Assuming you have a BED file 'input.bed' and a chain file 'hg19ToHg38.over.chain'
# library(rtracklayer)
# bed_data <- import.bed('input.bed')
# chain_data <- import.chain('hg19ToHg38.over.chain')
# lifted_granges <- lift_bed(bed = bed_data, chain = chain_data, outfile = 'output.bed')
```

### Response
#### Success Response
- **GRanges** - GRanges representing lifted intervals from input `bed`.

#### Response Example
```R
# Example GRanges object output
# GRangesList of length 1
#   Ranges: start end strand
#   [1] 100   200   *
#   ... (other intervals)
```

### Details
A warning is issued if the lifted intervals are less than 95% of the size of the original intervals. This utility is useful when working with genomic data from different reference assemblies.
```

--------------------------------

### GET get_dndscv_model_fit

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/get_dndscv_model_fit.html

Retrieves the dndscv model fit object, primarily used as an internal utility for gene mutation rate calculations.

```APIDOC
## GET get_dndscv_model_fit

### Description
This function extracts the model fit information from the dndscv output object. It is primarily used internally by gene_mutation_rates() and is exposed for testing and validation purposes.

### Method
GET

### Endpoint
get_dndscv_model_fit(dndscv_output)

### Parameters
#### Path Parameters
- **dndscv_output** (object) - Required - The output object generated by the dndscv package.

### Request Example
get_dndscv_model_fit(dndscv_results)

### Response
#### Success Response (200)
- **model_fit** (list) - The extracted model fit parameters and statistics from the dndscv output.

#### Response Example
{
  "model_fit": {
    "sel_cv": "...",
    "annotmuts": "..."
  }
}
```

--------------------------------

### List available signature sets

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/list_ces_signature_sets.html

This function prints the names of all mutational signature sets available for use in cancereffectsizeR. It requires no arguments and returns the names of the signature sets directly to the console.

```R
list_ces_signature_sets()
```

--------------------------------

### Get Epistatic Effect Schematic

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/epistasis_plot_schematic.html

Retrieves the explanatory schematic used in epistatic effect plots. This can be useful for incorporating the schematic into custom figures.

```APIDOC
## epistasis_plot_schematic

### Description
Get a copy of the explanatory schematic that appears in epistatic effect plots. May be useful for putting the schematic in custom locations when assembling complex figures.

### Method
GET (Conceptual - this is an R function, not a direct HTTP endpoint)

### Endpoint
N/A (R function call)

### Parameters
#### Arguments
- **title** (character) - Optional - Schematic title text. Defaults to "Types of effects".
- **schematic_label_size** (numeric) - Optional - Text size of labels in the schematic (title gets size + 1). Defaults to 3.
- **with_border** (logical) - Optional - TRUE/FALSE on the appearance of a thin visible border around the schematic. Defaults to TRUE.

### Request Example
```R
epistasis_plot_schematic(
  title = "My Custom Title",
  schematic_label_size = 4,
  with_border = FALSE
)
```

### Response
#### Success Response
- **ggplot object** - The schematic as a ggplot object.
```

--------------------------------

### GET suggest_cosmic_signature_exclusions

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/suggest_cosmic_signature_exclusions.html

Retrieves a vector of COSMIC signatures recommended for exclusion when calculating trinucleotide mutation rates based on specific cancer types and treatment history.

```APIDOC
## GET suggest_cosmic_signature_exclusions

### Description
Provides a list of COSMIC v3+ mutational signatures that should be excluded for a given cancer type to improve the accuracy of trinucleotide mutation rate calculations.

### Method
GET

### Endpoint
suggest_cosmic_signature_exclusions(cancer_type, treatment_naive, quiet)

### Parameters
#### Query Parameters
- **cancer_type** (string) - Optional - The specific cancer type label for which to retrieve exclusions.
- **treatment_naive** (boolean) - Optional - Set to TRUE if samples were taken pre-treatment; FALSE or NULL otherwise.
- **quiet** (boolean) - Optional - Default FALSE. If TRUE, suppresses console explanations and advice.

### Request Example
suggest_cosmic_signature_exclusions(cancer_type = "Lung Adenocarcinoma", treatment_naive = TRUE)

### Response
#### Success Response (200)
- **vector** (array) - A vector of signature identifiers to be used in the signature_exclusions argument of trinuc_mutation_rates().

#### Response Example
["SBS1", "SBS5"]
```

--------------------------------

### load_sample_data

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/load_sample_data.html

Function to insert sample-level data into a CESAnalysis samples table.

```APIDOC
## FUNCTION load_sample_data

### Description
Inserts sample-level data into a CESAnalysis samples table. This function maps provided data to existing samples using a unique patient identifier.

### Method
Function Call (R)

### Endpoint
load_sample_data(cesa, sample_data)

### Parameters
#### Arguments
- **cesa** (CESAnalysis) - Required - The CESAnalysis object to update.
- **sample_data** (data.table/data.frame) - Required - A data structure containing a 'Unique_Patient_Identifier' column to match against the CESAnalysis samples table.

### Request Example
load_sample_data(cesa, my_sample_df)

### Response
#### Success Response
- **cesa** (CESAnalysis) - Returns the updated CESAnalysis object with the new sample data integrated.

#### Response Example
# Returns an updated CESAnalysis object
```

--------------------------------

### Get CES Signature Set

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/trinuc_mutation_rates.html

Retrieves a reference signature set for CES analysis, specifying the reference genome and COSMIC version. This is useful for users who need a standard signature set for their analysis.

```R
sig_set <- get_ces_signature_set("ces.refset.hg19", "COSMIC_v3.2")
```

--------------------------------

### Get Epistasis Results - R

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/epistasis_results.html

The epistasis_results function in R retrieves a list of data tables containing results from epistasis analyses. It takes a CESAnalysis object as input and returns the processed epistasis results.

```R
epistasis_results(cesa = NULL)
```

--------------------------------

### preload_ref_data

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/preload_ref_data.html

Loads reference data into an environment to optimize performance for CESAnalysis.

```APIDOC
## preload_ref_data

### Description
Loads reference data into an environment for quick access when creating or loading a CESAnalysis object.

### Method
Function Call

### Endpoint
preload_ref_data(data_dir)

### Parameters
#### Path Parameters
- **data_dir** (string) - Required - The directory path containing the reference data files.

### Request Example
preload_ref_data(data_dir = "/path/to/reference/data")

### Response
#### Success Response (NULL)
- **Returns** (environment) - Returns an environment containing the preloaded reference data.
```

--------------------------------

### Create Custom Reference Set using R

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/create_refset.html

The create_refset function generates and saves a directory of custom reference data compatible with cancereffectsizeR. It requires transcript information from build_RefCDS, species and genome build names, and the BSgenome package name. Optional arguments include exome interval definitions and padding, additional transcript data from GTF files, and the number of cores to utilize for processing.

```R
create_refset(
  output_dir,
  refcds_dndscv,
  refcds_anno = NULL,
  species_name,
  genome_build_name,
  BSgenome_name,
  supported_chr = c(1:22, "X", "Y"),
  default_exome = NULL,
  exome_interval_padding = 0,
  transcripts = NULL,
  cores = 1
)
```

--------------------------------

### Get Signature Weights

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/get_signature_weights.html

Retrieves a table of SNV signature attributions for each sample. By default, it returns estimated relative weights of biologically-associated signatures that sum to 1. The raw argument can be used to obtain the attributions as produced by the signature extraction tool.

```APIDOC
## GET /api/signature_weights

### Description
Retrieves a table of SNV signature attributions for each sample. By default, these are estimated relative weights of biologically-associated signatures (i.e., non-artifact signatures) that sum to 1.

### Method
GET

### Endpoint
/api/signature_weights

### Parameters
#### Query Parameters
- **cesa** (object) - Required - CESAnalysis object.
- **raw** (boolean) - Optional - Default FALSE. When TRUE, return raw signature attributions as found by the signature extraction tool. Format may vary by tool.
- **artifacts_zeroed** (any) - Deprecated.

### Response
#### Success Response (200)
- **signature_attributions** (dataTable) - A data.table of signature attributions for each sample.
```

--------------------------------

### POST /reference/refset

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/index.html

Creates a custom reference data set for genome or tissue-specific analysis.

```APIDOC
## POST /create_refset

### Description
Builds a custom reference data set for use in cancereffectsizeR analyses.

### Method
POST

### Endpoint
/create_refset

### Parameters
#### Request Body
- **genome** (string) - Required - The genome build version.
- **name** (string) - Required - The name for the new refset.

### Response
#### Success Response (200)
- **status** (string) - Confirmation of refset creation.
```

--------------------------------

### Understanding SNV Counts and Attributions

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/trinuc_mutation_rates.html

Explains the `snv_counts` matrix and `raw_attributions` table generated by CESAnalysis, and their relationship with MutationalPatterns.

```APIDOC
## SNV Counts and Attributions

### Description
The `snv_counts` matrix provides the counts of Single Nucleotide Variants (SNVs) within each trinucleotide context for all samples in a CESAnalysis. This matrix is generated by the `trinuc_snv_counts()` function and can be directly used with the MutationalPatterns package for further signature analysis. The `raw_attributions` table contains signature attributions as produced by MutationalPatterns or deconstructSigs.

### Key Components
*   **snv_counts**: A matrix detailing SNV counts per trinucleotide context for each sample.
*   **raw_attributions**: A table containing raw signature attributions from MutationalPatterns or deconstructSigs.

### Usage
These outputs are foundational for signature analysis, allowing for the direct application of established tools like MutationalPatterns or for custom extended analyses.
```

--------------------------------

### Get MAF data from TCGA cohort

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/get_TCGA_project_MAF.html

This function queries the Genomic Data Commons API to retrieve MAF data for a specified TCGA project and saves it to a file. It handles data from the latest release and can optionally exclude non-primary TCGA samples.

```APIDOC
## Get MAF data from TCGA cohort

### Description
This convenience function queries the Genomic Data Commons API to get MAF data generated with the Aliquot Ensemble Somatic Variant Merging and Masking workflow for the specified project, and writes an MAF file. The API always provides data from the latest data release. This function might work with non-TCGA MAF data hosted on GDC (e.g., TARGET and GENIE-MSK), but it hasn't been tested and users should proceed with caution.

### Method
`get_TCGA_project_MAF`

### Parameters
#### Arguments
- **project** (character) - TCGA project name (e.g., "TCGA-BRCA").
- **filename** (character) - Output filename where MAF data should be saved. Must end in '.maf' (plaintext) or '.maf.gz' (gzip compressed).
- **test_run** (logical) - Default FALSE. When TRUE, gets MAF data for a few samples instead of the whole cohort.
- **exclude_TCGA_nonprimary** (logical) - Default TRUE. For TCGA projects, exclude samples not associated with a patient's initial primary tumor. (In many TCGA projects, a small handful of patients have metastatic, recurrent, or additional primary samples.)

### Details
TCGA cohort MAFs will be structured as downloaded, with a Unique_Patient_Identifier column generated from the first 12 characters of Tumor_Sample_Barcode. When passed to preload_maf() or load_maf(), this column will supersede Tumor_Sample_Barcode. In the handful of patients with multiple Tumor_Sample_Barcodes (essentially replicated sequencing, with very high variant overlap), these functions will effectively take the union of these samples for each patient. Relatedly, the small number of TCGA non-primary tumor samples should not be handled this way (and such samples are by default removed by this function).

Temporary aliquot MAF files downloaded by this function are deleted after they are read.

### Request Example
```R
# Get MAF data for the BRCA project and save it to a gzipped file
get_TCGA_project_MAF(project = "TCGA-BRCA", filename = "TCGA-BRCA.maf.gz")

# Get MAF data for a few samples for testing purposes
get_TCGA_project_MAF(project = "TCGA-LUAD", filename = "TCGA-LUAD_test.maf", test_run = TRUE)
```

### Response
This function does not return a value directly but saves the MAF data to the specified file. The MAF file will contain somatic variant information for the requested TCGA cohort.

#### Success Response (File Output)
- **MAF File** (file) - A MAF file (plain text or gzipped) containing somatic variant data.

#### Response Example (File Content - Snippet)
```
# Example MAF file header and a few lines of data
# ... (MAF header lines) ...
# Hugo_Symbol	Entrez_Gene_Id	... (other MAF columns) ...
# TP53	7157	...
# PIK3CA	5290	...
```
```

--------------------------------

### Define Compound Variants and Run Epistasis Analysis (R)

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/cancereffectsizeR.html

This R code snippet demonstrates how to define a compound variant set containing PIK3CA mutations and AKT1 E17K, and then perform epistasis analysis using `ces_epistasis`. It first collects relevant variants into a table, defines the compound variant set using `define_compound_variants`, and finally runs the epistasis test, outputting the results.

```R
# Collect all the variants that we want in the CompoundVariantSet into a table
top_PIK3CA <- cesa$variants[gene == "PIK3CA" & maf_prevalence > 1]
top_akt1 <- cesa$variants[variant_name == "AKT1 E17K"]
for_compound <- rbind(top_PIK3CA, top_akt1)

# see define_compound_variants() documentation for details on arguments
comp <- define_compound_variants(cesa = cesa, variant_table = for_compound, by = "gene", merge_distance = Inf)
cesa <- ces_epistasis(cesa = cesa, variants = comp, run_name = "AKT1_E17K_vs_PIK3CA")
cesa$epistasis$AKT1_E17K_vs_PIK3CA
```

--------------------------------

### Create GRanges from Table - R

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/get_gr_from_table.html

Converts a data.table with chromosome, start, and end columns into a GRanges object. This function is optimized for MAF-like coordinates (1-based, closed) and is particularly useful for processing variant data, especially when working with the output of select_variants(). It centers the nucleotide positions for accurate representation.

```R
get_gr_from_table(variant_table)
```

--------------------------------

### Consolidate TCGA Tumors by Patient in R

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/consolidate_tcga_tumors_by_patient.html

This function reads TCGA Tumor Sample Barcodes and consolidates them into patient-specific identifiers. Patients with multiple distinct tumors will share a single identifier. Sample barcodes not starting with 'TCGA' are kept unaltered. It accepts a vector of tumor sample barcodes, an optional number of characters to keep for non-TCGA samples, and boolean flags for summary statistics and figure generation.

```R
consolidate_tcga_tumors_by_patient(
  tumor_sample_barcodes,
  non_TCGA_characters_to_keep = "all",
  sum_stats = TRUE,
  figures = FALSE
)
```

--------------------------------

### Apply Pandoc Styles to Pre Source Code (JavaScript)

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/doc/cosmic_cancer_type_note.html

This JavaScript code iterates through style sheets to find Pandoc-origin styles and applies them to 'pre.sourceCode' elements. It ensures consistent code block presentation across different browsers and print outputs.

```javascript
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try {
      var rules = sheets[i].cssRules;
    } catch (e) {
      continue;
    }
    for (var j = 0; j < rules.length; j++) {
      var rule = rules[j];
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") continue;
      var style = rule.style.cssText;
      if (rule.style.color === '' && rule.style.backgroundColor === '') continue;
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
```

--------------------------------

### Get SNVs for Amino Acid Change (R)

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/aac_to_snv_ids.html

This R function, `aac_to_snv_ids`, identifies the SNVs that can cause a specified amino acid substitution within a given transcript. It takes the transcript's entry name, the amino acid position and its alternative identity (e.g., 'Lys' or 'STOP'), a BSgenome object for the relevant genome build, and a RefCDS entry as input. The function is internal and used for variant effect analysis.

```R
aac_to_snv_ids <- function(refcds_entry_name, aa_pos, aa_alt, bsg, refcds) {
  # Internal function implementation would go here
  # This is a placeholder based on the documentation
  # Actual code is in R/add_variants.R
  return(invisible(NULL))
}
```

--------------------------------

### Cancer Effect Sizer Parameters

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/ces_gene_epistasis.html

Detailed explanations of the parameters and metrics provided by the Cancer Effect Sizer.

```APIDOC
## Cancer Effect Sizer Parameters

### Description
This section details the various statistical measures and counts generated by the Cancer Effect Sizer tool for analyzing epistatic interactions in cancer mutations.

### Parameters

#### p_B_change
- **Type**: P-value
- **Description**: P-value from a likelihood ratio test (LRT) indicating if selection for variant B significantly changes after acquiring variant A. It compares the full epistatic model's likelihood to a reduced model where ces_B0 and ces_B_on_A are equal.

#### p_epistasis
- **Type**: P-value
- **Description**: P-value from a likelihood ratio test assessing if the epistatic model better explains mutation data than a non-epistatic model (independent selection for each gene). This can indicate significant epistatic effects even if individual gene changes are not significant.

#### expected_nAB_epistasis
- **Type**: Number
- **Description**: The expected number of samples with mutations in both A and B, as predicted by the fitted epistatic model. This value is typically close to the actual count of AB samples (nAB).

#### expected_nAB_null
- **Type**: Number
- **Description**: The expected number of samples with mutations in both A and B, under a null model assuming no epistasis.

#### AB_epistatic_ratio
- **Type**: Float
- **Description**: The ratio `expected_nAB_epistasis / expected_nAB_null`. This metric helps gauge the impact of epistatic interactions on the co-occurrence of variants A and B, accounting for mutation rates.

#### nA0
- **Type**: Integer
- **Description**: Number of samples with mutations only in gene A.

#### nB0
- **Type**: Integer
- **Description**: Number of samples with mutations only in gene B.

#### nAB
- **Type**: Integer
- **Description**: Number of samples with mutations in both gene A and gene B.

#### n00
- **Type**: Integer
- **Description**: Number of samples with mutations in neither gene A nor gene B.

#### ces_A_null
- **Type**: Float
- **Description**: Cancer Effect Size of variant A when estimated independently, i.e., under a no-epistasis model.

#### ces_B_null
- **Type**: Float
- **Description**: Cancer Effect Size of variant B when estimated independently, i.e., under a no-epistasis model.

### Important Note
Only samples with complete coverage at all included sites in both genes are used for inference. Samples with incomplete coverage may have mutations at uncovered sites, affecting the analysis.
```

--------------------------------

### POST /preload_maf

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/preload_maf.html

Reads and validates MAF-formatted mutation data, supporting coordinate conversion and quality control annotations.

```APIDOC
## POST /preload_maf

### Description
Reads MAF-formatted data from a file or data table, performs quality checks, and optionally converts coordinates using a chain file.

### Method
POST

### Endpoint
/preload_maf

### Parameters
#### Request Body
- **maf** (string/table) - Required - Path to tab-delimited MAF file or data.table object.
- **refset** (string) - Required - Name of the reference data set to use.
- **chain_file** (string) - Optional - Path to a UCSC-style .chain file for genome build conversion.
- **sample_col** (string) - Optional - Column name for patient ID (defaults to Unique_Patient_Identifier).
- **chr_col** (string) - Optional - Column name for chromosome data.
- **start_col** (string) - Optional - Column name for start position.
- **ref_col** (string) - Optional - Column name for reference allele.
- **detect_hidden_mnv** (boolean) - Optional - Whether to detect and convert adjacent SNVs to MNVs.

### Request Example
{
  "maf": "path/to/data.maf",
  "refset": "ces.refset.hg38",
  "detect_hidden_mnv": true
}

### Response
#### Success Response (200)
- **data** (data.table) - Validated MAF data with quality-control annotations and flagged records.

#### Response Example
{
  "status": "success",
  "records_processed": 1500,
  "flags": []
}
```

--------------------------------

### Preload reference data for CESAnalysis

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/preload_ref_data.html

This function loads reference data from a specified directory into the current R environment. It is intended to be used when setting up a CESAnalysis to improve performance by pre-caching required genome data.

```R
preload_ref_data(data_dir = "path/to/reference/data")
```

--------------------------------

### Initialize CESAnalysis Object in R

Source: https://context7.com/townsend-lab-yale/cancereffectsizer/llms.txt

Creates a CESAnalysis object, the central data structure for cancereffectsizeR. It holds MAF data, mutation annotations, mutation rates, and selection results. The refset parameter specifies the genome reference data (e.g., ces.refset.hg19 or ces.refset.hg38).

```R
library(cancereffectsizeR)

# Install reference data if needed
# options(timeout = 600)
# remotes::install_github("Townsend-Lab-Yale/ces.refset.hg38@*release")

# Create a new CESAnalysis with hg38 reference data
cesa <- CESAnalysis(refset = "ces.refset.hg38")

# For hg19 data
cesa_hg19 <- CESAnalysis(refset = "ces.refset.hg19")

# List available reference data sets
list_ces_refsets()
```

--------------------------------

### Accessing Selection and Epistasis Results in R

Source: https://context7.com/townsend-lab-yale/cancereffectsizer/llms.txt

Demonstrates how to retrieve selection and epistasis results from a CESAnalysis object using dedicated functions. These functions are part of the cancereffectsizeR package for cancer genomics analysis.

```R
selection <- snv_results(cesa)
epistasis <- epistasis_results(cesa)
```

--------------------------------

### load_maf - Load MAF data into CESAnalysis

Source: https://context7.com/townsend-lab-yale/cancereffectsizer/llms.txt

Integrates validated MAF data into an existing CESAnalysis object, including coverage definitions.

```APIDOC
## load_maf(cesa, maf, coverage, ...)

### Description
Loads mutation data into the CESAnalysis object and annotates variants.

### Method
Function

### Parameters
#### Path Parameters
- **cesa** (CESAnalysis) - Required - The analysis object.
- **maf** (data.frame) - Required - Validated MAF data.
- **coverage** (string) - Required - Sequencing type: "exome", "genome", or "targeted".

### Request Example
cesa <- load_maf(cesa = cesa, maf = maf_data, coverage = "exome")

### Response
- **cesa** (CESAnalysis) - Updated analysis object containing loaded data.
```

--------------------------------

### Usage of run_dndscv function

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/run_dndscv.html

This snippet demonstrates the function signature for running the internal dNdScv process. It requires mutation data, a gene list, covariates, a reference database, and gene genomic ranges.

```R
run_dndscv(mutations, gene_list, cv, refdb, gr_genes, ...)
```

--------------------------------

### Load sample data into CESAnalysis

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/load_sample_data.html

This function updates a CESAnalysis object by adding sample-level metadata. The input sample_data must be a data.table or data.frame with a Unique_Patient_Identifier column that matches the existing samples in the CESAnalysis object.

```R
load_sample_data(cesa, sample_data)
```

--------------------------------

### Build RefCDS Object

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/build_RefCDS.html

Initializes the build_RefCDS function to generate reference data from a GTF file and a specified genome assembly. It supports parallel processing and configuration of transcript selection and chromosome naming styles.

```R
build_RefCDS(
  gtf,
  genome,
  use_all_transcripts = TRUE,
  cds_ranges_lack_stop_codons = TRUE,
  cores = 1,
  additional_essential_splice_pos = NULL,
  numcode = 1,
  chromosome_style = "NCBI"
)
```

--------------------------------

### Generate PathScore Input File from MAF

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/make_PathScore_input.html

The make_PathScore_input function processes an MAF-like data.table into a tab-delimited format suitable for the PathScore web tool. It supports hg38 and hg19 genome builds and preserves existing annotation columns.

```R
make_PathScore_input(maf, file = NULL, genome = "hg38")
```

--------------------------------

### Run PCA and Save Covariates Object in R

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/create_custom_covariates.html

This code snippet prepares the combined gene data for Principal Component Analysis (PCA) by converting it to a matrix and then runs the prcomp function. It specifies the number of principal components and data scaling, and finally saves the resulting PCA object to an RDS file. The output can be used directly by cancereffectsizeR.

```R
# To format for prcomp, convert to a data-only matrix and transpose
final_gene_names = covariates_input$gene_name
covariates_input = t(as.matrix(covariates_input[, -c("gene_name", "short_gene_id")]))
colnames(covariates_input) = final_gene_names

# Run prcomp (with specification of 20 principal components and data scaling)
covariates_output = prcomp(covariates_input, rank. = 20, scale. = T)

# Save it!
saveRDS(covariates_output, "lung.rds")
```

--------------------------------

### Convert VCF files to MAF-like table

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/vcfs_to_maf_table.html

This function takes a vector of VCF file paths and corresponding sample IDs to generate a consolidated data.table. It standardizes POS/REF/ALT fields to match MAF format requirements for downstream processing.

```R
vcfs_to_maf_table(vcfs = c("path/to/sample1.vcf", "path/to/sample2.vcf"), sample_ids = c("sample1", "sample2"))
```

--------------------------------

### Select Samples from CESAnalysis Table (R)

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/select_samples.html

The `select_samples` function retrieves a validated subset of the CESAnalysis samples table. It takes a CESAnalysis object and an optional vector of sample identifiers or a data.table. If no samples are provided, it returns the full sample table. The function is written in R and is part of the cancereffectsR package.

```R
select_samples(cesa = NULL, samples = character())
```

--------------------------------

### Convert signature weights for MutationalPatterns

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/convert_signature_weights_for_mp.html

This function takes a signature weight table, typically accessed from a CESAnalysis object via mutational_signatures, and reformats it into a contributions matrix. The output is specifically designed to be compatible with MutationalPatterns functions.

```R
convert_signature_weights_for_mp(signature_weight_table)
```

--------------------------------

### Load Clinical Sample Data

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/articles/cancereffectsizeR.html

Imports clinical metadata associated with the samples into the existing CESAnalysis object.

```R
cesa <- load_sample_data(cesa, tcga_clinical)
```

--------------------------------

### pairwise_epistasis_lik

Source: https://github.com/townsend-lab-yale/cancereffectsizer/blob/main/docs/reference/pairwise_epistasis_lik.html

Creates a likelihood function for a model of pairwise epistasis with a 'strong mutation, weak selection' assumption for a pair of variants.

```APIDOC
## pairwise_epistasis_lik

### Description
For a pair of variants (or two groups of variants), creates a likelihood function for a model of pairwise epistasis with a "strong mutation, weak selection" assumption.

### Usage

```r
pairwise_epistasis_lik(with_just_1, with_just_2, with_both, with_neither)
```

### Arguments

#### Path Parameters

*   **with_just_1** (list) - two-item list of baseline rates in v1/v2 for tumors with mutation in just the first variant(s)
*   **with_just_2** (list) - two-item list of baseline rates in v1/v2 for tumors with mutation in just the second variant(s)
*   **with_both** (list) - two-item list of baseline rates in v1/v2 for tumors with mutation in both
*   **with_neither** (list) - two-item list of baseline rates in v1/v2 for tumors with mutation n neither

### Value

A likelihood function

### Details

The arguments to this function are automatically supplied by `[ces_epistasis()](ces_epistasis.html)` and `[ces_gene_epistasis()](ces_gene_epistasis.html)`.
```