cancereffectsizeR

https://townsend-lab-yale.github.io/cancereffectsizeR
Admin
cancereffectsizeR is an R package that quantifies somatic evolution in cancer by analyzing variant...
Tokens:39,808
Snippets:338
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install cancereffectsizeR and Dependencies

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Installs the cancereffectsizeR package and its dependencies from GitHub. Increases the download timeout limit to accommodate large dependencies.

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

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

### Example: Create CompoundVariantSet

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/CompoundVariantSet.html

Demonstrates creating a CompoundVariantSet with a named list of variant IDs.

```R
CompoundVariantSet(cesa, variant_id = list(kras12 = c("KRAS G12C", "KRAS G12D", "KRAS G12V")))
```

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

### Install Refset Data Package

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Installs the hg38 reference data package for cancereffectsizeR. This package contains genomic and gene annotations, and mutational signature definitions.

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

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

### Get Sample Info

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_sample_info.html

Retrieves a data.table containing information on all samples within a CESAnalysis object.

```APIDOC
## Get Sample Info

### Description
Returns a data.table with info on all samples in the CESAnalysis.

### Method
GET (conceptual, as this is an R function)

### Endpoint
N/A (R function)

### Parameters
#### Arguments 
- **cesa** (CESAnalysis object) - Optional - The CESAnalysis object to retrieve sample information from.
```

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

### Get Sample Information

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_sample_info.html

Retrieves a data.table containing information on all samples within a CESAnalysis object. Requires the CESAnalysis object as input.

```r
get_sample_info(cesa = NULL)
```

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

### Suggest COSMIC Signature Exclusions for Cancer Type

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cosmic_cancer_type_note.html

Use this function to get a list of suggested signatures to exclude for a given cancer type. Set `treatment_naive = TRUE` if your samples are treatment-naive.

```R
suggest_cosmic_signature_exclusions(cancer_type = "BRCA", treatment_naive = TRUE)
```

```R
suggest_cosmic_signature_exclusions(cancer_type = "Kidney-RCC")
```

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

### GET /get_signature_weights

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_signature_weights.html

Retrieves the table of signature attributions for samples associated with a CESAnalysis object.

```APIDOC
## GET get_signature_weights

### Description
View SNV signature attributions associated with CESAnalysis samples.

### Method
Function Call (R)

### Parameters
#### Arguments
- **cesa** (CESAnalysis object) - Required - The CESAnalysis object containing the sample data.
- **raw** (logical) - Optional - Default FALSE. When TRUE, returns raw signature attributions as found by the signature extraction tool.
- **artifacts_zeroed** (any) - Optional - Deprecated.

### Value
A data.table of signature attributions for each sample. By default, these are estimated relative weights of biologically-associated signatures that sum to 1.

### Details
Use raw = TRUE to get signature attributions as produced by the signature extraction tool, without adjustments made by cancereffectsizeR's trinuc_mutation_rates().
```

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

### Get MutationalPatterns contributions matrix

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/convert_signature_weights_for_mp.html

Reformat a signature weights table from mutational signature analysis into the contributions matrix required for MutationalPatterns functions, including visualizations.

```APIDOC
## convert_signature_weights_for_mp

### Description
Reformat a signature weights table from mutational signature analysis into the contributions matrix required for MutationalPatterns functions, including visualizations.

### Usage
```R
convert_signature_weights_for_mp(signature_weight_table)
```

### Arguments
#### Path Parameters
* **signature_weight_table** (data.frame) - Required - As created by trinuc_mutation_rates(); typically accessed via (CESAnalysis)$mutational_signatures.
```

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

### GET cosmic_signature_info

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/cosmic_signature_info.html

Retrieves a table containing descriptions and metadata for COSMIC signatures ranging from v3.0 to v3.4.

```APIDOC
## GET cosmic_signature_info

### Description
Returns a table describing COSMIC signatures. All signatures from v3.0 to the latest release (v3.4) are included, with information derived from the most recent information on the COSMIC website.

### Method
GET

### Endpoint
cosmic_signature_info()

### Response
#### Success Response (200)
- **data** (table) - A table containing COSMIC signature descriptions and associated metadata.
```

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

### Visualize variant effects

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Plots the effects of selected variants. The second example groups results by gene and limits the display to the top 10.

```R
plot_effects(effects = cesa$selection$recurrents)
```

```R
plot_effects(cesa$selection$recurrents,
  group_by = "gene", topn = 10,
  label_individual_variants = FALSE
)
```

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

### Suggest COSMIC Signature Exclusions

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/suggest_cosmic_signature_exclusions.html

Use this function to get suggestions for signatures to exclude when analyzing trinucleotide mutation rates with COSMIC signatures v3 and later. Set `quiet = TRUE` for non-interactive use.

```R
suggest_cosmic_signature_exclusions(
  cancer_type = NULL,
  treatment_naive = NULL,
  quiet = FALSE
)
```

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

### Get COSMIC Signature Descriptions

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/cosmic_signature_info.html

Retrieves a table detailing COSMIC signatures from v3.0 to the latest release (v3.4). Information is sourced from the COSMIC website. Note: An association between SBS16 and alcohol consumption is mentioned but not present on the COSMIC website.

```r
cosmic_signature_info()
```

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

### Quickstart: TCGA LUAD Data Analysis

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Performs a complete cancereffectsizeR analysis on TCGA lung adenocarcinoma data, including data loading, mutation rate inference, and selection coefficient estimation.

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

# Download TCGA lung adenocarcinoma (LUAD) somatic variant data.
tcga_maf_file <- "TCGA-LUAD.maf.gz"
if (!file.exists(tcga_maf_file)) {
  get_TCGA_project_MAF(project = "LUAD", filename = "TCGA-LUAD.maf.gz")
}

# Prepare data
maf <- preload_maf(maf = tcga_maf_file, refset = "ces.refset.hg38")

# Create cancereffectsizeR analysis and load data
cesa <- CESAnalysis(refset = "ces.refset.hg38")
cesa <- load_maf(cesa = cesa, maf = maf)

# Infer trinculeotide-context-specific relative rates of SNV mutation from
# a mutational signature analysis (leaving out signatures not found in LUAD)
signature_exclusions <- suggest_cosmic_signature_exclusions(cancer_type = "LUAD", treatment_naive = TRUE)
cesa <- trinuc_mutation_rates(
  cesa = cesa, signature_set = ces.refset.hg38$signatures$COSMIC_v3.4,
  signature_exclusions = signature_exclusions
)

# Estimate neutral gene mutation rates using dNdScv, with tissue-specific mutation rate covariates.
cesa <- gene_mutation_rates(cesa, covariates = ces.refset.hg38$covariates$lung)

# Infer scaled selection coefficients under the default model of clonal selection.
# By default, inference is restricted to recurrent mutations.
cesa <- ces_variant(cesa, run_name = "example")

# Visualize top-effect variants.
plot_effects(effects = cesa$selection$example, color_by = "#DB382D", topn = 20)
```

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

### Set Up Working Directory

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Creates and sets a working directory for the tutorial to store data and output files.

```R
# setwd() somewhere, if desired
dir.create("CES_tutorial")
setwd("CES_tutorial")
```

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

### Load cancereffectsizeR and data.table

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Initialize the environment by loading the required packages.

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

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

### Load required packages for covariates generation

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/create_custom_covariates.html

Initializes the environment by loading necessary data manipulation and genomic analysis libraries.

```R
library(data.table)
library(rtracklayer)
library(GenomicRanges)

# Load refset data package, if not using a custom refset directory
library(ces.refset.hg19)
```

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

### GET get_gene_rates

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_gene_rates.html

Retrieves a table of neutral gene mutation rates from a CESAnalysis object.

```APIDOC
## get_gene_rates

### Description
Get table of neutral gene mutation rates from a CESAnalysis object.

### Usage
get_gene_rates(cesa = NULL)

### Parameters
#### Arguments
- **cesa** (CESAnalysis object) - Required - The CESAnalysis object containing the data.
```

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

### GET epistasis_plot_schematic

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/epistasis_plot_schematic.html

Retrieves an explanatory schematic for epistatic effect plots as a ggplot object.

```APIDOC
## GET epistasis_plot_schematic

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

### Method
GET

### Endpoint
epistasis_plot_schematic()

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

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

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

### Create a custom refset in R

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/create_refset.html

Use this function to initialize and save a directory of custom reference data. Requires output from build_RefCDS() to function correctly.

```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
)
```

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

### Create a CESAnalysis object

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/CESAnalysis.html

Initializes a new CESAnalysis object using a specified reference dataset or custom directory.

```APIDOC
## CESAnalysis(refset = NULL)

### Description
Creates a CESAnalysis, the central data structure of cancereffectsizeR.

### Arguments
- **refset** (string) - Optional - Name of reference data set (refset) to use; run `list_ces_refsets()` for available refsets. Alternatively, the path to a custom reference data directory.

### Value
CESAnalysis object
```

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

### Sample Data Management

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/index.html

Functions for loading and clearing sample-level data.

```APIDOC
## Load sample-level data

### Description
Functions to load and clear sample-level data.

### Functions
- `load_sample_data()`: Add sample data.
- `clear_sample_data()`: Clear sample data.
```

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

### GET snv_results

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/snv_results.html

Retrieves a list of ces_variant results tables with added variant annotations from a CESAnalysis object.

```APIDOC
## snv_results

### Description
Returns a list of ces_variant() results tables, with variant annotations added.

### Usage
snv_results(cesa = NULL)

### Parameters
#### Arguments
- **cesa** (CESAnalysis object) - Required - The CESAnalysis object containing the variant data.
```

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

### Get Estimated Relative Rates of Trinucleotide-Specific SNV Mutation

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_trinuc_rates.html

Retrieves the estimated relative rates of trinucleotide-specific SNV mutations.

```APIDOC
## GET /api/trinuc_rates

### Description
Get estimated relative rates of trinucleotide-specific SNV mutation.

### Method
GET

### Endpoint
/api/trinuc_rates

### Parameters
#### Query Parameters
- **cesa** (CESAnalysis) - Required - CESAnalysis object

### Response
#### Success Response (200)
- **trinuc_rates** (object) - Estimated relative rates of trinucleotide-specific SNV mutation.

#### Response Example
{
  "trinuc_rates": {
    "example": "response body"
  }
}
```

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

### Load Sample Data

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/load_sample_data.html

Inserts sample-level data into a CESAnalysis samples table.

```APIDOC
## Add sample data

### Description
Insert sample-level data into a CESAnalysis samples table.

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

### Arguments 

* **cesa** (CESAnalysis) - The CESAnalysis object to which sample data will be added.
* **sample_data** (data.table or data.frame) - A data.table or data.frame with a Unique_Patient_Identifier column to match the CESAnalysis samples table, with one row per sample. It's okay if some samples aren't present in the table.
```

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

### Initialize CESAnalysis Object

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/CESAnalysis.html

Use this function to create the main data structure for cancereffectsizeR analyses. You can specify a reference dataset by name or provide a path to a custom directory.

```R
CESAnalysis(refset = NULL)
```

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

### Load MAF data into CESAnalysis

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Initialize CESAnalysis and load MAF data. Use maf_name for identification, especially when loading multiple MAFs. Variants outside refset exome definitions may be reported.

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

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

### Tissue-specific mutational signature exclusions

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/suggest_cosmic_signature_exclusions.html

Get suggestions on signatures_to_remove for trinuc_mutation_rates for COSMIC signatures v3 and later. For details, see this article on our website.

```APIDOC
## suggest_cosmic_signature_exclusions

### Description
Get suggestions on signatures_to_remove for trinuc_mutation_rates for COSMIC signatures v3 and later.

### Method
`suggest_cosmic_signature_exclusions()`

### Arguments 
#### Path Parameters
- **cancer_type** (character) - Optional - See here for supported cancer type labels.
- **treatment_naive** (logical) - Optional - give TRUE if samples were taken pre-treatment; FALSE or leave NULL otherwise.
- **quiet** (logical) - Optional - (default false) for non-interactive use, suppress explanations and advice.

### Value
a vector of signatures to feed to the `trinuc_mutation_rates()` `signature_exclusions` argument.
```

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

### Project Management

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/index.html

Functions for creating, loading, and saving cancereffectsizeR analysis projects.

```APIDOC
## Create and manage projects

### Description
Create, load, and save projects

### Functions
- `CESAnalysis()`: Create a cancereffectsizeR analysis.
- `load_cesa()`: Load a previously saved CESAnalysis.
- `save_cesa()`: Save a CESAnalysis in progress.
- `set_refset_dir()`: Set reference data directory.
```

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

### Get Trinucleotide Mutation Rates

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_trinuc_rates.html

Use this function to estimate the relative rates of trinucleotide-specific SNV mutations. It requires a CESAnalysis object as input.

```R
get_trinuc_rates(cesa = NULL)
```

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

### Initialize CompoundVariantSet

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/CompoundVariantSet.html

Defines the basic constructor signature for creating a CompoundVariantSet.

```R
CompoundVariantSet(cesa, variant_id)
```

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

### Get PathScore Coding Regions

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_PathScore_coding_regions.html

Retrieves GRanges representing coding sequence (CDS) definitions used by PathScore. Supports hg38 and hg19 genomes.

```r
get_PathScore_coding_regions(genome = "hg38")
```

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

### Get PathScore coding regions

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_PathScore_coding_regions.html

Retrieves GRanges representing the coding sequence (CDS) definitions used by PathScore. Includes support for hg38 and hg19 genomes.

```APIDOC
## Get PathScore coding regions

### Description
Returns GRanges that represent the coding sequence (CDS) definitions used by PathScore. The hg19 version was created by running liftOver on the hg38 intervals.

### Method
`get_PathScore_coding_regions`

### Arguments 
#### Path Parameters
- **genome** (string) - Optional - Genome build: Either "hg39" (default) or "hg19".

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

### Response
#### Success Response (200)
- **GRanges** - A GRanges object containing the coding regions.

#### Response Example
```R
# Example GRanges object structure (actual content will vary)
GRanges(seqnames = "chr1", ranges = IRanges(start = 1000, end = 2000), strand = "+")
```
```

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

### List Available Cancer Effect Size Signature Sets

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/list_ces_signature_sets.html

Prints the names of available mutational signature sets that are ready for use with cancereffectsizeR. These signature sets were not derived by the package.

```r
list_ces_signature_sets()
```

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

### Get Epistatic Effect Schematic in R

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/epistasis_plot_schematic.html

Retrieves the explanatory schematic used in epistatic effect plots. Useful for custom figure assembly. The schematic can be customized with a title, label size, and border.

```R
epistasis_plot_schematic(
  title = "Types of effects",
  schematic_label_size = 3,
  with_border = TRUE
)
```

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

### Convert BED intervals between genome builds

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/lift_bed.html

Utility to convert BED intervals between genome coordinate systems using liftOver. It uses only the chr/start/end fields of the input BED and ignores strand. The output GRanges will have no associated seqinfo.

```APIDOC
## Convert BED intervals between genome builds

### Description
Use this utility to convert BED intervals between genome coordinate systems using liftOver. Only the chr/start/end fields of the input BED are used (strand is ignored). The output GRanges will have no associated seqinfo.

### Usage
```R
lift_bed(bed, chain, outfile = NULL)
```

### Arguments
* **bed** (Pathname or GRanges) - Pathname of a BED file, or a GRanges (typically loaded from a BED file with `rtracklayer::import.bed()`).
* **chain** (UCSC-style chain file or Chain object) - A UCSC-style chain file, or a Chain object (such as from `rtracklayer::import.chain()`).
* **outfile** (NULL or Pathname) - If not NULL, the returned GRanges will be saved to the specified path using `rtracklayer::export.chain()`.

### Value
GRanges representing lifted intervals from input `bed`.

### Details
A warning is given if the lifted intervals are less than 95% of the size of the original intervals. When the BED input represents sequencing target intervals, most of the input intervals will usually lift successfully.
```

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

### list_ces_refsets

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/list_ces_refsets.html

Prints the names of all built-in reference data sets available in the package.

```APIDOC
## list_ces_refsets

### Description
Prints names of built-in reference data sets available for use in cancereffectsizeR.

### Usage
list_ces_refsets()
```

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

### Create a custom refset

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/create_refset.html

This function creates and saves a directory of custom reference data that can be used with cancereffectsizeR instead of supplied refsets like `ces.refset.hg19`. All arguments are required except default_exome/exome_interval_padding, which are recommended.

```APIDOC
## POST /create_refset

### Description
Use this function to create and save a directory of custom reference data that can be used with cancereffectsizeR instead of supplied refsets like `ces.refset.hg19`. All arguments are required except default_exome/exome_interval_padding, which are recommended.

### Method
POST

### Endpoint
/create_refset

### Parameters
#### Request Body
- **output_dir** (string) - Required - Name/path of an existing, writable output directory where all data will be saved. The name of this directory will serve as the name of the custom refset.
- **refcds_dndscv** (list) - Required - Transcript information in the two-item list (consisting of RefCDS and gr_genes) that is output by `build_RefCDS`. This transcript information will be used with dNdScv.
- **refcds_anno** (list) - Optional - Transcript information in the two-item list (consisting of RefCDS and gr_genes) that is output by `build_RefCDS`. This transcript information will be used for cancereffectsizeR's annotations. If unspecified, the same reference information as supplied for dNdScv will be used.
- **species_name** (string) - Required - Name of the species, primarily for display (e.g., "human").
- **genome_build_name** (string) - Required - Name of the genome build, primarily for display (e.g., "hg19").
- **BSgenome_name** (string) - Required - The name of the BSgenome package to use (e.g., "hg19"); will used by cancereffectsizeR to load the reference genome via BSgenome::getBSgenome().
- **supported_chr** (array of strings) - Required - Character vector of supported chromosomes. Note that cancereffectsizeR uses NCBI-style chromosome names, which means no chr prefixes ("X", not "chrX"). Mitochondrial contigs shouldn't be included since they would require special handling that hasn't been implemented.
- **default_exome** (string or GRanges object) - Optional - A BED file or GRanges object that defines coding regions in the genome as might be used by an exome capture kit. This file (or GRanges) might be acquired or generated from exome capture kit documentation, or alternatively, coding regions defined in a GTF file (or the granges output by build_RefCDS()).
- **exome_interval_padding** (integer) - Optional - Number of bases to pad start/end of each covered interval, to allow for some variants to be called just outside of targeted regions, where there still may be pretty good sequencing coverage.
- **transcripts** (data.table) - Optional - Additional information about coding (and, optionally, noncoding) transcripts from a Gencode GTF, supplied as a data.table. See the format provided in ces.refset.hg38. You'll have to match the format (including column names) pretty closely to get expected behavior. Noncoding transcripts are represented only by records with transcript_type = "transcript", and protein-coding transcripts are representing with transcript, CDS, and UTR records. Note that in Gencode format.
- **cores** (integer) - Optional - How many cores to use (default 1).

### Request Example
```json
{
  "output_dir": "/path/to/output",
  "refcds_dndscv": {
    "RefCDS": "...",
    "gr_genes": "..."
  },
  "species_name": "human",
  "genome_build_name": "hg19",
  "BSgenome_name": "hg19",
  "supported_chr": ["1", "2", "X"],
  "default_exome": "/path/to/exome.bed",
  "exome_interval_padding": 100,
  "transcripts": "...",
  "cores": 4
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful creation of the refset.

#### Response Example
```json
{
  "message": "Custom refset created successfully at /path/to/output"
}
```
```

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

### Get MAF Data from TCGA Project

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/get_TCGA_project_MAF.html

Use this function to query the Genomic Data Commons API for MAF data from a specified TCGA project. It saves the data to a MAF file. By default, it excludes non-primary tumor samples.

```r
get_TCGA_project_MAF(
  project = NULL,
  filename = NULL,
  test_run = FALSE,
  exclude_TCGA_nonprimary = TRUE
)
```

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

### Generate PathScore Input File from MAF Data

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/make_PathScore_input.html

Use this function to create a tab-delimited text file from MAF data for PathScore analysis. The MAF data should be in a data.table format. An optional annotation column named 'annot' will be preserved if present. Specify the genome build as 'hg38' or 'hg19'.

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

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

### Convert signature weights for MutationalPatterns

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/convert_signature_weights_for_mp.html

Use this function to prepare signature weight tables for use with MutationalPatterns visualization and analysis functions.

```R
convert_signature_weights_for_mp(signature_weight_table)
```

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

### Create Custom Reference Data

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/index.html

Functions for building custom reference data sets.

```APIDOC
## Create custom reference data

### Description
Build your own reference data set for almost any genome or tissue type.

### Functions
- `create_refset()`: Create a custom refset.
- `build_RefCDS()`: cancereffectsizeR's RefCDS builder.
- `validate_signature_set()`: validate_signature_set.
```

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

### Get MAF data from TCGA cohort

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/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 includes options to test the run with fewer samples and exclude non-primary tumor samples.

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

### Description
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 (Implicit, as it retrieves data from an API)

### Endpoint
`/` (This function interacts with the GDC API, not a specific endpoint within the R package itself)

### Parameters
#### Function 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.)

### Request Example
```R
get_TCGA_project_MAF(project = "TCGA-BRCA", filename = "BRCA_cohort.maf.gz", test_run = TRUE)
```

### Response
#### Success Response (File Output)
- MAF data saved to the specified `filename`.

#### Response Example
(Output is a file, not a direct JSON response. The content of the MAF file would be tab-separated values.)

### 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.
```

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

### Metadata and Rate Accessors

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/index.html

Functions to retrieve sample metadata and estimated mutation rates.

```APIDOC
## GET get_sample_info

### Description
View sample metadata.

### Method
GET

### Endpoint
/get_sample_info

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **sample_info** (DataFrame) - A table containing metadata for each sample.

#### Response Example
```json
{
  "sample_info": [
    {
      "Sample_ID": "Sample_01",
      "Tumor_Type": "Glioblastoma",
      "Age_at_Diagnosis": 55
    },
    {
      "Sample_ID": "Sample_02",
      "Tumor_Type": "Astrocytoma",
      "Age_at_Diagnosis": 42
    }
  ]
}
```

## GET get_trinuc_rates

### Description
Get estimated relative rates of trinucleotide-specific SNV mutation.

### Method
GET

### Endpoint
/get_trinuc_rates

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **trinuc_rates** (DataFrame) - A table of estimated trinucleotide mutation rates.

#### Response Example
```json
{
  "trinuc_rates": [
    {
      "context": "CGA",
      "rate": 0.00015
    },
    {
      "context": "TCT",
      "rate": 0.00012
    }
  ]
}
```

## GET get_gene_rates

### Description
Get table of neutral gene mutation rates.

### Method
GET

### Endpoint
/get_gene_rates

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **gene_rates** (DataFrame) - A table of neutral gene mutation rates.

#### Response Example
```json
{
  "gene_rates": [
    {
      "Gene": "TP53",
      "Mutation_Rate": 1.5e-06
    },
    {
      "Gene": "PTEN",
      "Mutation_Rate": 8.0e-07
    }
  ]
}
```
```

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

### Load and Prepare Clinical Data

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Load patient clinical information and align identifiers with the MAF data.

```R
tcga_clinical <- fread(system.file("tutorial/TCGA_BRCA_clinical.txt", package = "cancereffectsizeR"))

# Change patient identifier column name in clinical table to match the MAF.
setnames(tcga_clinical, "patient_id", "Unique_Patient_Identifier")

# Peek at data
tcga_clinical[1:5]
```

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

### List Available CES Signature Sets

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/list_ces_signature_sets.html

This function prints the names of all available mutational signature sets that are ready to be used with the cancereffectsizeR package. These signature sets were not derived by this package.

```APIDOC
## list_ces_signature_sets

### Description
Prints names of available mutational signature sets. These are ready to use with cancereffectsizeR. The package does not derive these signature sets.

### Method
Function Call

### Endpoint
N/A (R function)

### Parameters
None

### Request Example
```R
list_ces_signature_sets()
```

### Response
#### Success Response
Prints a list of available signature set names to the console.

#### Response Example
```
[1] "COSMIC_v3.2_GRCh38"
[2] "COSMIC_v3.3_GRCh38"
[3] "COSMIC_v3.3_GRCh37"
```
```

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

### vcfs_to_maf_table

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/vcfs_to_maf_table.html

This function loads VCF files into MAF-like tables. It adds a Tumor_Sample_Barcode column and converts POS/REF/ALT fields to match MAF style for Start_Position/Reference_Allele/Tumor_Seq_Allele2. The input VCF files should contain high-confidence somatic variant calls for a single tumor sample.

```APIDOC
## vcfs_to_maf_table

### Description
Loads VCF files into MAF-like tables, adding a Tumor_Sample_Barcode column and standardizing position and allele fields.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Arguments
- **vcfs** (vector or list or data.table) - Required - Vector of VCF file paths, or a list of VCF-like data.tables, or a single data.table.
- **sample_ids** (vector) - Required - Identifiers to populate Tumor_Sample_Barcode, one per VCF.

### Value
A single data.table with MAF-style fields, suitable for use with cancereffectsizeR.
```

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

### Load sample data into CESAnalysis

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/load_sample_data.html

Use this function to add sample-level information to an existing CESAnalysis object. The input data must contain a Unique_Patient_Identifier column to map correctly to the samples table.

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

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

### Build RefCDS object

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/build_RefCDS.html

Constructs a RefCDS object and associated GenomicRanges from Gencode-style GTF files and genome assemblies.

```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"
)
```

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

### R Function: samples_with

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/samples_with.html

Identifies samples containing specific variants within a CESAnalysis object.

```APIDOC
## samples_with

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

### Usage
samples_with(cesa, any_of = NULL)

### Arguments
- **cesa** (CESAnalysis) - The CESAnalysis object to search.
- **any_of** (vector) - Optional. Select samples with ANY of the given variant names/IDs, such as c("8:142506482_C>G", "KRAS G12C").
```

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

### make_PathScore_input

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/make_PathScore_input.html

Converts MAF-like data into a tab-delimited format suitable for the PathScore web tool.

```APIDOC
## make_PathScore_input

### Description
Produce a file from MAF data for use with PathScore, a web tool for identifying significantly altered pathways in cancer.

### Usage
make_PathScore_input(maf, file = NULL, genome = "hg38")

### Parameters
- **maf** (data.table) - Required - An MAF-like data.table. If the MAF has a column named 'annot', this column will be preserved in output.
- **file** (string) - Optional - Name/path where PathScore-formatted data should be written. Will be a tab-delimited text file.
- **genome** (string) - Optional - The genome build associated with the MAF file. Must be "hg38" (default) or "hg19".

### Value
A copy of the PathScore-formatted data as a data.table.
```

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

### Display Head of Gene Mutation Rates

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Displays the first few rows of the calculated gene mutation rates. This is useful for a quick inspection of the estimated mutation rates and their confidence intervals.

```r
head(cesa$gene_rates)
```

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

### Load Saved CESAnalysis - R

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/load_cesa.html

Use this function to load a previously saved CESAnalysis object. The file must be saved using `saveRDS` and have an .rds extension.

```r
load_cesa(file)
```

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

### View epistasis function output

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/epistasis_results.html

Returns a list of data tables containing results from epistasis functions. Requires a CESAnalysis object.

```r
epistasis_results(cesa = NULL)
```

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

### Generate Site-Level Selection Log-Likelihood Function

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/sswm_lik.html

Generates the log-likelihood function for site-level selection under the 'strong selection, weak mutation' assumption. All necessary arguments are automatically provided by `ces_variant()`.

```R
sswm_lik(rates_tumors_with, rates_tumors_without)
```

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

### List Built-in Reference Data Sets in R

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/list_ces_refsets.html

Use this function to view the names of all reference data sets included with the cancereffectsizeR package. No arguments are required.

```R
list_ces_refsets()
```

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

### sswm_lik Function

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/sswm_lik.html

Generates a log-likelihood function of site-level selection with 'strong selection, weak mutation' assumption.

```APIDOC
## R Function: sswm_lik

### Description
Generates log-likelihood function of site-level selection with "strong selection, weak mutation" assumption. All arguments to this likelihood function factory are automatically supplied by ces_variant().

### Usage
sswm_lik(rates_tumors_with, rates_tumors_without)

### Parameters
- **rates_tumors_with** (vector) - Required - Site-specific mutation rates for all tumors with variant
- **rates_tumors_without** (vector) - Required - Site-specific mutation rates for all eligible tumors without variant
```

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

### build_RefCDS

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/build_RefCDS.html

Creates a dNdScv-style RefCDS object and an associated GenomicRanges object from Gencode-style GTF files.

```APIDOC
## build_RefCDS

### Description
Takes in gene/transcript/CDS definitions and creates a dNdScv-style RefCDS object and an associated GenomicRanges object required to run dNdScv.

### Parameters
- **gtf** (string) - Required - Path of a Gencode-style GTF file, or an equivalently formatted data table.
- **genome** (string/BSgenome) - Required - Genome assembly name (e.g., "hg19") or a BSgenome object.
- **use_all_transcripts** (boolean) - Optional - Whether to use all complete transcripts or just the longest one for each gene. Default: TRUE.
- **cds_ranges_lack_stop_codons** (boolean) - Optional - Set to FALSE if input CDS records include stop codons. Default: TRUE.
- **cores** (integer) - Optional - Number of cores to use for parallel computations. Default: 1.
- **additional_essential_splice_pos** (list) - Optional - A list of additional essential splice site positions.
- **numcode** (integer) - Optional - NCBI genetic code number. Default: 1.
- **chromosome_style** (string) - Optional - Chromosome naming style (e.g., "NCBI" or "UCSC"). Default: "NCBI".

### Response
- **RefCDS** (list) - A list containing information on one coding sequence (CDS).
- **GRanges** (object) - A GenomicRanges object that defines the genomic intervals covered by each CDS.
```

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

### Convert BED intervals using lift_bed

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/lift_bed.html

Use this function to perform coordinate conversion. It accepts either a file path or a GRanges object and optionally exports the result to a file.

```R
lift_bed(bed, chain, outfile = NULL)
```

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

### Save and Load CESAnalysis

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Persists the current analysis state to an RDS file and restores it in future sessions.

```R
save_cesa(cesa = cesa, "cancerffectsizeR_tutorial_analysis.rds")

# In some future R session...
library(cancereffectsizeR)
cesa <- load_cesa("cancerffectsizeR_tutorial_analysis.rds")
```

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

### Load sample data into CESAnalysis

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Load clinical or sample-specific data into the CESAnalysis object. This function integrates additional sample information.

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

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

### Convert VCF files to MAF-like table

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/vcfs_to_maf_table.html

Use this function to prepare high-confidence somatic variant calls for analysis. Ensure the input VCF files correspond to the provided sample identifiers.

```R
vcfs_to_maf_table(vcfs, sample_ids)
```

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

### Preload MAF Data

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/preload_maf.html

Loads MAF-formatted data, checks for issues, and adds quality annotations. Use this function to prepare your somatic mutation data for analysis.

```R
preload_maf(
  maf = NULL,
  refset = NULL,
  coverage_intervals_to_check = NULL,
  chain_file = NULL,
  sample_col = "Unique_Patient_Identifier",
  chr_col = "Chromosome",
  start_col = "Start_Position",
  ref_col = "Reference_Allele",
  tumor_allele_col = "guess",
  keep_extra_columns = FALSE,
  detect_hidden_mnv = TRUE
)
```

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

### MAF Data Preparation

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/index.html

Functions for obtaining and preparing MAF (Mutation Annotation Format) somatic mutation data.

```APIDOC
## Obtain and prep MAF data

### Description
Functions to obtain and prepare MAF somatic mutation data.

### Functions
- `preload_maf()`: Read and verify MAF somatic mutation data.
- `check_sample_overlap()`: Catch duplicate samples.
- `get_TCGA_project_MAF()`: Get MAF data from TCGA cohort.
- `vcfs_to_maf_table()`: Read a VCF into an MAF-like table.
- `make_PathScore_input()`: Make a PathScore input file from MAF data.
- `lift_bed()`: Convert BED intervals between genome builds.
```

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

### View output from epistasis functions

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/epistasis_results.html

This function returns a list of data tables containing results from epistasis functions.

```APIDOC
## epistasis_results

### Description
Returns a list of data tables with results from epistasis functions.

### Method
N/A (R function)

### Endpoint
N/A (R function)

### Arguments 
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```R
epistasis_results(cesa = NULL)
```

### Response
#### Success Response (200)
- **cesa** (CESAnalysis object) - The input CESAnalysis object.

#### Response Example
```R
# Example response structure (actual output will be a list of data tables)
list(
  epistasis_table_1 = data.frame(...),
  epistasis_table_2 = data.frame(...)
)
```
```

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

### preload_maf

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/preload_maf.html

Reads and verifies MAF-formatted somatic mutation data, including support for genome build conversion and quality control annotations.

```APIDOC
## preload_maf

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

### Parameters
#### Arguments
- **maf** (string/data.table) - Required - Path to tab-delimited MAF file or data object.
- **refset** (string) - Required - Name of the reference data set or path to custom reference directory.
- **coverage_intervals_to_check** (string/GRanges) - Optional - BED file or GRanges object representing expected sequencing coverage.
- **chain_file** (string) - Optional - Path to a UCSC-style .chain file for LiftOver coordinate conversion.
- **sample_col** (string) - Optional - Column name for patient ID (defaults to Unique_Patient_Identifier).
- **chr_col** (string) - Optional - Column name for chromosome data (defaults to Chromosome).
- **start_col** (string) - Optional - Column name for start position (defaults to Start_Position).
- **ref_col** (string) - Optional - Column name for reference allele (defaults to Reference_Allele).
- **tumor_allele_col** (string) - Optional - Column name for alternate allele.
- **keep_extra_columns** (boolean/vector) - Optional - Whether to keep non-essential columns.
- **detect_hidden_mnv** (boolean) - Optional - Whether to identify and merge adjacent SNVs into DBS/MNV records.

### Value
A data.table containing the processed MAF data with quality control flags and annotations.
```

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

### pairwise_epistasis_lik Function

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/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
```
pairwise_epistasis_lik(with_just_1, with_just_2, with_both, with_neither)
```

### Arguments 

*   **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()` and `ces_gene_epistasis()`.
```

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

### Preload MAF Data

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/articles/cancereffectsizeR.html

Process MAF files to extract necessary columns and perform quality checks for cancereffectsizeR analysis.

```R
tcga_maf <- preload_maf(maf = tcga_maf_file, refset = "ces.refset.hg38")
```

```R
tgs_maf_file <- system.file("tutorial/metastatic_breast_2021_hg38.maf", package = "cancereffectsizeR")
tgs_maf <- preload_maf(maf = tgs_maf_file, refset = "ces.refset.hg38")
```

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

### CompoundVariantSet Constructor

Source: https://townsend-lab-yale.github.io/cancereffectsizeR/reference/CompoundVariantSet.html

Creates a CompoundVariantSet object from a CESAnalysis and a list of variant IDs.

```APIDOC
## CompoundVariantSet(cesa, variant_id)

### Description
A CompoundVariantSet is a collection of disjoint "compound variants". A compound variant is an arbitrary group of variants that have sequencing coverage across some set of samples.

### Parameters
#### Arguments
- **cesa** (CESAnalysis) - Required - The CESAnalysis object used to access variant annotations.
- **variant_id** (Vector or List) - Required - A vector of variant IDs to include in one compound variant, or a list of vectors, each of which defines a separate compound variant.

### Request Example
CompoundVariantSet(cesa, variant_id = list(kras12 = c("KRAS G12C", "KRAS G12D", "KRAS G12V")))
```
Tokens:
Raw