Package 'YAPSA'

Description

Function to iteratively add information to an annotation data structure as needed for HeatmapAnnotation and especially for annotation_exposures_barplot

Usage

add_annotation(
  in_annotation_col,
  in_annotation_df,
  in_attribution_vector,
  in_colour_vector,
  in_name
)

Arguments

Value

A list with entries

• annotation_col: A list as in in_annotation_col but with one additional layer of annotation

• annotation_df: A data frame as in in_annotation_df but with one additional layer of annotation

Examples

NULL

Description

Works for all types of lists and inputs

Usage

add_as_fist_to_list(in_list, in_element)

Arguments

Value

List with input element as first entry.

Examples

NULL

Description

If a valid category (i.e. it matches to a category specified in in_sig_ind_df) is supplied, then the exposures are aggregated over this category.

Usage

aggregate_exposures_by_category(in_exposures_df, in_sig_ind_df, in_category)

Arguments

Value

A list with entries:

• exposures: The exposures H, a numeric data frame with l rows and m columns, l being the number of aggregated signatures and m being the number of samples

• norm_exposures: The normalized exposures H, a numeric data frame with l rows and m columns, l being the number of aggregated signatures and m being the number of samples

• out_sig_ind_df: Data frame of the type signature_indices_df, i.e. indicating name, function and meta-information of the aggregated signatures..

See Also

LCD_complex_cutoff

Examples

NULL

Description

The function annotates the intermutational distance to a cohort wide data frame by applying annotate_intermut_dist_PID to every PID-specific subfraction of the cohort wide data. Note that annotate_intermut_dist_PID calls rainfallTransform. If the PID information is missing, annotate_intermut_dist_PID is called directly for the whole input.

Usage

annotate_intermut_dist_cohort(
  in_dat,
  in_CHROM.field = "CHROM",
  in_POS.field = "POS",
  in_PID.field = NULL,
  in_mode = "min",
  in_verbose = FALSE
)

Arguments

Value

VRanges object, VRangesList, data frame or list of data frames identical to in_df (reordered by in_PID.field), but with the intermutation distance annotated as an additional column on the right named dist.

See Also

annotate_intermut_dist_PID

rainfallTransform

Examples

test_df <- data.frame(CHROM=c(1,1,1,2,2,2,3,3,3,4,4,4,5,5),
                      POS=c(1,2,4,4,6,9,1,4,8,10,20,40,100,200),
                      REF=c("C","C","C","T","T","T","A",
                            "A","A","G","G","G","N","A"),
                      ALT=c("A","G","T","A","C","G","C",
                            "G","T","A","C","T","A","N"),
                      PID=c(1,1,1,2,2,2,1,1,2,2,2,1,1,2))
test_df <- test_df[order(test_df$PID,test_df$CHROM,test_df$POS),]
min_dist_df <-
  annotate_intermut_dist_cohort(test_df,in_CHROM.field="CHROM",
                                in_POS.field="POS", in_PID.field="PID",
                                in_mode="min")
max_dist_df <-
  annotate_intermut_dist_cohort(test_df,in_CHROM.field="CHROM",
                                in_POS.field="POS", in_PID.field="PID",
                                in_mode="max")
min_dist_df
max_dist_df

Description

The function annotates the intermutational distance to a PID wide data frame by applying rainfallTransform to every chromosome-specific subfraction of the PID wide data.

Usage

annotate_intermut_dist_PID(
  in_dat,
  in_CHROM.field = "CHROM",
  in_POS.field = "POS",
  in_mode = "min",
  in_verbose = FALSE
)

Arguments

Value

VRanges object or data frame identical to in_dat, but with the intermutation distance annotated as an additional column on the right named dist.

See Also

annotate_intermut_dist_cohort

rainfallTransform

Examples

test_df <- data.frame(
 CHROM=c(1,1,1,2,2,2,3,3,3,4,4,4,5,5),
 POS=c(1,2,4,4,6,9,1,4,8,10,20,40,100,200),
 REF=c("C","C","C","T","T","T","A","A","A","G","G","G","N","A"),
 ALT=c("A","G","T","A","C","G","C","G","T","A","C","T","A","N"))
min_dist_df <- annotate_intermut_dist_PID(test_df,in_CHROM.field="CHROM",
                                          in_POS.field="POS",
                                          in_mode="min")
max_dist_df <- annotate_intermut_dist_PID(test_df,in_CHROM.field="CHROM",
                                          in_POS.field="POS",
                                          in_mode="max")
min_dist_df
max_dist_df

Description

The exposures H, determined by NMF or by LCD, are displayed as a stacked barplot by calling Heatmap. The x-axis displays the PIDs (patient identifier or sample), the y-axis the counts attributed to the different signatures with their respective colours per PID. It is analogous to plot_exposures. As many layers of information as desired can be added via an annotation data frame. The annotation data is handled in a way similar to annotation_heatmap_exposures. This function calls:

• rowAnnotation,

• HeatmapAnnotation and

• Heatmap

Usage

annotation_exposures_barplot(
  in_exposures_df,
  in_signatures_ind_df,
  in_subgroups_df,
  in_annotation_df = NULL,
  in_annotation_col = NULL,
  ylab = NULL,
  title = "",
  in_labels = FALSE,
  in_barplot_borders = TRUE,
  in_column_anno_borders = FALSE,
  in_annotation_legend_side = "right",
  in_padding = unit(c(2, 20, 2, 2), "mm"),
  in_annotation = NULL
)

Arguments

Details

It might be necessary to install the newest version of the development branch of the packages circlize and ComplexHeatmap by Zuguang Gu: devtools::install_github("jokergoo/circlize") and devtools::install_github("jokergoo/ComplexHeatmap")

It might be necessary to install the newest version of the development branch of the packages circlize and ComplexHeatmap by Zuguang Gu: devtools::install_github("jokergoo/circlize") and devtools::install_github("jokergoo/ComplexHeatmap")

Value

The function doesn't return any value.

See Also

HeatmapAnnotation

Heatmap

decorate_heatmap_body

annotation_heatmap_exposures

plot_exposures

Examples

NULL

Description

The exposures H, determined by NMF or by LCD, are displayed as a stacked barplot by calling Heatmap. The x-axis displays the PIDs (patient identifier or sample), the y-axis the counts attributed to the different signatures with their respective colours per PID. It is analogous to plot_exposures. As many layers of information as desired can be added via an annotation data frame. The annotation data is handled in a way similar to annotation_heatmap_exposures. In comparison to annotation_exposures_barplot allows this function to deal with a list of differn signature and mutation types. This function calls:

• rowAnnotation,

• HeatmapAnnotation and

• Heatmap

Usage

annotation_exposures_list_barplot(
  in_exposures_list,
  in_signatures_ind_list,
  in_subgroups_list,
  in_annotation_list,
  ylab = NULL,
  title = "",
  in_indel_sigs = FALSE,
  in_labels = FALSE,
  in_barplot_borders = TRUE,
  in_column_anno_borders = FALSE,
  in_annotation_legend_side = "right",
  in_padding = unit(c(2, 20, 2, 2), "mm"),
  in_annotation = NULL
)

Arguments

Details

It might be necessary to install the newest version of the development branch of the packages circlize and ComplexHeatmap by Zuguang Gu: devtools::install_github("jokergoo/circlize") and devtools::install_github("jokergoo/ComplexHeatmap")

It might be necessary to install the newest version of the development branch of the packages circlize and ComplexHeatmap by Zuguang Gu: devtools::install_github("jokergoo/circlize") and devtools::install_github("jokergoo/ComplexHeatmap")

Value

The function doesn't return any value.

See Also

HeatmapAnnotation

Heatmap

decorate_heatmap_body

annotation_heatmap_exposures

plot_exposures

Examples

NULL

Description

The PIDs are clustered according to their signature exposures. The procedure is analogous to complex_heatmap_exposures, but enabling more than one annotation row for the PIDs. This function calls:

• rowAnnotation,

• HeatmapAnnotation and

• Heatmap

Usage

annotation_heatmap_exposures(
  in_exposures_df,
  in_annotation_df,
  in_annotation_col,
  in_signatures_ind_df,
  in_data_type = "norm exposures",
  in_method = "manhattan",
  in_palette = colorRamp2(c(0, 0.2, 0.4, 0.6), c("white", "yellow", "orange", "red")),
  in_cutoff = 0,
  in_filename = NULL,
  in_column_anno_borders = FALSE,
  in_row_anno_borders = FALSE,
  in_show_PIDs = TRUE,
  in_annotation_legend_side = "right"
)

Arguments

Details

One additional parameter, in_show_legend_bool_vector, indicating which legends to display, is planned but deactivated in this version of the package. In order to use this features, it will be necessary to install the newest version of the packages circlize and ComplexHeatmap by Zuguang Gu: devtools::install_github("jokergoo/circlize") and devtools::install_github("jokergoo/ComplexHeatmap")

Value

The function doesn't return any value.

See Also

Heatmap

complex_heatmap_exposures

Examples

NULL

Description

SNVs are grouped into 6 different categories (12/2 as reverse complements are summed over). This function defines the attribution.

Usage

attribute_nucleotide_exchanges(
  in_dat,
  in_REF.field = "REF",
  in_ALT.field = "ALT",
  in_verbose = FALSE
)

Arguments

Value

A character vector with as many rows as there are in in_dat which can be annotated (i.e. appended) to the input data frame.

Examples

test_df <- data.frame(
 CHROM=c(1,1,1,2,2,2,3,3,3,4,4,4,5,5),
 POS=c(1,2,3,4,5,6,1,2,3,4,5,6,7,8),
 REF=c("C","C","C","T","T","T","A","A","A","G","G","G","N","A"),
 ALT=c("A","G","T","A","C","G","C","G","T","A","C","T","A","N"))
test_df$change <- attribute_nucleotide_exchanges(
 test_df,in_REF.field = "REF",in_ALT.field = "ALT")
test_df

Description

The function is a wrapper and uses getSequenceContext to annotate the sequence context.

Usage

attribute_sequence_contex_indel(
  in_dat,
  in_REF.field = "REF",
  in_ALT.field = "ALT",
  in_verbose = FALSE,
  in_offsetL = 10,
  in_offsetR = 50
)

Arguments

Value

VRanges object or data frame with the same number rows and additional columns containing the type of INDEL (Ins = insertion and Del = deletion), the annotated sequence context of the defined length, the absolute number of exchanged nucleotides and the nucleotide exchange between in_REF.field and in_ALT.field.

Examples

data(GenomeOfNl_raw)
GenomeOfNl_context <- attribute_sequence_contex_indel(
                                   in_dat = head(GenomeOfNl_raw),
                                   in_REF.field = "REF",
                                   in_ALT.field = "ALT",
                                   in_verbose = FALSE,
                                   in_offsetL= 10, in_offsetR=50)
GenomeOfNl_context

Description

Each varaint is categorized into one of the 83 INDEL categories. The classification likewise to Alexandrov et al., 2018 (https://www.synapse.org/#!Synapse:syn11726616). The number of 83 features are classefied asfollowed:

1. Deletion of 1 bp C/(G) or T/(A) in a repetitive context. The context is classified into 1, 2, 3, 4, 5 or larger or equal to 6 times the same nucleotide(s).

2. Insertion of 1 bp C/(G) or T/(A) in a repetitive context. The context is classified into 0, 1, 2, 3, 4, or larger or equal to 5 times the same nucleotide(s).

3. Deletions of 2bps, 3bps, 4bps or more or equal to 5bps in a repetitive context. Each deletion is classified in a context of 1, 2, 3, 4, 5 or larger or equal to 6 times the same motif.

4. Insertion of 2 bps, 3 bps, 4 bps or more or equal to 5 bps in a repetitive context. Each deletion is classified in a context of 0, 1, 2, 3, 4 or larger or equal to 5 times the same motif.

5. Microhomology deletion of 2bps, 3bps, 4bps or more or equal to 5 bps in a partly repetitive context. The partly repetitive context is defined by motif length of minus 1 bp, 2 bps, 3 bps, 4 bps or more or equal to 5bps, which is located before and after the break-point junction of the deletion.

Usage

attribution_of_indels(in_dat_return = in_dat_return)

Arguments

Value

Data frame with the same dimention as the input data frame plus an addional column with the INDEL classification number corrospondig to Alexandrov et al. 2018.

Examples

data(GenomeOfNl_raw)
GenomeOfNl_context <- attribute_sequence_contex_indel(in_dat =
head(GenomeOfNl_raw))
GenomeOfNl_classified <- attribution_of_indels(GenomeOfNl_context)
GenomeOfNl_classified

Description

Build a gene list for a given pathway name

Usage

build_gene_list_for_pathway(in_string, in_organism)

Arguments

Value

A character vector of gene names

See Also

keggLink

keggFind

extract_names_from_gene_list

Examples

species <- "hsa"
   gene_lists_meta_df <- data.frame(
     name=c("BER","NHEJ","MMR"),
     explanation=c("base excision repair",
                   "non homologous end joining",
                   "mismatch repair"))
   number_of_pathways <- dim(gene_lists_meta_df)[1]
   gene_lists_list <- list()
   for (i in seq_len(number_of_pathways)) {
     temp_list <- 
       build_gene_list_for_pathway(gene_lists_meta_df$explanation[i],
                                   species)
     gene_lists_list <- c(gene_lists_list,list(temp_list))
   }
   gene_lists_list

Description

INDEL function V1 - not compartible with AlexandrovSignatures

Usage

classify_indels(
  in_df,
  in_ALT.field = "ALT",
  in_REF.field = "REF",
  in_breaks = c(-Inf, -10, -3, 0, 2, 9, Inf),
  in_labels = c("del3", "del2", "del1", "in1", "in2", "in3")
)

Arguments

Value

classVector, a factor vector of indel sizes

Examples

NULL

Description

Compares exposures computed by two alternative approaches for the same cohort

Usage

compare_exposures(in_exposures1_df, in_exposures2_df, deselect_flag = TRUE)

Arguments

Value

A list with entries merge_df, all_cor.coeff, all_p.value, cor.coeff_vector, p.value_vector, all_cor.test, and cor.test_list.

• merge_df: Merged molten input exposure data frames

• all_cor.coeff: Pearson correlation coefficient for all data points, i.e. taken all signatures together

• all_p.value: P-value of the Pearson test for all data points, i.e. taken all signatures together

• cor.coeff_vector: A vector of Pearson correlation coefficients evaluated for every signature independently

• p.value_vector: A vector of p-values of the Pearson tests evaluated for every signature independently

• all_cor.test: A data structure as returned by cor.test for all data points, i.e. taken all signatures together

• cor.test_list: A list of data structures as returned by cor.test, but evaluated for every signature independently

Examples

NULL

Description

Compare two sets of exposures, stored in numerical data frames H1 and H2, by computing the row-wise cosine distance

Usage

compare_expousre_sets(in_df_small, in_df_big, in_distance = cosineDist)

Arguments

Value

A list with entries distance, hierarchy_small and hierarchy_big.

• distance: A numerical data frame with the cosine distances between the columns of H1, indexing the rows, and H2, indexing the columns

• hierarchy_small: A data frame carrying the information of ranked similarity between the signatures in H2 with the signatures in H1

• hierarchy_big: A data frame carrying the information of ranked similarity between the signatures in H1 with the signatures in H2

See Also

cosineDist

Examples

sig_1_df <- data.frame(matrix(c(1,0,0,0,0,1,0,0,0,0,1,0),ncol=3))
names(sig_1_df) <- paste0("B",seq_len(dim(sig_1_df)[2]))
sig_2_df <- data.frame(matrix(c(1,1,0,0,0,0,1,1),ncol=2))
compare_expousre_sets(sig_1_df,sig_2_df)

Description

Compare two sets of signatures, stored in numerical data frames W1 and W2, by computing the column-wise cosine distance

Usage

compare_sets(in_df_small, in_df_big, in_distance = cosineDist)

Arguments

Value

A list with entries distance, hierarchy_small and hierarchy_big.

• distance: A numerical data frame with the cosine distances between the columns of W1, indexing the rows, and W2, indexing the columns

• hierarchy_small: A data frame carrying the information of ranked similarity between the signatures in W2 with the signatures in W1

• hierarchy_big: A data frame carrying the information of ranked similarity between the signatures in W1 with the signatures in W2

See Also

cosineDist

Examples

sig_1_df <- data.frame(matrix(c(1,0,0,0,0,1,0,0,0,0,1,0),ncol=3))
names(sig_1_df) <- paste0("B",seq_len(dim(sig_1_df)[2]))
sig_2_df <- data.frame(matrix(c(1,1,0,0,0,0,1,1),ncol=2))
compare_sets(sig_1_df,sig_2_df)

Description

Compare all strata from different orthogonal stratification axes, i.e. othogonal SMCs by cosine similarity of signature exposures. First calls

• make_strata_df, then

• plot_strata and finally

• make_comparison_matrix

Usage

compare_SMCs(
  in_stratification_lists_list,
  in_signatures_ind_df,
  output_path,
  in_nrect = 5,
  in_attribute = ""
)

Arguments

Value

The comparison matrix of cosine similarities.

See Also

plot_strata

make_comparison_matrix

Examples

NULL

Description

Compare one mutational catalogue (e.g. of one index patient) to a list of reference mutational catalogues (e.g. from the initial Alexandrov puplication) by cosine similarities

Usage

compare_to_catalogues(in_index_df, in_comparison_list)

Arguments

Value

A similarity dataframe

Examples

NULL

Description

The PIDs are clustered according to their signature exposures. uses package ComplexHeatmap by Zuguang Gu. This function calls:

• rowAnnotation,

• HeatmapAnnotation and

• Heatmap

Usage

complex_heatmap_exposures(
  in_exposures_df,
  in_subgroups_df,
  in_signatures_ind_df,
  in_data_type = "norm exposures",
  in_method = "manhattan",
  in_subgroup_column = "subgroup",
  in_subgroup_colour_column = NULL,
  in_palette = colorRamp2(c(0, 0.2, 0.4, 0.6), c("white", "yellow", "orange", "red")),
  in_cutoff = 0,
  in_filename = NULL,
  in_column_anno_borders = FALSE,
  in_row_anno_borders = FALSE
)

Arguments

Details

It might be necessary to install the newest version of the development branch of the packages circlize and ComplexHeatmap by Zuguang Gu: devtools::install_github("jokergoo/circlize") and devtools::install_github("jokergoo/ComplexHeatmap")

Value

The function doesn't return any value.

See Also

Heatmap

Examples

data(lymphoma_cohort_LCD_results)
 complex_heatmap_exposures(
   rel_lymphoma_Nature2013_COSMIC_cutoff_exposures_df,
   COSMIC_subgroups_df,
   chosen_signatures_indices_df,
   in_data_type="norm exposures",
   in_subgroup_colour_column="col",
   in_method="manhattan",
   in_subgroup_column="subgroup")

Description

Compare one mutational catalogue (e.g. of one index patient) to a list of reference mutational catalogues (e.g. from the initial Alexandrov puplication) by cosine similarities

Usage

compute_comparison_stat_df(in_sim_df)

Arguments

Value

A dataframe containing statistical measures, prepared for bar plot

Examples

NULL

Description

Compute the loglikelihood

Usage

computeLogLik(in_vector, in_pdf = NULL, verbose = FALSE)

Arguments

Value

A numeric value (sum of the logarithms of the likelihoods of the input vector)

Examples

NULL

Description

Wrapper function around confIntExp, which is applies to every signature or sample pair in a cohort. The extracted lower bound of the confidence intervals are added to the input data which is reodered and melted in order to prepare for visualization with ggplot2. The calculates of confidence intervals is based on a profiling likelihood algorithm and the wrapper calculates the data for the exposure contubution identefied with SNV and INDEL signature decompositions and application of the following cutoffs:

1. CosmicValid_absCutoffVector

2. CosmicValid_normCutoffVector

3. CosmicArtif_absCutoffVector

4. CosmicArtif_normCutoffVector

5. PCAWGValidSNV_absCutoffVector

6. PCAWGValidID_absCutoffVector

The function makes use of differnet YAPSA functions. For each of the above stated cutoff vectors a per PID decompostion of the SNV and INDEL catalog is calulated respectivly using LCD_complex_cutoff_perPID. In a next step, variateExp wich is a wrapper around confIntExp to compute confidence intervals for a cohort is used. A dataframe is returend with the upper and lower bounds of the confidence intervals. In a last step plotExposuresConfidence_indel to plot the exposures to extracted signatures including confidence intervals computed with e.g. by variateExp.

Usage

confidence_indel_calulation(in_current_indel_df, in_current_snv_df)

Arguments

Value

A list is returned containing 12 objects. For each cutoff data frame two corrosponding object are present. First, the p gtable object which can be used for gaphically visualization, and second a dataframe containing the corrosponding upper and lower bounds of the confidence intervals.

Examples

data("GenomeOfNl_MutCat")

Description

Wrapper function around confIntExp, which is applies to every signature or sample pair in a cohort. The extracted lower bound of the confidence intervals are added to the input data which is reodered and melted in order to prepare for visualization with ggplot2. The calculates of confidence intervals is based on a profiling likelihood algorithm and the wrapper calculates the data for the exposure contubution identefied with INDEL singature decomposition and the usage of PCAWGValidID_absCutoffVector data frame.

Usage

confidence_indel_only_calulation(in_current_indel_df)

Arguments

Details

The function makes use of differnet YAPSA functions. For each of the above stated cutoff vectors a per PID decompostion of the SNV and INDEL catalog is calulated respectivly using LCD_complex_cutoff_perPID. In a next step, variateExp which is a wrapper around confIntExp to compute confidenceintervals for a cohort is used. A dataframe is returend with the upper and lower bounds of the confidence intervals. In a last step plotExposuresConfidence_indel to plot the exposures to extracted signatures including confidence intervals computed with e.g. by variateExp.

Value

A list is returned containing two object. First, the p gtable object which can be used for gaphically visualization, and second a dataframe containing the corrosponding upper and lower bounds of the confidence intervals.

Examples

data("GenomeOfNl_MutCat")
temp_list <- confidence_indel_only_calulation(
                        in_current_indel_df=MutCat_indel_df)
plot(temp_list$p_complete_PCAWG_ID)
head(temp_list$complete_PCAWG_ID)

Description

Compute confidence intervals using the (log-)likelihood ratio test, primarily for one input sample.

Usage

confIntExp(
  in_ind = 1,
  in_sigLevel = 0.05,
  in_delta = 1,
  in_exposure_vector = NULL,
  in_verbose = FALSE,
  ...
)

Arguments

Value

A list with entries

• upper: Upper bound of the confidence interval

• lower: Lower bound of the confidence interval

Examples

library(BSgenome.Hsapiens.UCSC.hg19)
 data(lymphoma_test)
 data(lymphoma_cohort_LCD_results)
 data(sigs)
 word_length <- 3
 temp_list <- create_mutation_catalogue_from_df(
   lymphoma_test_df,this_seqnames.field = "CHROM",
   this_start.field = "POS",this_end.field = "POS",
   this_PID.field = "PID",this_subgroup.field = "SUBGROUP",
   this_refGenome = BSgenome.Hsapiens.UCSC.hg19,
   this_wordLength = word_length)
 lymphoma_catalogue_df <- temp_list$matrix
 lymphoma_PIDs <- colnames(lymphoma_catalogue_df)
 data("lymphoma_cohort_LCD_results")
 lymphoma_exposures_df <-
   lymphoma_Nature2013_COSMIC_cutoff_exposures_df[, lymphoma_PIDs]
 lymphoma_sigs <- rownames(lymphoma_exposures_df)
 lymphoma_sig_df <- AlexCosmicValid_sig_df[, lymphoma_sigs]
 confIntExp(in_ind = 1, in_sigLevel = 0.05, in_delta = 0.4,
            in_exposure_vector = lymphoma_exposures_df[, 1],
            in_catalogue_vector = lymphoma_catalogue_df[, 1],
            in_sig_df = lymphoma_sig_df)

Description

After use of the function round_precision the norm of the input vector may have been altered by the rounding procedure. This function restores the norm by altering only the largest entry in the rounded vector (in order to create the least possible relative error).

Usage

correct_rounded(x, in_interval = c(0, 1))

Arguments

Value

The adapted form of the input vector x.

Examples

NULL

Description

Compute the cosine distance of two vectors

Usage

cosineDist(a, b)

Arguments

Value

The scalar product of the two input vectors divided by the product of the norms of the two input vectors

Examples

## 1. Orthogonal vectors:
cosineDist(c(1,0),c(0,1))
## 2. Non-orthogonal vectors:
cosineDist(c(1,0),c(1,1))
## Compare trigonometry:
1-cos(pi/4)

Description

This is an altered cosine distance: it first reduced the dimension of the two input vectors to only those coordinates where both have non-zero entries. The cosine similarity is then computed on these reduced vectors, i.e. on a sub-vector space.

Usage

cosineMatchDist(a, b)

Arguments

Value

The scalar product of the reduced input vectors divided by the product of the norms of the two reduced input vectors

Examples

## 1. Orthogonal vectors:
cosineMatchDist(c(1,0),c(0,1))
## 2. Non-orthogonal vectors:
cosineMatchDist(c(1,0),c(1,1))

Description

This function creates a mutational catalog from a data frame. It requires the returend data frame optainted with attribution_of_indels.

Usage

create_indel_mut_cat_from_df(in_df, in_signatures_df)

Arguments

Value

A count dataframe, the mutational catalog V with rownames indicating the INDELs and colnames having the PIDs

Examples

data(GenomeOfNl_raw)
data(sigs_pcawg)
GenomeOfNl_context <- attribute_sequence_contex_indel(in_dat =
 head(GenomeOfNl_raw))
GenomeOfNl_classified <- attribution_of_indels(GenomeOfNl_context)
GenomeOfNl_mut_cat <- create_indel_mut_cat_from_df(GenomeOfNl_classified,
 in_signatures_df=PCAWG_SP_ID_sigs_df)

Description

From data frame constucted from a vcf-file file the function create_indel_mutation_catalogue_from_df creates a mutational catalog V by squencially applying the attribute_sequence_contex_indel, attribute_sequence_contex_indel and then attribution_of_indels. The runtime of the function is about 1 sec per 6 variants as sequence context as well as INDEL calssification are timeconsuming to compute (optimization ongoing)

Usage

create_indel_mutation_catalogue_from_df(
  in_dat,
  in_signature_df,
  in_REF.field = "REF",
  in_ALT.field = "ALT",
  in_verbose = FALSE
)

Arguments

Value

A dataframe in the format of a mutational catalog V, which can be used for LCD analysis

Examples

data(sigs_pcawg)
data(GenomeOfNl_raw)
temp_df <- translate_to_hg19(GenomeOfNl_raw[1:200,],"CHROM")
temp_df$PID <- sample(c("PID1","PID2","PID3","PID4","PID5"),200,replace=TRUE)
temp <- create_indel_mutation_catalogue_from_df(in_dat = temp_df,
   in_signature_df = PCAWG_SP_ID_sigs_df,
   in_REF.field = "REF",
   in_ALT.field = "ALT",
   in_verbose = FALSE)
dim(temp)
head(temp)

Description

This function creates a mutational catalogue from a data frame. It is a wrapper function for create_mutation_catalogue_from_VR: it first creates a VRanges object from the data frame by makeVRangesFromDataFrame and then passes this object on to the above mentioned custom function.

Usage

create_mutation_catalogue_from_df(
  this_df,
  this_refGenome_Seqinfo = NULL,
  this_seqnames.field = "X.CHROM",
  this_start.field = "POS",
  this_end.field = "POS",
  this_PID.field = "PID",
  this_subgroup.field = "subgroup",
  this_refGenome,
  this_wordLength,
  this_verbose = 1,
  this_rownames = c(),
  this_adapt_rownames = 1
)

Arguments

Value

A list with entries matrix and frame obtained from create_mutation_catalogue_from_VR:

• matrix: The mutational catalogue V

• frame: Additional and meta information on rownames (features), colnames (PIDs) and subgroup attribution.

See Also

makeVRangesFromDataFrame

create_mutation_catalogue_from_VR

Examples

library(BSgenome.Hsapiens.UCSC.hg19)
 data(lymphoma_test)
 word_length <- 3
 temp_list <- create_mutation_catalogue_from_df(
   lymphoma_test_df,this_seqnames.field = "CHROM",
   this_start.field = "POS",this_end.field = "POS",
   this_PID.field = "PID",this_subgroup.field = "SUBGROUP",
   this_refGenome = BSgenome.Hsapiens.UCSC.hg19,
   this_wordLength = word_length)
   dim(temp_list$matrix)
   head(temp_list$matrix)

Description

This function creates a mutational catalogue from a VRanges Object by first calling mutationContext to establish the motif context of the variants in the input VRanges and then calling motifMatrix to build the mutational catalogue V.

Usage

create_mutation_catalogue_from_VR(
  in_vr,
  in_refGenome,
  in_wordLength,
  in_PID.field = "PID",
  in_verbose = 0,
  in_rownames = c(),
  adapt_rownames = 1
)

Arguments

Value

A list with entries matrix, frame,

• matrix: The mutational catalogue V

• frame: Additional and meta information on rownames (features), colnames (PIDs) and subgroup attribution.

See Also

mutationContext

motifMatrix

Examples

library(BSgenome.Hsapiens.UCSC.hg19)
 data(lymphoma_test)
 data(sigs)
 word_length <- 3
 temp_vr <- makeVRangesFromDataFrame(
   lymphoma_test_df,in_seqnames.field="CHROM",
   in_subgroup.field="SUBGROUP",verbose_flag=1)
 temp_list <- create_mutation_catalogue_from_VR(
   temp_vr,in_refGenome=BSgenome.Hsapiens.UCSC.hg19,
   in_wordLength=word_length,in_PID.field="PID",
   in_verbose=1)
 dim(temp_list$matrix)
 head(temp_list$matrix)
 test_list <- split(lymphoma_test_df,f=lymphoma_test_df$PID)
 other_list <- list()
 for(i in seq_len(length(test_list))){
   other_list[[i]] <- test_list[[i]][c(1:80),]
 }
 other_df <- do.call(rbind,other_list)
 other_vr <- makeVRangesFromDataFrame(
   other_df,in_seqnames.field="CHROM",
   in_subgroup.field="SUBGROUP",verbose_flag=1)
 other_list <- create_mutation_catalogue_from_VR(
   other_vr,in_refGenome=BSgenome.Hsapiens.UCSC.hg19,
   in_wordLength=word_length,in_PID.field="PID",
   in_verbose=1,in_rownames=rownames(AlexCosmicValid_sig_df))
 dim(other_list$matrix)
 head(other_list$matrix)

Description

In this wrapper function for the known cut function, the breaks vector need not be supplied directly, instead, for every break, an interval is supplied and the function optimizes the choice of the breakpoint by chosing a local minimum of the distribution.

Usage

cut_breaks_as_intervals(
  in_vector,
  in_outlier_cutoffs = c(0, 3000),
  in_cutoff_ranges_list = list(c(60, 69), c(25, 32)),
  in_labels = c("late", "intermediate", "early"),
  in_name = "",
  output_path = NULL
)

Arguments

Value

A list with entries category_vector, and density_plot and cutoffs

• category_vector: Factor vector of the categories or strata, of the same length as in_vector

• density_plot: Density plot produced by the density function and indication of the chosen cutoffs.

• cutoffs: Vector of the computed optimal cutoffs

See Also

cut

density

Examples

data(lymphoma_test)
 lymphoma_test_df$random_norm <- rnorm(dim(lymphoma_test_df)[1])
 temp_list <- cut_breaks_as_intervals(
   lymphoma_test_df$random_norm,
   in_outlier_cutoffs=c(-4,4),
   in_cutoff_ranges_list=list(c(-2.5,-1.5),c(0.5,1.5)),
   in_labels=c("small","intermediate","big"))
  temp_list$density_plot

Description

Series of data frames with signature-specific cutoffs. All values represent optimal cutoffs. The optimal cutoffs were determined for different choices of parameters in the cost function of the optimization. The row index is equivalent to the ratio between costs for false negative attribution and false positive attribution. The columns correspond to the different signatures. To be used with LCD_complex_cutoff. There are two different sets of cutoffs one for the signatures described by Alexandrov et al.(Natue 2013) and one for the signatures dokumented in Alexandriv et al. (biorxiv 2018). The calculation of the PCAWG signature specific cutoffs was perfomed in a single-sample resolution which are both valid for whole genome and whole exome sequencing data analysis.

cutoffCosmicValid_rel_df: Optimal cutoffs for AlexCosmicValid_sig_df, i.e. COSMIC signatures, only validated, trained on relative exposures.

cutoffCosmicArtif_rel_df: Optimal cutoffs for AlexCosmicArtif_sig_df, i.e. COSMIC signatures, including artifact signatures, trained on relative exposures.

cutoffCosmicValid_abs_df: Optimal cutoffs for AlexCosmicValid_sig_df, i.e. COSMIC signatures, only validated, trained on absolute exposures.

cutoffCosmicArtif_abs_df: Optimal cutoffs for AlexCosmicArtif_sig_df, i.e. COSMIC signatures, including artifact signatures, trained on absolute exposures.

cutoffInitialValid_rel_df: Optimal cutoffs for AlexInitialValid_sig_df, i.e. initially published signatures, only validated signatures, trained on relative exposures.

cutoffInitialArtif_rel_df: Optimal cutoffs for AlexInitialArtif_sig_df, i.e. initially published signatures, including artifact signatures, trained on relative exposures.

cutoffInitialValid_abs_df: Optimal cutoffs for AlexInitialValid_sig_df, i.e. initially published signatures, only validated signatures, trained on absolute exposures.

cutoffInitialArtif_abs_df: Optimal cutoffs for AlexInitialArtif_sig_df, i.e. initially published signatures, including artifact signatures, trained on absolute exposures.

Usage

data(cutoffs)

Author(s)

Daniel Huebschmann [email protected]

Description

cutoffPCAWG_SBS_WGSWES_artifPid_df: Optimal cutoffs for PCAWG_SP_SBS_sigs_Artif_df, i.e. initially published signatures,including artifact signatures, trained in a single-sample resolution.

cutoffPCAWG_SBS_WGSWES_realPid_df: Optimal cutoffs for PCAWG_SP_SBS_sigs_Real_df, i.e. initially published signatures, only validated signatures, trained in a single-sample resolution.

cutoffPCAWG_ID_WGS_Pid_df: Optimal cutoffs for PCAWG_SP_ID_sigs_df, i.e. initially published signatures, signatures, trained in a single-sample resolution.

Usage

data(cutoffs_pcawg)

Author(s)

Lea Jopp-Saile [email protected]

Description

Derive a data frame of type signature_indices_df (additional information for a set of signatures) from a set of given signatures for a set of new signatures.

Usage

deriveSigInd_df(querySigs, subjectSigs, querySigInd = NULL, in_sort = FALSE)

Arguments

Value

An object of type signature_indices_df (additional informatio for a set of signatures) belonging to the set of new signatures.

See Also

relateSigs

Examples

NULL

Description

Add numbered suffixes to redundant entries in a vector

Usage

disambiguateVector(in_vector)

Arguments

Value

The disambiguated vector.

Examples

NULL

Description

Compare exposures from an analysis of mutational signatures in a cohort of interest to exposures computed in a background (e.g. the set of WES and WGS samples from Alexandrov 2013).

Usage

enrichSigs(in_cohort_exposures_df, in_background_exposures_df, in_sig_df)

Arguments

Value

A data frame with counts and p-values from Fisher tests.

Examples

NULL

Description

Data structures used in examples, Indel tests and the Indel signature vignette of the YAPSA package.

Author(s)

Daniel Huebschmann [email protected]

References

https://www.ncbi.nlm.nih.gov/pubmed/23945592

Description

Data structures used in examples, SNV tests and the SNV signature vignette of the YAPSA package.

lymphoma_PID_df: A data frame carrying subgroup information for a subcohort of samples used in the vignette. Data in the vignette is downloaded from ftp://ftp.sanger.ac.uk/pub/cancer/AlexandrovEtAl/somatic_mutation_data/Lymphoma%20B-cell/Lymphoma%20B-cell_clean_somatic_mutations_for_signature_analysis.txt. In the file available under that link somatic point mutation calls from several samples are listed in a vcf-like format. One column encodes the sample the variant was found in. In the vignette we want to restrict the analysis to only a fraction of these involved samples. The data frame lymphoma_PID_df carries the sample identifiers (PID) as rownames and the attributed subgroup in a column called subgroup.

lymphoma_test_df: A data frame carrying point mutation calls. It represents a subset of the data stored in ftp://ftp.sanger.ac.uk/pub/cancer/AlexandrovEtAl/somatic_mutation_data/Lymphoma%20B-cell/Lymphoma%20B-cell_clean_somatic_mutations_for_signature_analysis.txt. In the file available under that link somatic point mutation calls from several samples are listed in a vcf-like format. One column encodes the sample the variant was found in. The data frame lymphoma_test_df has only the variants occuring in the sample identifiers (PIDs) 4112512, 4194218 and 4121361.

lymphoma_Nature2013_raw_df: A data frame carrying point mutation calls. It represents a subset of the data stored in ftp://ftp.sanger.ac.uk/pub/cancer/AlexandrovEtAl/somatic_mutation_data/Lymphoma%20B-cell/Lymphoma%20B-cell_clean_somatic_mutations_for_signature_analysis.txt. In the file available under that link somatic point mutation calls from several samples are listed in a vcf-like format. One column encodes the sample the variant was found in.

lymphoma_Nature2013_COSMIC_cutoff_exposures_df: Data frame with exposures for testing the plot functions. Data taken from ftp://ftp.sanger.ac.uk/pub/cancer/AlexandrovEtAl/somatic_mutation_data/Lymphoma%20B-cell/Lymphoma%20B-cell_clean_somatic_mutations_for_signature_analysis.txt.

rel_lymphoma_Nature2013_COSMIC_cutoff_exposures_df: Data frame with normalized or relative exposures for testing the plot functions. Data taken from ftp://ftp.sanger.ac.uk/pub/cancer/AlexandrovEtAl/somatic_mutation_data/Lymphoma%20B-cell/Lymphoma%20B-cell_clean_somatic_mutations_for_signature_analysis.txt.

COSMIC_subgroups_df: Subgroup information for the data stored in lymphoma_Nature2013_COSMIC_cutoff_exposures_df and rel_lymphoma_Nature2013_COSMIC_cutoff_exposures_df.

chosen_AlexInitialArtif_sigInd_df: Signature information for the data stored in lymphoma_Nature2013_COSMIC_cutoff_exposures_df and rel_lymphoma_Nature2013_COSMIC_cutoff_exposures_df.

chosen_signatures_indices_df: Signature information for the data stored in lymphoma_Nature2013_COSMIC_cutoff_exposures_df and rel_lymphoma_Nature2013_COSMIC_cutoff_exposures_df.

Usage

data(lymphoma_PID)

data(lymphoma_test)

data(lymphoma_Nature2013_raw)

data(lymphoma_cohort_LCD_results)

data(lymphoma_cohort_LCD_results)

data(lymphoma_cohort_LCD_results)

data(lymphoma_cohort_LCD_results)

data(lymphoma_cohort_LCD_results)

Author(s)

Daniel Huebschmann [email protected]

References

https://www.ncbi.nlm.nih.gov/pubmed/23945592

Examples

data(lymphoma_test)
head(lymphoma_test_df)
dim(lymphoma_test_df)
table(lymphoma_test_df$PID)

data(lymphoma_Nature2013_raw)
head(lymphoma_Nature2013_raw_df)
dim(lymphoma_Nature2013_raw_df)

Description

Vector attributing colours to nucleotide exchanges used when displaying SNV information, e.g. in a rainfall plot.

Usage

data(exchange_colour_vector)

Value

A named character vector

Author(s)

Daniel Huebschmann [email protected]

Description

exome_mutCatRaw_df: A data frame in the format of a SNV mutation catalog. The mutational catalog contains SNV variants from a cohort of small-cell lung cancer published by Rudin et al. (Nature Genetics 2012) which was later used in the de novo discovery analysis of mutational signatures in human cancer by Alexandrov et al. (Nature 2013).

Usage

data(smallCellLungCancerMutCat_NatureGenetics2012)

Value

A data fame in the layout of a SNV mutational catalog

References

https://www.nature.com/articles/ng.2405

Examples

data(smallCellLungCancerMutCat_NatureGenetics2012)
head(exome_mutCatRaw_df)
dim(exome_mutCatRaw_df)

Description

Wrapper for enhanced_barplot

Usage

exposures_barplot(
  in_exposures_df,
  in_signatures_ind_df = NULL,
  in_subgroups_df = NULL,
  in_sum_ind = NULL,
  in_subgroups.field = "subgroup",
  in_title = "",
  in_labels = TRUE,
  in_show_subgroups = TRUE,
  ylab = NULL,
  in_barplot_borders = TRUE,
  in_column_anno_borders = FALSE
)

Arguments

Value

The generated barplot - a ggplot2 plot

Examples

data(lymphoma_cohort_LCD_results)
 exposures_barplot(lymphoma_Nature2013_COSMIC_cutoff_exposures_df,
                   chosen_signatures_indices_df,
                   COSMIC_subgroups_df)

Description

Return gene names from gene lists

Usage

extract_names_from_gene_list(in_KEGG_gene_list, l)

Arguments

Value

The gene name.

See Also

keggGet

build_gene_list_for_pathway

Examples

NULL

Description

Find samples affected by SNVs in a certain pathway

Usage

find_affected_PIDs(in_gene_list, in_gene_vector, in_PID_vector)

Arguments

Value

A character vector of the names of the affected samples

Examples

NULL

Description

GenomeOfNl_raw: A data frame contains the gemiline varinats of the dutch population. carrying point mutation calls. It represents a subset of the data stored in ftp://ftp.sanger.ac.uk/pub/cancer/AlexandrovEtAl/somatic_mutation_data/Lymphoma%20B-cell/Lymphoma%20B-cell_clean_somatic_mutations_for_signature_analysis.txt. In the file available under that link somatic point mutation calls from several samples are listed in a vcf-like format. One column encodes the sample the variant was found in.

Usage

data(GenomeOfNl_raw)

Value

A data frame in a vcf-like format

References

release version 5 https://www.nlgenome.nl/menu/main/app-go-nl/?page_id=9

Examples

data(GenomeOfNl_raw)
head(GenomeOfNl_raw)
dim(GenomeOfNl_raw)

Description

For all signatures found in a project, this function returns the sample identifiers (PIDs) with extremely high or extremely low exposures of the respective signatures.

Usage

get_extreme_PIDs(in_exposures_df, in_quantile = 0.03)

Arguments

Value

A data frame with 4 rows per signature (high PIDs, high exposures, low PIDs, low exposures); the number of columns depends on the quantile chosen.

Examples

data(lymphoma_cohort_LCD_results)
 get_extreme_PIDs(lymphoma_Nature2013_COSMIC_cutoff_exposures_df,0.05)

Description

Extracts the sequence context up and downstream of a nucleotide position

Usage

getSequenceContext(position, chr, offsetL = 10, offsetR = 50)

Arguments

Value

Returns a character string containing the defined seqeunce context

Examples

library(Biostrings)
library(BSgenome.Hsapiens.UCSC.hg19)

sequence_context <- getSequenceContext(position = 123456789, chr = "chr12",
                                       offsetL= 10, offsetR=50)
sequence_context

Description

The PIDs are clustered according to their signature exposures by calling first creating a distance matrix:

• dist, then

• hclust and then

• labels_colors to colour the labels (the text) of the leaves in the dendrogram.

Typically one colour per subgroup.

Usage

hclust_exposures(
  in_exposures_df,
  in_subgroups_df,
  in_method = "manhattan",
  in_subgroup_column = "subgroup",
  in_palette = NULL,
  in_cutoff = 0,
  in_filename = NULL,
  in_shift_factor = 0.3,
  in_cex = 0.2,
  in_title = "",
  in_plot_flag = FALSE
)

Arguments

Value

A list with entries hclust and dendrogram.

• hclust: The object created by hclust

• dendrogram: The above object wrapped in as.dendrogram

See Also

hclust

dist

labels_colors

Examples

data(lymphoma_cohort_LCD_results)
 hclust_exposures(rel_lymphoma_Nature2013_COSMIC_cutoff_exposures_df,
                  COSMIC_subgroups_df,
                  in_method="manhattan",
                  in_subgroup_column="subgroup")

Description

LCD performs a mutational signatures decomposition of a given mutational catalogue V with known signatures W by solving the minimization problem $min(||W*H - V||)$ with additional constraints of non-negativity on H where W and V are known

Usage

LCD(in_mutation_catalogue_df, in_signatures_df, in_per_sample_cutoff = 0)

Arguments

Value

The exposures H, a numeric data frame with l rows and m columns, l being the number of signatures and m being the number of samples

See Also

lsei

Examples

## define raw data
W_prim <- matrix(c(1,2,3,4,5,6),ncol=2)
W_prim_df <- as.data.frame(W_prim)
W_df <- YAPSA:::normalize_df_per_dim(W_prim_df,2) # corresponds to the sigs
W <- as.matrix(W_df)
## 1. Simple case: non-negativity already in raw data
H <- matrix(c(2,5,3,6,1,9,1,2),ncol=4)
H_df <- as.data.frame(H) # corresponds to the exposures
V <- W %*% H # matrix multiplication
V_df <- as.data.frame(V) # corresponds to the mutational catalogue
exposures_df <- YAPSA:::LCD(V_df,W_df)
## 2. more complicated: raw data already contains negative elements
## define indices where sign is going to be swapped
sign_ind <- c(5,7)
## now compute the indices of the other fields in the columns affected
## by the sign change
row_ind <- sign_ind %% dim(H)[1]
temp_ind <- 2*row_ind -1
other_ind <- sign_ind + temp_ind
## alter the matrix H to yield a new mutational catalogue
H_compl <- H
H_compl[sign_ind] <- (-1)*H[sign_ind]
H_compl_df <- as.data.frame(H_compl) # corresponds to the exposures
V_compl <- W %*% H_compl # matrix multiplication
V_compl_df <- as.data.frame(V_compl) # corresponds to the mutational catalog
exposures_df <- YAPSA:::LCD(V_compl_df,W_df)
exposures <- as.matrix(exposures_df)

Description

LCD_cutoff performs a mutational signatures decomposition by Linear Combination Decomposition (LCD) of a given mutational catalogue V with known signatures W by solving the minimization problem $min(||W*H - V||)$ with additional constraints of non-negativity on H where W and V are known, but excludes signatures with an overall contribution less than a given signature-specific cutoff (and thereby accounting for a background model) over the whole cohort.

LCD_complex_cutoff_perPID is a wrapper for LCD_complex_cutoff and runs individually for every PID.

LCD_extractCohort_callPerPID runs LCD_complex_cutoff and takes the identified signatures as input for LCD_complex_cutoff_perPID.

LCD_complex_cutoff_consensus calls LCD_complex_cutoff_combined AND LCD_complex_cutoff_perPID and makes a consensus signature call set.

LCD_complex_cutoff_combined is a wrapper for LCD_complex_cutoff, LCD_complex_cutoff_perPID, LCD_complex_cutoff_consensus AND LCD_extractCohort_callPerPID.

Usage

LCD_complex_cutoff(
  in_mutation_catalogue_df,
  in_signatures_df,
  in_cutoff_vector = NULL,
  in_filename = NULL,
  in_method = "abs",
  in_per_sample_cutoff = 0,
  in_rescale = TRUE,
  in_sig_ind_df = NULL,
  in_cat_list = NULL
)

LCD_complex_cutoff_perPID(
  in_mutation_catalogue_df,
  in_signatures_df,
  in_cutoff_vector = NULL,
  in_filename = NULL,
  in_method = "abs",
  in_rescale = TRUE,
  in_sig_ind_df = NULL,
  in_cat_list = NULL,
  minimumNumberOfAlterations = 25
)

LCD_extractCohort_callPerPID(
  in_mutation_catalogue_df,
  in_signatures_df,
  in_cutoff_vector = NULL,
  in_filename = NULL,
  in_method = "abs",
  in_rescale = TRUE,
  in_sig_ind_df = NULL,
  in_cat_list = NULL,
  in_verbose = FALSE,
  minimumNumberOfAlterations = 25,
  cutoff_type = "adaptive"
)

LCD_complex_cutoff_consensus(
  in_mutation_catalogue_df = NULL,
  in_signatures_df = NULL,
  in_cutoff_vector = NULL,
  in_filename = NULL,
  in_method = "abs",
  in_rescale = TRUE,
  in_sig_ind_df = NULL,
  in_cat_list = NULL,
  in_cohort_LCDlist = NULL,
  in_perPID_LCDlist = NULL,
  addSigs_cohort_cutoff = 0.25,
  addSigs_perPID_cutoff = 0.25,
  addSigs_relAbs_cutoff = 0.01,
  keep.unassigned = FALSE,
  keep.all.cohort.sigs = TRUE,
  in_verbose = FALSE,
  minimumNumberOfAlterations = 25
)

LCD_complex_cutoff_combined(
  in_mutation_catalogue_df = NULL,
  in_signatures_df = NULL,
  in_cutoff_vector = NULL,
  in_filename = NULL,
  in_method = "abs",
  in_rescale = TRUE,
  in_sig_ind_df = NULL,
  in_cat_list = NULL,
  addSigs_cohort_cutoff = 0.25,
  addSigs_perPID_cutoff = 0.25,
  addSigs_relAbs_cutoff = 0.01,
  keep.all.cohort.sigs = TRUE,
  in_verbose = FALSE,
  minimumNumberOfAlterations = 25,
  cutoff_type = "adaptive"
)

Arguments

Value

A list with entries:

• exposures: The exposures H, a numeric data frame with l rows and m columns, l being the number of signatures and m being the number of samples

• norm_exposures: The normalized exposures H, a numeric data frame with l rows and m columns, l being the number of signatures and m being the number of samples

• signatures: The reduced signatures that have exposures bigger than in_cutoff

• choice: Index vector of the reduced signatures in the input signatures

• order: Order vector of the signatures by exposure

• residual_catalogue: Numerical data frame (matrix) of the difference between fit (product of signatures and exposures) and input mutational catalogue

• rss: Residual sum of squares (i.e. sum of squares of the residual catalogue)

• cosDist_fit_orig_per_matrix: Cosine distance between the fit (product of signatures and exposures) and input mutational catalogue computed after putting the matrix into vector format (i.e. one scaler product for the whole matrix)

• cosDist_fit_orig_per_col: Cosine distance between the fit (product of signatures and exposures) and input mutational catalogue computed per column (i.e. per sample, i.e. as many scaler products as there are samples in the cohort)

• sum_ind: Decreasing order of mutational loads based on the input mutational catalogue

• out_sig_ind_df: Data frame of the type signature_indices_df, i.e. indicating name, function and meta-information of the signatures. Default is NULL, non-NULL only if in_sig_ind_df is non-NULL.

• aggregate_exposures_list: List of exposure data frames aggregated over different categories. Default is NULL, non-NULL only if in_sig_ind_df and in_cat_list are non-NULL and if the categories specified in in_cat_list are among the column names of in_sig_ind_df.

See Also

LCD

aggregate_exposures_by_category

lsei

Examples

NULL

Description

CD stratification analysis

Usage

LCD_SMC(in_mutation_sub_catalogue_list, in_signatures_df, in_F_df = NULL)

Arguments

Value

Returns a list with all exposures and the stratified ones

Description

Compute a likelihood ratio test based on the loglikelihoods of the residuals of two different models of the same data.

Usage

logLikelihood(
  in_1,
  in_2,
  df_1 = NULL,
  df_2 = NULL,
  in_pdf = NULL,
  verbose = FALSE
)

Arguments

Value

A list with entries

• statistic: The test statistic

• delta_df: The difference in degrees of freedom between input model 1 and 2

• p.value: p value of the statistical test.

Examples

library(BSgenome.Hsapiens.UCSC.hg19)
 data(lymphoma_test)
 data(sigs)
 data(cutoffs)
 word_length <- 3
 temp_list <- create_mutation_catalogue_from_df(
   lymphoma_test_df,this_seqnames.field = "CHROM",
   this_start.field = "POS",this_end.field = "POS",
   this_PID.field = "PID",this_subgroup.field = "SUBGROUP",
   this_refGenome = BSgenome.Hsapiens.UCSC.hg19,
   this_wordLength = word_length)
 lymphoma_catalogue_df <- temp_list$matrix
 lymphoma_PIDs <- colnames(lymphoma_catalogue_df)
 current_sig_df <- AlexCosmicValid_sig_df
 current_sigInd_df <- AlexCosmicValid_sigInd_df
 current_cutoff_vector <- cutoffCosmicValid_rel_df[6, ]
 iniLCDList <- LCD_complex_cutoff(
   in_mutation_catalogue_df = lymphoma_catalogue_df[, 1, drop = FALSE],
   in_signatures_df = current_sig_df,
   in_cutoff_vector = current_cutoff_vector,
   in_method = "relative", in_rescale = TRUE,
   in_sig_ind_df = current_sigInd_df)
 current_sig_df <- AlexCosmicValid_sig_df[, -9]
 current_sigInd_df <- AlexCosmicValid_sigInd_df[-9,]
 current_cutoff_vector <- cutoffCosmicValid_rel_df[6, -9]
 redLCDList <- LCD_complex_cutoff(
   in_mutation_catalogue_df = lymphoma_catalogue_df[, 1, drop = FALSE],
   in_signatures_df = current_sig_df,
   in_cutoff_vector = current_cutoff_vector,
   in_method = "relative", in_rescale = TRUE,
   in_sig_ind_df = current_sigInd_df)
 logLikelihood(iniLCDList, redLCDList)

Description

lymphomaNature2013_mutCat_df: A data frame in the format of a SNV mutation catalog. The mutational catalog contains SNV variants from the lymphoma_Nature2013_raw_df data. Mutational catalog was created with create_mutation_catalogue_from_df function.

Usage

data(lymphomaNature2013_mutCat_df)

Value

A data fame in the layout of a SNV mutational catalog

References

ftp://ftp.sanger.ac.uk/pub/cancer/AlexandrovEtAl/somatic_mutation_data/Lymphoma%20B-cell/Lymphoma%20B-cell_clean_somatic_mutations_for_signature_analysis.txt

Examples

data(lymphomaNature2013_mutCat_df)
head(lymphomaNature2013_mutCat_df)
dim(lymphomaNature2013_mutCat_df)

Description

For a comparison of the strata from different orthogonal stratification axes, i.e. othogonal SMCs, the strata have to be grouped and reformatted. This function does this task for the comparison by cosine similarity of mutational catalogues. Output of this function is the basis for applying make_comparison_matrix. It is called by the wrapper function run_comparison_catalogues.

Usage

make_catalogue_strata_df(
  in_stratification_lists_list,
  in_additional_stratum = NULL
)

Arguments

Value

A list with entries strata_df, number_of_SMCs, number_of_strata.

• strata_df: Pasted numerical data frame of all strata (these are going to be compared e.g. by make_comparison_matrix).

• number_of_SMCs: Number of orthogonal stratifications in in_stratification_lists_list and additional ones.

• number_of_strata: Cumulative number of strata (sum over the numbers of strata of the different stratifications in in_stratification_lists_list) and additional ones.

See Also

plot_strata

make_comparison_matrix

run_comparison_catalogues

Examples

NULL

Description

Compute and plot a similarity matrix for different strata from different stratification axes together. First, compare_sets is called on in_strata_df with itself, yielding a distance matrix (a numerical data frame) dist_df of the strata. The corresponding similarity matrix 1-dif_df is then passed to corrplot.

Usage

make_comparison_matrix(
  in_strata_df,
  output_path = NULL,
  in_nrect = 5,
  in_attribute = "",
  in_palette = NULL
)

Arguments

Value

The comparison matrix of cosine similarities.

See Also

compare_SMCs

Examples

data(sigs)
make_comparison_matrix(
 AlexCosmicValid_sig_df,in_nrect=9,
 in_palette=colorRampPalette(c("blue","green","red"))(n=100))

Description

For a comparison of the strata from different orthogonal stratification axes, i.e. othogonal SMCs, the strata have to be grouped and reformatted. This function does this task for the comparison by cosine similarity of signature exposures. Output of this function is the basis for applying plot_strata and make_comparison_matrix. It is called by the wrapper functions compare_SMCs, run_plot_strata_general or run_comparison_general.

Usage

make_strata_df(
  in_stratification_lists_list,
  in_remove_signature_ind = NULL,
  in_additional_stratum = NULL
)

Arguments

Value

A list with entries strata_df, number_of_SMCs, number_of_strata.

• strata_df: Pasted numerical data frame of all strata (these are going to be compared e.g. by make_comparison_matrix).

• number_of_SMCs: Number of orthogonal stratifications in in_stratification_lists_list and additional ones.

• number_of_strata: Cumulative number of strata (sum over the numbers of strata of the different stratifications in in_stratification_lists_list) and additional ones.

See Also

plot_strata

make_comparison_matrix

compare_SMCs

run_plot_strata_general

run_comparison_general

Examples

NULL

Description

Creates a data frame carrying the subgroup information and the order in which the PIDs have to be displayed. Calls aggregate on in_vcf_like_df.

Usage

make_subgroups_df(
  in_vcf_like_df,
  in_exposures_df = NULL,
  in_palette = NULL,
  in_subgroup.field = "SUBGROUP",
  in_PID.field = "PID",
  in_verbose = FALSE
)

Arguments

Value

subgroups_df: A data frame carrying the subgroup and rank information.

See Also

aggregate

Examples

data(lymphoma_test)
 data(lymphoma_cohort_LCD_results)
 choice_ind <- (names(lymphoma_Nature2013_COSMIC_cutoff_exposures_df)
                %in% unique(lymphoma_test_df$PID))
 lymphoma_test_exposures_df <-
   lymphoma_Nature2013_COSMIC_cutoff_exposures_df[,choice_ind]
 make_subgroups_df(lymphoma_test_df,lymphoma_test_exposures_df)

Description

In this package, big data frames are generated from cohort wide vcf-like files. This function constructs a VRanges object from such a data frame by using makeGRangesFromDataFrame from the package GenomicRanges

Usage

makeVRangesFromDataFrame(
  in_df,
  in_keep.extra.columns = TRUE,
  in_seqinfo = NULL,
  in_seqnames.field = "X.CHROM",
  in_start.field = "POS",
  in_end.field = "POS",
  in_PID.field = "PID",
  in_subgroup.field = "subgroup",
  in_strand.field = "strand",
  verbose_flag = 1
)

Arguments

Value

The constructed VRanges object

See Also

makeGRangesFromDataFrame

Examples

data(lymphoma_test)
 temp_vr <- makeVRangesFromDataFrame(lymphoma_test_df,
                                     in_seqnames.field="CHROM",
                                     in_subgroup.field="SUBGROUP",
                                     verbose_flag=1)

Description

Melt an exposure data frame with signatures as ID variables.

Usage

melt_exposures(in_df)

Arguments

Value

A data frame with the molten exposures.

Examples

NULL

Description

Merges with the special feature of preserving the signatures and signature order.

Usage

merge_exposures(in_exposures_list, in_signatures_df)

Arguments

Value

A data frame with the merged exposures.

Examples

NULL

Description

MutCat_indel_df: A data frame in the format of a mutation catalog. The mutational catalog contains Indel variants from the GenomeOfNl_raw data. Variants were random sampled for 15 artificial patient for the purpose to have a Indel mutational catalog and have to show the functionality of the package. The results of the mutational catalog should not be interpreted fot they biological relevance. Mutational catalog was created with create_indel_mutation_catalogue_from_df function.

Usage

data(GenomeOfNl_MutCat)

Value

A data fame in the layout of a Indel mutational catalog

References

Mutational catalog created form release version 5 of the Genome of NL https://www.nlgenome.nl/menu/main/app-go-nl/?page_id=9

Examples

data(GenomeOfNl_MutCat)
head(MutCat_indel_df)
dim(MutCat_indel_df)

Description

normalize_df_per_dim: Normalization is carried out by dividing by rowSums or colSums; for rows with rowSums=0 or columns with colSums=0, the normalization is left out.

average_over_present: If averaging over columns, zero rows (i.e. those with rowSums=0) are left out, if averaging over rows, zero columns (i.e. those with colSums=0) are left out.

sd_over_present: If computing the standard deviation over columns, zero rows (i.e. those with rowSums=0) are left out, if computing the standard deviation over rows, zero columns (i.e. those with colSums=0) are left out.

stderrmean_over_present: If computing the standard error of the mean over columns, zero rows (i.e. those with rowSums=0) are left out, if computing the standard error of the mean over rows, zero columns (i.e. those with colSums=0) are left out. Uses the function stderrmean

Usage

normalize_df_per_dim(in_df, in_dimension)

average_over_present(in_df, in_dimension)

sd_over_present(in_df, in_dimension)

stderrmean_over_present(in_df, in_dimension)

Arguments

Value

The normalized numerical data frame (normalize_df_per_dim)

A vector of the means (average_over_present)

A vector of the standard deviations (sd_over_present)

A vector of the standard errors of the mean (stderrmean_over_present)

See Also

stderrmean

Examples

test_df <- data.frame(matrix(c(1,2,3,0,5,2,3,4,0,6,0,0,0,0,0,4,5,6,0,7),
                             ncol=4))
## 1. Normalize over rows:
normalize_df_per_dim(test_df,1)
## 2. Normalize over columns:
normalize_df_per_dim(test_df,2)

test_df <- data.frame(matrix(c(1,2,3,0,5,2,3,4,0,6,0,0,0,0,0,4,5,6,0,7),
                             ncol=4))
## 1. Average over non-zero rows:
average_over_present(test_df,1)
## 2. Average over non-zero columns:
average_over_present(test_df,2)

test_df <- data.frame(matrix(c(1,2,3,0,5,2,3,4,0,6,0,0,0,0,0,4,5,6,0,7),
                             ncol=4))
## 1. Compute standard deviation over non-zero rows:
sd_over_present(test_df,1)
## 2. Compute standard deviation over non-zero columns:
sd_over_present(test_df,2)

test_df <- data.frame(matrix(c(1,2,3,0,5,2,3,4,0,6,0,0,0,0,0,4,5,6,0,7),
                             ncol=4))
## 1. Compute standard deviation over non-zero rows:
stderrmean_over_present(test_df,1)
## 2. Compute standard deviation over non-zero columns:
stderrmean_over_present(test_df,2)

Description

This is a wrapper function to normalizeMotifs. The rownames are first transformed to fit the convention of the SomaticSignatures package and then passed on to the above mentioned function.

Usage

normalizeMotifs_otherRownames(in_matrix, in_norms, adjust_counts = TRUE)

Arguments

Value

The matrix returned by normalizeMotifs, but with rownames transformed back to the convention of the input

Examples

NULL

Description

plot_exposures: The exposures H, determined by NMF or by LCD, are displayed as a stacked barplot by calling

• geom_bar and optionally

• geom_text.

The x-axis displays the PIDs (patient identifier or sample), the y-axis the counts attributed to the different signatures with their respective colours per PID. Is called by plot_relative_exposures.

plot_relative_exposures: Plot the relative or normalized exposures of a cohort. This function first normalizes its input and then sends the normalized data to plot_exposures.

Usage

plot_exposures(
  in_exposures_df,
  in_signatures_ind_df,
  in_subgroups_df = NULL,
  in_sum_ind = NULL,
  in_subgroups.field = "subgroup",
  in_title = "",
  in_labels = TRUE,
  in_show_subgroups = TRUE,
  legend_height = 10
)

plot_relative_exposures(
  in_exposures_df,
  in_signatures_ind_df,
  in_subgroups_df,
  in_sum_ind = NULL,
  in_subgroups.field = "subgroup",
  in_title = "",
  in_labels = TRUE,
  in_show_subgroups = TRUE
)

Arguments

Value

The generated barplot - a ggplot2 plot

See Also

LCD

geom_bar

geom_text

Examples

data(lymphoma_cohort_LCD_results)
 plot_exposures(lymphoma_Nature2013_COSMIC_cutoff_exposures_df,
                chosen_signatures_indices_df,
                COSMIC_subgroups_df)

 data(lymphoma_cohort_LCD_results)
 plot_relative_exposures(lymphoma_Nature2013_COSMIC_cutoff_exposures_df,
                         chosen_signatures_indices_df,
                         COSMIC_subgroups_df)

Description

Plot a big composite figure with 3 columns: in the left column the per-PID absolute exposures will be shown, in the middle column the per_PID relative or normalized exposures will be shown, in the right column the cohort-wide exposures are shown (averaged over PIDs).

Usage

plot_SMC(
  number_of_strata,
  output_path,
  decomposition_method,
  number_of_sigs,
  name_list,
  exposures_strata_list,
  this_signatures_ind_df,
  this_subgroups_df,
  in_strata_order_ind,
  exposures_both_rel_df_list,
  cohort_method_flag,
  fig_width = 1200,
  fig_height = 900,
  fig_type = "png",
  in_label_orientation = "turn",
  this_sum_ind = NULL
)

Arguments

Value

The function doesn't return any value.

Examples

NULL

Description

Plot the cohort wide signature exposures of all strata from different stratification axes together. Naturally called by compare_SMCs.

Usage

plot_strata(
  in_strata_list,
  in_signatures_ind_df,
  output_path = NULL,
  in_attribute = ""
)

Arguments

Value

The function doesn't return any value.

See Also

compare_SMCs

Examples

NULL

Description

Plots the spectra of nucleotide exchanges in their triplet contexts. If several columns are present in the input data frame, the spectra are plotted for every column separately.

Usage

plotExchangeSpectra(
  in_catalogue_df,
  in_colour_vector = NULL,
  in_show_triplets = FALSE,
  in_show_axis_title = FALSE,
  in_scales = "free_x",
  in_refLine = NULL,
  in_refAlpha = 0.5,
  in_background = NULL
)

Arguments

Value

The generated barplot - a ggplot2 plot

See Also

geom_bar

facet_grid

Examples

NULL

Description

Plots the spectra of nucelotides in their triplet contexts. If several columns are present in the input data frame, the spectra are ploted for every column seperatly. The function is only suitable for a INDEL spectra and for SNV representation the funtion plotExchangeSpectra should be used.

Usage

plotExchangeSpectra_indel(
  in_catalogue_df,
  in_colour_vector = NULL,
  in_show_indel = FALSE,
  in_show_axis_title = FALSE,
  in_scales = "free_x",
  in_refLine = NULL,
  in_refAlpha = 0.5,
  in_background = NULL
)

Arguments

Value

The generated barplot - a ggplot2 plot

Examples

data(sigs_pcawg)
plotExchangeSpectra_indel(PCAWG_SP_ID_sigs_df[,c(6,8)])

Description

Plot the exposures to extracted signatures including confidence intervals computed e.g. by variateExp.

Usage

plotExposuresConfidence(in_complete_df, in_subgroups_df, in_sigInd_df)

Arguments

Value

The function doesn't return any value but plots instead.

Examples

NULL

Description

Plot the exposures to extracted signatures including the confidence intervals computed e.g. by variateExp

Usage

plotExposuresConfidence_indel(in_complete_df, in_subgroups_df, in_sigInd_df)

Arguments

Value

The function returns a gtable object which can be plotted with plot or grid.draw

Examples

NULL

Description

Note: this function uses read.csv to read vcf-like files into data frames for single samples. As it uses read.csv, the default value for comment.char is "" and not "#" as it would have been for read.table.

Usage

read_entry(
  current_ind,
  in_list,
  header = TRUE,
  in_header = NULL,
  variant_type = "SNV",
  delete.char = NULL,
  ...
)

read_list(in_list, in_parallel = FALSE, header = TRUE, in_header = NULL, ...)

Arguments

Value

A vcf-like data frame

A list with entries:

• vcf_like_df_list: List of the read data frames

• readVcf_time: Object of class proc_time, which stores the time needed for reading in the data

Examples

NULL

 NULL

Description

Make unique assignments between a set of given signatures and a set of new signatures.

Usage

relateSigs(querySigs, subjectSigs)

Arguments

Value

A list of comparison vectors

See Also

compare_sets

disambiguateVector

Examples

NULL

Description

Create a data frame with default values

Usage

repeat_df(in_value, in_rows, in_cols)

Arguments

Value

The created data frame

Examples

## 1. Initialize with numeric value:
repeat_df(1,2,3)
## 2. Initialize with NA value:
repeat_df(NA,3,2)
## 3. Initialize with character:
repeat_df("a",4,3)

Description

This function is an extension with regard to the function round from base R as it allows not only digits as precision, but can also round to a user-specified precision. The interval in which the rounding operation is to be carried out also can be specified by the user (default is the unit interval). Alternatively, breaks can be provided.

Usage

round_precision(x, breaks = NULL, in_precision = 0.05, in_interval = c(0, 1))

Arguments

Value

A list with two entries:

• values: the rounded vector

• breaks: the breaks used for rounding

Examples

NULL

Description

Wrapper function to the perl script annotate_vcf.pl which annotates data of a track stored in file_B (may be different formats) to called variants stored in a vcf-like file_A.

Usage

run_annotate_vcf_pl(
  in_data_file,
  in_anno_track_file,
  in_new_column_name,
  out_file,
  in_data_file_type = "custom",
  in_anno_track_file_type = "bed",
  in_data_CHROM.field = "CHROM",
  in_data_POS.field = "POS",
  in_data_END.field = "POS"
)

Arguments

Value

Return zero if no problems occur.

Examples

NULL

Description

Compare all strata from different orthogonal stratification axes, i.e. othogonal SMCs by cosine similarity of mutational catalogues. Function similar to run_comparison_general. First calls

• make_catalogue_strata_df, then

• make_comparison_matrix

Usage

run_comparison_catalogues(
  in_stratification_lists_list,
  output_path = NULL,
  in_nrect = 5,
  in_attribute = ""
)

Arguments

Value

The comparison matrix of cosine similarities.

See Also

make_comparison_matrix

run_comparison_general

Examples

NULL

Description

Compare all strata from different orthogonal stratification axes, i.e. othogonal SMCs by cosine similarity of signature exposures. Function similar to compare_SMCs, but without calling plot_strata. First calls

• make_strata_df, then

• make_comparison_matrix

Usage

run_comparison_general(
  in_stratification_lists_list,
  output_path = NULL,
  in_nrect = 5,
  in_attribute = "",
  in_remove_signature_ind = NULL,
  in_additional_stratum = NULL
)

Arguments

Value

The comparison matrix of cosine similarities.

See Also

make_comparison_matrix

compare_SMCs

run_comparison_catalogues

Examples

NULL

Description

This function is analogous to normalizeMotifs. If an analysis of mutational signatures is performed on e.g. Whole Exome Sequencing (WES) data, the signatures and exposures have to be adapted to the potentially different kmer (trinucleotide) content of the target capture. The present function takes as arguments paths to the used reference genome and target capture file. It the extracts the sequence of the target capture by calling bedtools getfasta on the system command prompt. run_kmer_frequency_normalization then calls a custom made perl script kmer_frequencies.pl also included in this package to count the occurences of the tripletts in both the whole reference genome and the created target capture sequence. These counts are used for normalization as in normalizeMotifs. Note that kmerFrequency provides a solution to approximate kmer frequencies by random sampling. As opposed to that approach, the function described here deterministically counts all occurences of the kmers in the respective genome.

Usage

run_kmer_frequency_correction(
  in_ref_genome_fasta,
  in_target_capture_bed,
  in_word_length,
  project_folder,
  target_capture_fasta = "targetCapture.fa",
  in_verbose = 1
)

Arguments

Value

A list with 2 entries:

• rel_cor: The correction factors after normalization as in run_kmer_frequency_normalization

• abs_cor: The correction factors without normalization.

See Also

normalizeMotifs

Examples

NULL

Description

This function is analogous to normalizeMotifs. If an analysis of mutational signatures is performed on e.g. Whole Exome Sequencing (WES) data, the signatures and exposures have to be adapted to the potentially different kmer (trinucleotide) content of the target capture. The present function takes as arguments paths to the used reference genome and target capture file. It the extracts the sequence of the target capture by calling bedtools getfasta on the system command prompt. run_kmer_frequency_normalization then calls a custom made perl script kmer_frequencies.pl also included in this package to count the occurences of the tripletts in both the whole reference genome and the created target capture sequence. These counts are used for normalization as in normalizeMotifs. Note that kmerFrequency provides a solution to approximate kmer frequencies by random sampling. As opposed to that approach, the function described here deterministically counts all occurences of the kmers in the respective genome.

Usage

run_kmer_frequency_normalization(
  in_ref_genome_fasta,
  in_target_capture_bed,
  in_word_length,
  project_folder,
  in_verbose = 1
)

Arguments

Value

A numeric vector with correction factors

See Also

normalizeMotifs

Examples

NULL

Description

First calls

• make_strata_df, then

• plot_strata

Usage

run_plot_strata_general(
  in_stratification_lists_list,
  in_signatures_ind_df,
  output_path = NULL,
  in_attribute = "",
  in_remove_signature_ind = NULL,
  in_additional_stratum = NULL
)