[{"_1":2,"_183":-5,"_184":-5},"loaderData",{"_3":4,"_17":18,"_25":26,"_162":163},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","routes/_layout",{"_19":-5,"_20":21,"_22":21,"_23":11,"_24":21},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_88":89,"_111":112,"_151":-5,"_152":11,"_153":21,"_154":11,"_155":-5,"_156":11,"_157":-5,"_158":159,"_160":113,"_161":-7},"canonicalUrl","https://hub.docker.com/r/hdsu/butchr/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","hdsu","reponame","butchr","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":74,"_79":11,"_80":81,"_85":33,"_86":87},"categories",[],"content_types",[44],"image","date_registered","2020-07-15T12:33:01.74009Z","description","Docker image to usr ButchR alongside with RStudio","is_private","last_updated","2023-01-04T06:17:17.145304Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[56],"application/vnd.docker.container.image.v1+json","name","pull_count",1285,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","

\n\n# ButcherR Docker container\n\nTo run the ButcherR Docker image use the following command: \n\ndocker run --rm -p 8787:8787 -e USER=hdsu -e PASSWORD=pass hdsu/butchr\n\nAnd lauch the app in browser:\nhttp://localhost:8787/\n\n# ButchR\n\n`ButchR` is an R package providing functions to perform \nnon-negative matrix factorization and postprocessing using TensorFlow. \n\nhttps://github.com/wurst-theke/ButchR\n\n## Citation \nAndres Quintero, Daniel Hübschmann, Nils Kurzawa, Sebastian Steinhauser, Philipp Rentzsch, Stephen Krämer, Carolin Andresen, Jeongbin Park, Roland Eils, Matthias Schlesner, Carl Herrmann, [ShinyButchR: interactive NMF-based decomposition workflow of genome-scale datasets](https://doi.org/10.1093/biomethods/bpaa022), Biology Methods and Protocols, bpaa022.\n\n\n## ShinyButchR\n\nWe also provide an interactive R/Shiny app `ShinyButchR` to perform NMF and \nexplore the results interactively.\nThe live version can be used here: \nhttps://hdsu-bioquant.shinyapps.io/shinyButchR/\n\nOr a pre-build image can be pulled from Docker:\nhttps://hub.docker.com/r/hdsu/shinybutchr\n\n`docker run --rm -p 3838:3838 hdsu/shinybutchr`\n\n\n\n## How to use ButchR\n\n\n``` r\nlibrary(BiocStyle)\nlibrary(ButchR)\nlibrary(knitr)\nlibrary(ComplexHeatmap)\nlibrary(viridis)\nlibrary(tidyverse)\n```\n\n# Introduction\n\n\n**NMF** (**nonnegative matrix factorization**) is a matrix decomposition\nmethod. A description of the algorithm and it’s implementation can be\nfound e.g. in (Lee and Seung 1999). In 2003, Brunet et al. applied NMF\nto gene expression data (Brunet et al. 2003). In 2010,\n*[NMF](https://CRAN.R-project.org/package=NMF)*, an R package\nimplementing several NMF solvers was published (Gaujoux and Seoighe\n2010). NMF basically solves the problem as illustrated in the following\nfigure (Image taken from\nhttps://en.wikipedia.org/wiki/Non-negative_matrix_factorization):\n\n![NMF](vignettes/figs/ButchR/NMF.png)\n\nHere, *V* is an input matrix with dimensions *n* × *m*. It is decomposed\ninto two matrices *W* of dimension *n* × *l* and *H* of dimension\n*l* × *m*, which when multiplied approximate the original matrix *V*.\n*l* is a free parameter in NMF, it is called the factorization rank. If\nwe call the columns of *W* , then *l* corresponds to the number of\nsignatures. The decomposition thus leads to a reduction in complexity if\n*l* \\< *n*, i.e. if the number of signatures is smaller than the number\nof features, as indicated in the above figure.\n\nIn 2015, Mejia-Roa et al. introduced an implementation of an NMF-solver\nin CUDA, which lead to significant reduction of computation times by\nmaking use of massive parallelisation on GPUs (Mejia-Roa et al. 2015).\nOther implementations of NMF-solvers on GPUs exist.\n\nIt is the pupose of the package `ButchR` described here to provide\nwrapper functions in R to these NMF-solvers in TensorFlow. Massive\nparallelisation not only leads to faster algorithms, but also makes the\nbenefits of NMF accessible to much bigger matrices. Furthermore,\nfunctions for estimation of the optimal factorization rank and post-hoc\nfeature selection are provided.\n\n# The ButchR package\n\n\nThe matrix decomposition results are stored in an S4 object called\n`ButchR_NMF`. `ButchR` provides functions to access the best\nfactorzation after *n* initailization *W* and *H* matrices for a given\nfactorzation rank.\n\nA crucial step in data analysis with NMF is the determination of the\noptimal factorization rank, i.e. the number of columns of the matrix *W*\nor equivalently the number of rows of the matrix *H*. No consensus\nmethod for an automatic evaluation of the optimal factorization rank has\nbeen found to date. Instead, the decomposition is usually performed\niteratively over a range of possible factorization ranks and different\nquality measures are computed for every tested factorization ranks. Many\nquality measures have been proposed:\n\n- The `Frobenius reconstruction error`, i.e. the Frobenius norm of the\n residuals of the decomposition:\n \\|\\|*W* ⋅ *H* − *V*\\|\\|_*F*\n\n- Criteria to assess the stability of the decomposition:\n\n - The `cophenetic correlation coefficient`\n - An `Amari type distance`\n - `Silhouette values` over clusters of patterns extracted\n iteratively at the same factorization rank\n\nThe package `ButchR` provides a function to visualize all factorization\nmetrics.\n\n# Example: leukemia data\n\n\nPreparations\n\nLoad the example data\n\n``` r\ndata(leukemia)\n```\n\nNow we are ready to start an NMF analysis.\n\nNMF analysis\n------------\n\n### Call wrapper function\n\nThe wrapper function for the NMF solvers in the ButchR package is\n`run_NMF_tensor`. It is called as follows:\n\n``` r\nk_min <- 2\nk_max <- 4\n\nleukemia_nmf_exp <- run_NMF_tensor(X = leukemia$matrix,\n ranks = k_min:k_max,\n method = \"NMF\",\n n_initializations = 10, \n extract_features = TRUE)\n```\n\n ## [1] \"2020-07-16 17:50:42 CEST\"\n ## Factorization rank: 2 \n ## [1] \"NMF converged after 75,123,64,69,58,126,141,83,54,87 iterations\"\n ## [1] \"2020-07-16 17:50:42 CEST\"\n ## Factorization rank: 3 \n ## [1] \"NMF converged after 154,79,90,87,66,84,76,151,115,102 iterations\"\n ## [1] \"2020-07-16 17:50:44 CEST\"\n ## Factorization rank: 4 \n ## [1] \"NMF converged after 108,189,202,108,121,76,104,150,110,132 iterations\"\n ## No optimal K could be determined from the Optimal K stat\n\nDepending on the choice of parameters (dimensions of the input matrix,\nnumber of iterations), this step may take some time. Note that the\nalgorithm updates the user about the progress in the iterations.\n\n### normalize W matrix\n\nTo make the features in the *W* matrix comparable, the factorization is\nnormalized to make all columns of *W* sum 1.\n\n``` r\nleukemia_nmf_exp <- normalizeW(leukemia_nmf_exp)\n```\n\nSeveral functions to access the results are available:\n\n### `HMatrix`\n\nReturns the matrix `H` for the optimal decomposition (i.e. the one with\nthe minimal residual) for a specific factorization rank `k`. The number\nof rows of the matrix `H` corresponds to the chosen factorization rank.\n\n``` r\nleukemia_Hk2 <- HMatrix(leukemia_nmf_exp, k = 2)\nclass(leukemia_Hk2)\n```\n\n ## [1] \"matrix\" \"array\"\n\n``` r\ndim(leukemia_Hk2)\n```\n\n ## [1] 2 38\n\n``` r\nkable(leukemia_Hk2[, 1:5])\n```\n\n| ALL001| ALL002| ALL003| ALL004| ALL005|\n|----------:|----------:|----------:|----------:|----------:|\n| 1543455.8| 1356277.8| 1460730.1| 1420151.7| 1286558.2|\n| 229239.7| 281053.9| 280561.9| 298372.2| 257627.2|\n\nIf no value for `k` is supplied, the function returns a list of\nmatrices, one for every factorization rank.\n\n``` r\nleukemia_Hlist <- HMatrix(leukemia_nmf_exp)\nclass(leukemia_Hlist)\n```\n\n ## [1] \"list\"\n\n``` r\nlength(leukemia_Hlist)\n```\n\n ## [1] 3\n\n``` r\nkable(leukemia_Hlist$k2[, 1:5])\n```\n\n| ALL001| ALL002| ALL003| ALL004| ALL005|\n|----------:|----------:|----------:|----------:|----------:|\n| 1543455.8| 1356277.8| 1460730.1| 1420151.7| 1286558.2|\n| 229239.7| 281053.9| 280561.9| 298372.2| 257627.2|\n\n### `WMatrix`\n\nReturns the matrix `W` for the optimal decomposition (i.e. the one with\nthe minimal residual) for a specific factorization rank `k`. The number\nof columns of the matrix `W` corresponds to the chosen factorization\nrank.\n\n``` r\nleukemia_Wk2 <- WMatrix(leukemia_nmf_exp, k = 2)\nclass(leukemia_Wk2)\n```\n\n ## [1] \"matrix\" \"array\"\n\n``` r\ndim(leukemia_Wk2)\n```\n\n ## [1] 4452 2\n\n``` r\nkable(as.data.frame(leukemia_Wk2[1:5, ]))\n```\n\n| | V1| V2|\n|:------|----------:|---------:|\n| A2M | 0.0000453| 6.77e-05|\n| AADAC | 0.0000793| 9.02e-05|\n| AARS | 0.0006768| 1.68e-04|\n| ABAT | 0.0001170| 1.41e-04|\n| ABCA3 | 0.0000322| 8.74e-05|\n\nIf no value for `k` is supplied, the function returns a list of\nmatrices, one for every factorization rank.\n\n``` r\nleukemia_Wlist <- WMatrix(leukemia_nmf_exp)\nclass(leukemia_Wlist)\n```\n\n ## [1] \"list\"\n\n``` r\nlength(leukemia_Wlist)\n```\n\n ## [1] 3\n\n``` r\nkable(as.data.frame(leukemia_Wlist$k2[1:5, ]))\n```\n\n| | V1| V2|\n|:------|----------:|---------:|\n| A2M | 0.0000453| 6.77e-05|\n| AADAC | 0.0000793| 9.02e-05|\n| AARS | 0.0006768| 1.68e-04|\n| ABAT | 0.0001170| 1.41e-04|\n| ABCA3 | 0.0000322| 8.74e-05|\n\n### `FrobError`\n\nReturns a data frame with as many columns as there are iterated\nfactorization ranks and as many rows as there are iterations per\nfactorization rank.\n\n``` r\nkable(FrobError(leukemia_nmf_exp))\n```\n\n| k2| k3| k4|\n|----------:|----------:|----------:|\n| 0.5338607| 0.4778121| 0.4417868|\n| 0.5342311| 0.4779813| 0.4408565|\n| 0.5338451| 0.4783073| 0.4427480|\n| 0.5338433| 0.4781617| 0.4410060|\n| 0.5336356| 0.4780584| 0.4540046|\n| 0.5335016| 0.4781451| 0.4413026|\n| 0.5334857| 0.4779530| 0.4411095|\n| 0.5335520| 0.4783140| 0.4411363|\n| 0.5336552| 0.4779924| 0.4415452|\n| 0.5335182| 0.4787099| 0.4409682|\n\nDetermine the optimal factorization rank\n----------------------------------------\n\nIn NMF, Several methods have been described to assess the optimal\nfactorization rank. The ButchR package implements some of them:\n\n- *Frobenius error:* The most important information about the many\n iterated d ecompositions is the norm of the residual. In NMF this is\n often called the Frobenius error, as the Frobenius norm may be\n used. \n- *Alexandrov Criterion:* In (Alexandrov et al. 2013) an approach is\n described in which a modified silhouette criterion is used to\n estimate the stability across iteration steps for one fixed\n factorization rank `k`. \n- *Cophenetic correlation coefficient* \n- *Amari distance*\n\nThe values of the computed factorization metrics can be accessed with\n`OptKStats`:\n\n``` r\nkable(OptKStats(leukemia_nmf_exp))\n```\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

rank_id	k	min	mean	sd	cv	sumSilWidth	meanSilWidth	copheneticCoeff	meanAmariDist
k2	2	0.5334857	0.5337128	0.0002343	0.0004391	19.95919	0.9979595	0.9964766	0.0008694
k3	3	0.4778121	0.4781435	0.0002538	0.0005307	29.94162	0.9980541	0.9765375	0.0008432
k4	4	0.4408565	0.4426464	0.0040295	0.0091031	37.69052	0.9422630	0.9591708	0.0237371

\n\nThese quality measures can be displayed together:\n\n### Generate plots to estimate optimal k\n\n``` r\ngg_plotKStats(leukemia_nmf_exp)\n```\n\n![](vignettes/figs/ButchR/kstats-1.png)\n\nVisualize the matrix H (exposures)\n----------------------------------\n\nThe matrices `H` may be visualized as heatmaps. We can define a meta\ninformation object and annotate meta data:\n\n``` r\nheat_anno <- HeatmapAnnotation(df = leukemia$annotation[, c(\"ALL_AML\", \"Type\")],\n col = list(ALL_AML = c(\"ALL\" = \"grey80\", \n \"AML\" = \"grey20\"),\n Type = c(\"-\" = \"white\",\n \"B-cell\" = \"grey80\",\n \"T-cell\" = \"grey20\")))\n```\n\nAnd now display the matrices `H` with meta data annotation:\n\n``` r\nfor(ki in k_min:k_max) {\n cat(\"\\n\")\n cat(\" \\n#### H matrix for k=\", ki, \" \\n \")\n #plot H matrix\n tmp_hmatrix <- HMatrix(leukemia_nmf_exp, k = ki)\n h_heatmap <- Heatmap(tmp_hmatrix,\n col = viridis(100),\n name = \"Exposure\",\n clustering_distance_columns = 'pearson',\n show_column_dend = TRUE,\n top_annotation = heat_anno,\n show_column_names = FALSE,\n show_row_names = FALSE,\n cluster_rows = FALSE)\n print(h_heatmap)\n}\n```\n\n#### H matrix for k= 2\n\n![](vignettes/figs/ButchR/hheatmap-1.png)\n\n#### H matrix for k= 3\n\n![](vignettes/figs/ButchR/hheatmap-2.png)\n\n#### H matrix for k= 4\n\n![](vignettes/figs/ButchR/hheatmap-3.png)\n\nFeature selection\n-----------------\n\n### Row K-means to determine signature specific features\n\n``` r\n### Find representative regions.\n# Get W for best K\nleukemia_features <- SignatureSpecificFeatures(leukemia_nmf_exp,\n k = 4, \n return_all_features = TRUE)\ncolnames(leukemia_features) <- paste0(\"Sign.\", 1:4)\nkable(head(leukemia_features))\n```\n\n| | Sign.1| Sign.2| Sign.3| Sign.4|\n|:------|-------:|-------:|-------:|-------:|\n| A2M | 1| 0| 0| 0|\n| AADAC | 0| 0| 0| 1|\n| AARS | 0| 1| 1| 0|\n| ABAT | 0| 0| 0| 1|\n| ABCA3 | 1| 0| 0| 1|\n| ABCA4 | 0| 0| 0| 1|\n\n### Feature visualization\n\n``` r\n# List of signature specific features\n# leukemia_specific <- SignatureSpecificFeatures(leukemia_nmf_exp,\n# k = 4, \n# return_all_features = FALSE)\n\n\nleukemia_specific <- rownames(leukemia_features)[rowSums(leukemia_features) == 1]\nleukemia_Wspecific <- WMatrix(leukemia_nmf_exp, k = 4)[leukemia_specific, ]\ncolnames(leukemia_Wspecific) <- paste0(\"Sign.\", 1:4)\n\n# normalize exposure score in W matrix across rows\nleukemia_Wspecific <- leukemia_Wspecific/matrixStats::rowMaxs(leukemia_Wspecific)\n\n# Display selected features on W matrix\nw_heatmap <- Heatmap(leukemia_Wspecific,\n col = inferno(100),\n name = \"W matrix\",\n clustering_distance_columns = 'pearson',\n show_column_dend = TRUE,\n show_column_names = TRUE,\n show_row_names = FALSE,\n cluster_rows = TRUE,\n cluster_columns = FALSE)\nw_heatmap\n\n```\n\n![](vignettes/figs/ButchR/wspecific-1.png)\n\n\n# References\n\n\nAlexandrov, LB, S Nik-Zainal, DC Wedge, SA Aparicio, S Behjati, AV\nBiankin, GR Bignell, et al. 2013. “Signatures of Mutational Processes in\nCancer.” *Nature*. Nature Publishing Group.\n\nBrunet, Jean-Philippe, Pablo Tamayo, Todd R. Golub, and Jill P. Mesirov.\n2003. “Metagenes and Molecular Pattern Discovery Using Matrix\nFactorization.” *PNAS*. PNAS.\n\nGaujoux, Renaud, and Cathal Seoighe. 2010. “A Flexible R Package for\nNonnegative Matrix Factorization.” *BMC Bioinformatics*. BMC.\n\nLee, Daniel D., and Sebastian Seung. 1999. “Learning the Parts of\nObjects by Non-Negative Matrix Factorization.” *Nature*. Nature\nPublishing Group.\n\nMejia-Roa, Edgardo, Daniel Tabas-Madrid, Javier Setoain, Carlos Garcia,\nFrancisco Tirado, and Alberto Pascual-Montano. 2015. “NMF-mGPU:\nNon-Negative Matrix Factorization on Multi-GPU Systems.” *BMC\nBioinformatics*. BMC.\n","has_starred","hub_user","immutable_tags_settings",{"_75":11,"_76":77},"enabled","rules",[78],".*","is_automated","permissions",{"_82":21,"_83":11,"_84":11},"read","write","admin","user","storage_size",11590401643,"orgData",{"_90":91,"_92":93,"_94":95,"_96":33,"_97":98,"_99":100,"_101":102,"_103":98,"_104":105,"_106":107,"_108":98,"_109":98,"_110":21},"id","529c3d559a5841ebba4387fca1f89d5a","uuid","529c3d55-9a58-41eb-ba43-87fca1f89d5a","type","organization","orgname","full_name","","location","Heidelberg","company","Medical Faculty Heidelberg","profile_url","date_joined","2019-11-26T16:06:48.075312Z","gravatar_url","https://www.gravatar.com/avatar/31b9f4d4199f2312b7048b33d162dfcf?s=80&r=g&d=mm","gravatar_email","badge","is_active","recentTags",[113],{"_114":44,"_115":116,"_117":118,"_119":120,"_90":121,"_122":123,"_50":138,"_139":140,"_141":142,"_143":56,"_57":144,"_145":146,"_147":129,"_148":138,"_149":66,"_150":21},"content_type","creator",5785945,"digest","sha256:cd102fd0e13004e2f55c8b7c0431df9ee7bbc2ecf5261ef63eccf0f5e641c03a","full_size",2125735643,108725957,"images",[124],{"_125":126,"_117":118,"_127":98,"_128":129,"_130":131,"_132":133,"_134":98,"_135":-5,"_136":120,"_63":66,"_137":-5},"architecture","amd64","features","last_pulled","2026-10-01T08:16:22.62863103Z","last_pushed","2023-01-04T06:17:17Z","os","linux","os_features","os_version","size","variant","2023-01-04T06:17:17.007493Z","last_updater",9241642,"last_updater_username","hdsubioquant","media_type","latest","repository",9456180,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":164,"_171":172,"_158":181,"_182":11},{"_40":165,"_42":166,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":167,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":168,"_79":11,"_80":170,"_85":33,"_86":87},[],[44],[56],{"_75":11,"_76":169},[78],{"_82":21,"_83":11,"_84":11},"tags",{"_173":64,"_174":-5,"_175":-5,"_176":177},"count","next","previous","results",[178],{"_114":44,"_115":116,"_117":118,"_119":120,"_90":121,"_122":179,"_50":138,"_139":140,"_141":142,"_143":56,"_57":144,"_145":146,"_147":129,"_148":138,"_149":66,"_150":21},[180],{"_125":126,"_117":118,"_127":98,"_128":129,"_130":131,"_132":133,"_134":98,"_135":-5,"_136":120,"_63":66,"_137":-5},[],"canDeleteTags","actionData","errors"]

hdsu/butchr

Tags for hdsu/butchr