BOBaFIT
2024-10-29
Abstract
Good practices for BOBaFIT package
Package
BOBaFIT 1.10.0
Contents
1 Introduction
The R package BoBafit is composed of four functions which allow the refit and the recalibration of copy number profile of tumor sample. In particular, the package was built to check, and possibly correct, the diploid regions. The wrong diploid region is a phenomenon that very often affects the profiles of samples with a very complex karyotype.
The principal and refitting function was named DRrefit, which - throughout a chromosome clustering method and a list of unaltered chromosomes (chromosome list) - recalibrates the copy number values. BoBafit also contains three secondary functions: ComputeNormalChromosome, which generates the chromosome list; PlotChrCluster, where is possible to visualize the cluster; and Popeye, which affixes its chromosomal arm to each segment (see in “Data Preparation” vignette).
2 Data
The package checks the diploid region assessment working on pre-estimated segment information, as the copy number and their position. We included a data set TCGA_BRCA_CN_segments where are showed all the information necessary. The data correspond to segments about 100 breast tumors samples obtained by the project TCGA-BRCA (Tomczak, Czerwińska, and Wiznerowicz 2015). In the “Data Preparation” vingnette is shown how we download and prepare the dataset for the following analysis.
## Warning: replacing previous import 'ggplot2::geom_segment' by
## 'ggbio::geom_segment' when loading 'BOBaFIT'3 BOBaFIT Workflow
Once the dataset has been prepared, the next step is to generate the chromosome list. The chromosome list is a vector containing all chromosomal arm which are the least affected by SCNAs in the tumor analyzed. Together with the clustering, the chromosome list is one the operating principles to rewrite the diploid region. The list can be manually created or by using the function ComputeNormalChromosome. We suggest these two sequential steps to allow the right refit and recalibration of sample’s diploid region:
ComputeNormalChromosome()DRrefit()
Here we performed this analysis workflow on the dataset TCGA_BRCA_CN_segments described above.
3.1 ComputeNormalChromosome
The chromosome list is a vector specific for each tumor (type and subtype) . The chromosome arms included in this list must be selected based on how many CNA events they are subject to and how many times their CN falls into a “diploid range”. According to this principle, ComputeNormalChromosome write the chromosome list. The function allows to set the chromosomal alteration rate (tolerance_val), which corresponds to a minimum percentage of alterations that one wants to tolerate per arm.
With a little dataframe (less than 200 samples), we suggest an alteration rate of 5% (0.5) ; on the contrary, With a big dataframe (about 1000 samples), we suggest as maximum rate 20-25% (0.20-0.25) . The function input is a sample cohort with their segments.
Here we performed the function in the data set TCGA_BRCA_CN_segments, using an alteration rate of 25%.
chr_list[1] “10q” “12q” “15q” “2p” “2q” “3p” “4q” “9q”
Storing the result in the variable chr_list, it will be a vector containing the chromosomal arms which present an alteration rate under the indicated tolerance_val value.
The function also plots in the Viewer a histogram where is possible observe the chromosomal alteration rate of each chromosomal arms and which one have been selected in the chromosome list (blue bars). The tolerance value has been set at 0.25 (dotted line).
\end{kframe}\begin{adjustwidth}{}{0mm} \includegraphics[width=100%]{/home/biocbuild/bbs-3.20-bioc/tmpdir/Rtmpr90vsU/Rbuild3a386725d7d771/BOBaFIT/vignettes/BOBaFIT_files/figure-html/chrlist plot-1} \end{adjustwidth}\begin{kframe}
3.2 DRrefit
To create a tumor-specific method that refit and recalibrate the tumor copy number profile, we developed the function DRrefit. It uses as input the sample’s segments - cohort or single sample-, and the chromosome list.
As said before, DRrefit estimates the right diploid region using two operating principle: a clustering function NbClust (Charrad et al. 2014), which allow to estimete the best number of cluster in the sample, and the chromosome list. The clustering method can be sets with the argument clust_method. The options are: “ward.D”, “ward.D2”, “single”, “complete”, “average”, “mcquitty”, “median”, “centroid” and “kmeans”.
In this example, the TCGA_BRCA_CN_segmentsdata table and the chr_list previously generated are used. The default value of maxCN (6) and clust_method (ward.d2) are used.
results <- DRrefit (segments_chort = TCGA_BRCA_CN_segments, chrlist = chr_list)3.2.1 The Dataframes
- The data frame
corrected_segmentsreports the CN corrected of the segments by the correction factor (CR) - value estimated for each sample by the function to correct the diploid region-
results$corrected_segments[1,]| chr | start | end | ID | arm | chrarm | CN | CN_corrected |
|---|---|---|---|---|---|---|---|
| 1 | 62920 | 21996664 | 01428281-1653-4839-b5cf-167bc62eb147 | p | 1p | 1.098 | 1.171 |
It is similar to the input one and report the new CN value of each segment calculated by DRrefit (CN_corrected).
- The data frame
reportcontains all the information about the clustering as the outcome,the number of clusters found in that sample, the chromosome list and the CR used for the adjustment of the diploid region. Sample are also divided in three classes, based on their CR: No changes (CR<0.1); Recalibrated (0.1<CR<0.5); Refitted (CR >0.5). The class label is also reported in the data framereport.
results$report[1,] | sample | clustering | ref_clust_chr | num_clust | correction_factor | correction_class |
|---|---|---|---|---|---|
| 01428281-1653-4839-b5cf-167bc62eb147 | SUCCEDED | 10p, 10q, 11p, 13q, 14q, 15q, 16p, 16q, 17p, 18p, 18q, 19p, 19q, 1p, 20p, 20q, 21q, 22q, 2p, 2q, 3p, 4p, 4q, 5p, 5q, 6p, 6q, 7p, 7q, 8p, 9p, 9q | 3 | 0.0722233 | NO CHANGES |
When the column clustering reports FAIL, it indicates that , NbClust fails the chromosome clustering in that sample. In this case, the sample will not present clusters, so the input chromosome list will be kept as reference . When the column clustering reports SUCCED, NbClust succeeds and and the new chromosome list is chosen. The chromosome list used for each sample are all reported in the column ref_clust_chr.
3.3 DRrefit_plot
Thanks to the function DRrefit_plot is possible appreciate the CN profile before and after the correction made byDRrefit. It makes a plot for each sample with the old and new segments positions. The x-axes represent the chromosomes with their genomic position, and the y-axes the copy number value. Above the plot are reported the sample name, the CR and the chromosomal arm used as reference to estimate the new diploid region.
corrected_segments <- results$corrected_segments
report <- results$report# the plot is diplayed on the R viewer
DRrefit_plot(corrected_segments = corrected_segments,
DRrefit_report = report,
plot_viewer = TRUE,
plot_save = FALSE )
# how to save the plot
DRrefit_plot(corrected_segments = corrected_segments,
DRrefit_report = report,
plot_save = TRUE, plot_format = "pdf", plot_path = "/my_path" )Based on the CR value two plots can be displayed:
- CR ≤ 0.1: the new segment and the old segments are orange and red colored, respectively;
## Warning: The `facets` argument of `facet_grid()` is deprecated as of ggplot2 2.2.0.
## ℹ Please use the `rows` argument instead.
## ℹ The deprecated feature was likely used in the ggbio package.
## Please report the issue at <https://github.com/lawremi/ggbio/issues>.
## This warning is displayed once every 8 hours.
## Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
## generated.## Warning: Removed 81 rows containing missing values or values outside the scale range
## (`geom_segment()`).## Warning: Removed 82 rows containing missing values or values outside the scale range
## (`geom_segment()`).\end{kframe}\begin{adjustwidth}{}{0mm} \includegraphics[width=100%]{/home/biocbuild/bbs-3.20-bioc/tmpdir/Rtmpr90vsU/Rbuild3a386725d7d771/BOBaFIT/vignettes/BOBaFIT_files/figure-html/DRrefit_plot 1-1} \end{adjustwidth}\begin{kframe}
- CR > 0.1: the new segment and the old segments are green and red colored, respectively;
## Warning: Removed 52 rows containing missing values or values outside the scale range
## (`geom_segment()`).## Warning: Removed 48 rows containing missing values or values outside the scale range
## (`geom_segment()`).\end{kframe}\begin{adjustwidth}{}{0mm} \includegraphics[width=100%]{/home/biocbuild/bbs-3.20-bioc/tmpdir/Rtmpr90vsU/Rbuild3a386725d7d771/BOBaFIT/vignettes/BOBaFIT_files/figure-html/DRrefit_plot 2-1} \end{adjustwidth}\begin{kframe}
4 PlotChrCluster
Another accessory function is PlotChrCluster. It can be used to visualize the chromosomal cluster in a single sample or in a sample cohort. The input data is always a .tsv file, as the data frame TCGA_BRCA_CN_segments. The option of clust_method argument are the same of DRrefit(“ward.D”, “ward.D2”, “single”, “complete”, “average”, “mcquitty”, “median”, “centroid” and “kmeans”).
Cluster <- PlotChrCluster(segs = TCGA_BRCA_CN_segments,
clust_method = "ward.D2",
plot_output= TRUE)We suggest to store the output on a variable (in this example we use Cluster) to view and possibly save the data frame generated. The PlotCuster will automatically save the plot in the folder indicated by the variable path of the argument plot_path.
In the PlotChrCluster plot, the chromosomal arms are labeled and colored according to the cluster they belong to. The y-axis reports the arm CN.
4.1 The Dataframes
The outputs report summarizes the outcome of clustering for each sample (fail or succeeded, the number of clusters), similar to DRrefit report output. The second output, plot tables, is a list of data frames (one per sample) and reports in which clustering the chromosomes of the sample have been placed.
head(Cluster$report)
#select plot table per sample
head(Cluster$plot_tables$`01428281-1653-4839-b5cf-167bc62eb147`) knitr::kable(head(Cluster$report)) | sample | clustering | num_clust |
|---|---|---|
| 01428281-1653-4839-b5cf-167bc62eb147 | SUCCEDED | 3 |
| 01bc5261-bf91-4f7b-a6b4-0e727c5e31d2 | SUCCEDED | 2 |
| 05afee4e-9acd-44f1-8a0c-ffa34d772b9c | SUCCEDED | 3 |
| 091f70c0-586a-49e8-a0e5-0b60caa72c1b | SUCCEDED | 3 |
| 0941a978-c8aa-467b-8464-9f979d1f0418 | SUCCEDED | 2 |
#select plot table per sample
knitr::kable(head(Cluster$plot_tables$`01428281-1653-4839-b5cf-167bc62eb147`)) | chr | cluster | CN |
|---|---|---|
| 1p | cluster1 | 1.670236 |
| 1q | cluster2 | 3.140345 |
| 2p | cluster1 | 1.906657 |
| 2q | cluster1 | 1.911449 |
| 3p | cluster1 | 1.996745 |
| 3q | cluster2 | 2.624881 |
Session info
## R version 4.4.1 (2024-06-14)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.1 LTS
##
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.20-bioc/R/lib/libRblas.so
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_GB LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: America/New_York
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] dplyr_1.1.4 BOBaFIT_1.10.0 BiocStyle_2.34.0
##
## loaded via a namespace (and not attached):
## [1] RColorBrewer_1.1-3 rstudioapi_0.17.1
## [3] jsonlite_1.8.9 magrittr_2.0.3
## [5] magick_2.8.5 GenomicFeatures_1.58.0
## [7] farver_2.1.2 rmarkdown_2.28
## [9] BiocIO_1.16.0 zlibbioc_1.52.0
## [11] vctrs_0.6.5 memoise_2.0.1
## [13] Rsamtools_2.22.0 RCurl_1.98-1.16
## [15] base64enc_0.1-3 tinytex_0.53
## [17] htmltools_0.5.8.1 S4Arrays_1.6.0
## [19] progress_1.2.3 curl_5.2.3
## [21] SparseArray_1.6.0 Formula_1.2-5
## [23] sass_0.4.9 bslib_0.8.0
## [25] htmlwidgets_1.6.4 httr2_1.0.5
## [27] plyr_1.8.9 cachem_1.1.0
## [29] GenomicAlignments_1.42.0 lifecycle_1.0.4
## [31] pkgconfig_2.0.3 Matrix_1.7-1
## [33] R6_2.5.1 fastmap_1.2.0
## [35] GenomeInfoDbData_1.2.13 MatrixGenerics_1.18.0
## [37] digest_0.6.37 colorspace_2.1-1
## [39] GGally_2.2.1 AnnotationDbi_1.68.0
## [41] S4Vectors_0.44.0 OrganismDbi_1.48.0
## [43] Hmisc_5.2-0 GenomicRanges_1.58.0
## [45] RSQLite_2.3.7 labeling_0.4.3
## [47] filelock_1.0.3 fansi_1.0.6
## [49] polyclip_1.10-7 httr_1.4.7
## [51] abind_1.4-8 compiler_4.4.1
## [53] withr_3.0.2 bit64_4.5.2
## [55] htmlTable_2.4.3 backports_1.5.0
## [57] BiocParallel_1.40.0 DBI_1.2.3
## [59] ggstats_0.7.0 ggforce_0.4.2
## [61] biomaRt_2.62.0 MASS_7.3-61
## [63] rappdirs_0.3.3 DelayedArray_0.32.0
## [65] rjson_0.2.23 tools_4.4.1
## [67] foreign_0.8-87 nnet_7.3-19
## [69] glue_1.8.0 restfulr_0.0.15
## [71] grid_4.4.1 checkmate_2.3.2
## [73] cluster_2.1.6 reshape2_1.4.4
## [75] generics_0.1.3 gtable_0.3.6
## [77] BSgenome_1.74.0 tidyr_1.3.1
## [79] ensembldb_2.30.0 data.table_1.16.2
## [81] hms_1.1.3 xml2_1.3.6
## [83] utf8_1.2.4 XVector_0.46.0
## [85] BiocGenerics_0.52.0 pillar_1.9.0
## [87] stringr_1.5.1 tweenr_2.0.3
## [89] BiocFileCache_2.14.0 lattice_0.22-6
## [91] rtracklayer_1.66.0 bit_4.5.0
## [93] biovizBase_1.54.0 RBGL_1.82.0
## [95] tidyselect_1.2.1 Biostrings_2.74.0
## [97] knitr_1.48 gridExtra_2.3
## [99] bookdown_0.41 ggbio_1.54.0
## [101] IRanges_2.40.0 ProtGenerics_1.38.0
## [103] SummarizedExperiment_1.36.0 stats4_4.4.1
## [105] xfun_0.48 Biobase_2.66.0
## [107] matrixStats_1.4.1 stringi_1.8.4
## [109] UCSC.utils_1.2.0 lazyeval_0.2.2
## [111] yaml_2.3.10 evaluate_1.0.1
## [113] codetools_0.2-20 NbClust_3.0.1
## [115] tibble_3.2.1 graph_1.84.0
## [117] BiocManager_1.30.25 cli_3.6.3
## [119] rpart_4.1.23 munsell_0.5.1
## [121] jquerylib_0.1.4 dichromat_2.0-0.1
## [123] Rcpp_1.0.13 GenomeInfoDb_1.42.0
## [125] dbplyr_2.5.0 png_0.1-8
## [127] XML_3.99-0.17 parallel_4.4.1
## [129] ggplot2_3.5.1 blob_1.2.4
## [131] prettyunits_1.2.0 AnnotationFilter_1.30.0
## [133] plyranges_1.26.0 bitops_1.0-9
## [135] txdbmaker_1.2.0 VariantAnnotation_1.52.0
## [137] scales_1.3.0 purrr_1.0.2
## [139] crayon_1.5.3 rlang_1.1.4
## [141] KEGGREST_1.46.0Reference
Charrad, Malika, Nadia Ghazzali, Véronique Boiteau, and Azam Niknafs. 2014. “NbClust: AnRPackage for Determining the Relevant Number of Clusters in a Data Set.” Journal of Statistical Software 61 (6). https://doi.org/10.18637/jss.v061.i06.
Tomczak, Katarzyna, Patrycja Czerwińska, and Maciej Wiznerowicz. 2015. “Review the Cancer Genome Atlas (Tcga): An Immeasurable Source of Knowledge.” Współczesna Onkologia 1A: 68–77. https://doi.org/10.5114/wo.2014.47136.