9 | 
10 |
11 |
12 | # Getting started
13 |
14 | ## Installation
15 |
16 |
17 | ### Installing from GitHub
18 |
19 | `cellassign` is built using Google's Tensorflow, and as such requires installation of the R package `tensorflow`:
20 |
21 | ``` r
22 | install.packages("tensorflow")
23 | tensorflow::install_tensorflow(extra_packages='tensorflow-probability', version = "2.1.0")
24 | ```
25 |
26 | Please ensure this installs version 2 of tensorflow. You can check this by calling
27 |
28 | ```r
29 | tensorflow::tf_config()
30 | ```
31 |
32 | ```
33 | TensorFlow v2.1.0 (/usr/local/lib/python3.7/site-packages/tensorflow)
34 | ```
35 |
36 | `cellassign` can then be installed from github:
37 |
38 | ``` r
39 | install.packages("devtools") # If not already installed
40 | devtools::install_github("Irrationone/cellassign")
41 | ```
42 |
43 |
44 | ### Installing from conda
45 |
46 | With [conda](https://conda.io/miniconda.html), install the current release version of `cellassign` as follows:
47 |
48 | ``` r
49 | conda install -c conda-forge -c bioconda r-cellassign
50 | ```
51 |
52 | ## Documentation
53 |
54 | Package documentation can be found [here](https://irrationone.github.io/cellassign/index.html). This includes the following vignettes:
55 |
56 | - [Assigning single-cells to known cell types with CellAssign](https://irrationone.github.io/cellassign/articles/introduction-to-cellassign.html)
57 |
58 | - [Constructing marker genes from purified bulk/scRNA-seq data](https://irrationone.github.io/cellassign/articles/constructing-markers-from-purified-data.html)
59 |
60 | ## Basic usage
61 |
62 | `cellassign` requires the following inputs:
63 |
64 | * `exprs_obj`: Cell-by-gene matrix of raw counts (or SingleCellExperiment with `counts` assay)
65 | * `marker_gene_info`: Binary gene-by-celltype marker gene matrix or list relating cell types to marker genes
66 | * `s`: Size factors
67 | * `X`: Design matrix for any patient/batch specific effects
68 |
69 | The model can be run as follows:
70 |
71 | ``` r
72 | cas <- cellassign(exprs_obj = gene_expression_data,
73 | marker_gene_info = marker_gene_info,
74 | s = s,
75 | X = X)
76 | ```
77 |
78 | An example set of markers for the human tumour microenvironment can be loaded by calling
79 |
80 | ``` r
81 | data(example_TME_markers)
82 |
83 | ```
84 |
85 | Please see the package vignette for details and caveats.
86 |
87 | # Paper
88 |
89 | [Probabilistic cell-type assignment of single-cell RNA-seq for tumor microenvironment profiling, _Nature Methods 2019_](https://www.nature.com/articles/s41592-019-0529-1)
90 |
91 | # Code of Conduct
92 |
93 | Please note that the 'cellassign' project is released with a
94 | [Contributor Code of Conduct](CODE_OF_CONDUCT.md).
95 | By contributing to this project, you agree to abide by its terms.
96 |
97 | # Authors
98 |
99 | Allen W Zhang, University of British Columbia
100 |
101 | Kieran R Campbell, University of British Columbia
102 |
--------------------------------------------------------------------------------
/R/utils.R:
--------------------------------------------------------------------------------
1 |
2 | #' Convert a list of marker genes to a binary matrix
3 | #'
4 | #' Given a list of cell types and marker genes, convert to a binary
5 | #' cell type by gene matrix required by cellassign.
6 | #'
7 | #' This function takes a list of marker genes and converts it to a binary
8 | #' gene by cell type matrix. The input list should be the same
9 | #' length as the number of cell types with names corresponding to cell types.
10 | #' Each element of the list should be a character vector of the genes corresponding
11 | #' to that cell type. There is no requirement for mutually-exclusive marker genes.
12 | #'
13 | #' @param marker_list A list where each entry is named by a cell type and
14 | #' contains a character vector of gene names belonging to that cell type
15 | #' @param include_other If \code{TRUE} adds a column of zeros for cells that do not
16 | #' exhibit high expression of any marker gene to be binned into
17 | #'
18 | #' @return A cell type by gene binary matrix with 1 if a gene is a marker for
19 | #' a cell type and 0 otherwise
20 | #'
21 | #' @examples
22 | #' marker_list <- list(
23 | #' `cell_type_1` = c("geneA", "geneB"),
24 | #' `cell_type_2` = c("geneB", "geneC")
25 | #' )
26 | #' marker_list_to_mat(marker_list)
27 | #'
28 | #' @export
29 | marker_list_to_mat <- function(marker_list, include_other = TRUE) {
30 | cell_types <- names(marker_list)
31 |
32 | if(is.null(cell_types)) {
33 | warning("Marker list has no cell type names - replacing with generics")
34 | cell_types <- paste0("cell_type_", seq_along(marker_list))
35 | names(marker_list) <- cell_types
36 | }
37 |
38 | genes <- sort(unique(unlist(marker_list)))
39 | genes <- genes[nchar(genes) > 0]
40 |
41 | n_cell_types <- length(cell_types)
42 | n_genes <- length(genes)
43 |
44 | mat <- matrix(0, nrow = n_cell_types, ncol = n_genes)
45 | colnames(mat) <- genes
46 | rownames(mat) <- cell_types
47 |
48 | for(cell_type in names(marker_list)) {
49 | mat[cell_type,] <- genes %in% marker_list[[cell_type]]
50 | }
51 |
52 | if(include_other) {
53 | mat <- rbind(mat, `other` = 0)
54 | }
55 |
56 | mat <- t(mat) # Make it gene type by cell
57 |
58 | mat
59 | }
60 |
61 | #' Get MLE estimates of type of each cell
62 | #'
63 | #' @return A vector of MLE cell types, where the names are
64 | #' taken from the column names of the input matrix
65 | #'
66 | #' @keywords internal
67 | get_mle_cell_type <- function(gamma) {
68 | which_max <- apply(gamma, 1, which.max)
69 | colnames(gamma)[which_max]
70 | }
71 |
72 | #' Extract expression matrix from expression object
73 | #'
74 | #' @return The cleaned expression matrix (of counts) from whatever input to \code{cellassign}
75 | #'
76 | #' @keywords internal
77 | extract_expression_matrix <- function(exprs_obj, sce_assay = "counts") {
78 | if(is(exprs_obj, "SummarizedExperiment")) {
79 | Y <- t(as.matrix(SummarizedExperiment::assay(exprs_obj, sce_assay)))
80 | } else if(is.matrix(exprs_obj) && is.numeric(exprs_obj)) {
81 | Y <- exprs_obj
82 | } else {
83 | stop("Input exprs_obj must either be a SummarizedExperiment or numeric matrix of gene expression")
84 | }
85 | return(Y)
86 | }
87 |
88 | #' Create X matrix
89 | #'
90 | #' @importFrom stats var
91 | #'
92 | #' @return A cleaned covariate matrix given the input provided by the user
93 | #'
94 | #' @keywords internal
95 | initialize_X <- function(X, N, verbose = FALSE) {
96 | if(is.null(X)) {
97 | if (N > 0) {
98 | X <- matrix(1, nrow = N)
99 | } else {
100 | X <- matrix(nrow = 0, ncol = 1)
101 | }
102 | } else {
103 | # We can be a little intelligent about whether or not to add an intercept -
104 | # if any column variance of X is 0 then the associated covariate is constant
105 | # so we don't need to add an intercept
106 | col_vars <- apply(X, 2, var)
107 | if(any(col_vars == 0)) {
108 | if(verbose) {
109 | message("Intecept column detected in X")
110 | }
111 | } else {
112 | X <- cbind(1, X)
113 | if(verbose) {
114 | message("No intercept column detected in X - adding")
115 | }
116 | }
117 | }
118 | return(X)
119 | }
120 |
121 |
122 | #' Check for tensorflow
123 | #'
124 | #' @keywords internal
125 | #'
126 | #' @return Installs tensorflow if not already installed
127 | .onLoad <- function(libname, pkgname) {
128 | if(is.null(tensorflow::tf_version())) {
129 | stop("Tensorflow installation not detected. Please run 'tensorflow::install_tensorflow()' to continue...")
130 | }
131 | }
132 |
133 |
--------------------------------------------------------------------------------
/man/cellassign.Rd:
--------------------------------------------------------------------------------
1 | % Generated by roxygen2: do not edit by hand
2 | % Please edit documentation in R/cellassign.R
3 | \name{cellassign}
4 | \alias{cellassign}
5 | \title{Annotate cells to cell types using cellassign}
6 | \usage{
7 | cellassign(
8 | exprs_obj,
9 | marker_gene_info,
10 | s = NULL,
11 | min_delta = 2,
12 | X = NULL,
13 | B = 10,
14 | shrinkage = TRUE,
15 | n_batches = 1,
16 | dirichlet_concentration = 0.01,
17 | rel_tol_adam = 1e-04,
18 | rel_tol_em = 1e-04,
19 | max_iter_adam = 1e+05,
20 | max_iter_em = 20,
21 | learning_rate = 0.1,
22 | verbose = TRUE,
23 | sce_assay = "counts",
24 | return_SCE = FALSE,
25 | num_runs = 1,
26 | threads = 0
27 | )
28 | }
29 | \arguments{
30 | \item{exprs_obj}{Either a matrix representing gene
31 | expression counts or a \code{SummarizedExperiment}.
32 | See details.}
33 |
34 | \item{marker_gene_info}{Information relating marker genes to cell types.
35 | See details.}
36 |
37 | \item{s}{Numeric vector of cell size factors}
38 |
39 | \item{min_delta}{The minimum log fold change a marker gene must
40 | be over-expressed by in its cell type}
41 |
42 | \item{X}{Numeric matrix of external covariates. See details.}
43 |
44 | \item{B}{Number of bases to use for RBF dispersion function}
45 |
46 | \item{shrinkage}{Logical - should the delta parameters
47 | have hierarchical shrinkage?}
48 |
49 | \item{n_batches}{Number of data subsample batches to use in inference}
50 |
51 | \item{dirichlet_concentration}{Dirichlet concentration parameter for cell
52 | type abundances}
53 |
54 | \item{rel_tol_adam}{The change in Q function value (in pct) below which
55 | each optimization round is considered converged}
56 |
57 | \item{rel_tol_em}{The change in log marginal likelihood value (in pct)
58 | below which the EM algorithm is considered converged}
59 |
60 | \item{max_iter_adam}{Maximum number of ADAM iterations
61 | to perform in each M-step}
62 |
63 | \item{max_iter_em}{Maximum number of EM iterations to perform}
64 |
65 | \item{learning_rate}{Learning rate of ADAM optimization}
66 |
67 | \item{verbose}{Logical - should running info be printed?}
68 |
69 | \item{sce_assay}{The \code{assay} from the input#' \code{SingleCellExperiment} to use: this assay
70 | should always represent raw counts.}
71 |
72 | \item{return_SCE}{Logical - should a SingleCellExperiment be returned
73 | with the cell
74 | type annotations added? See details.}
75 |
76 | \item{num_runs}{Number of EM optimizations to perform (the one with the maximum
77 | log-marginal likelihood value will be used as the final).}
78 |
79 | \item{threads}{Maximum number of threads used by the algorithm
80 | (defaults to the number of cores available on the machine)}
81 | }
82 | \value{
83 | An object of class \code{cellassign}. See \code{details}
84 | }
85 | \description{
86 | Automatically annotate cells to known types based
87 | on the expression patterns of
88 | a priori known marker genes.
89 | }
90 | \details{
91 | \strong{Input format}
92 | \code{exprs_obj} should be either a
93 | \code{SummarizedExperiment} (we recommend the
94 | \code{SingleCellExperiment} package) or a
95 | cell (row) by gene (column) matrix of
96 | \emph{raw} RNA-seq counts (do \strong{not}
97 | log-transform or otherwise normalize).
98 |
99 | \code{marker_gene_info} should either be
100 | \itemize{
101 | \item A gene by cell type binary matrix, where a 1 indicates that a gene is a
102 | marker for a cell type, and 0 otherwise
103 | \item A list with names corresponding to cell types, where each entry is a
104 | vector of marker gene names. These are converted to the above matrix using
105 | the \code{marker_list_to_mat} function.
106 | }
107 |
108 | \strong{Cell size factors}
109 | If the cell size factors \code{s} are
110 | not provided they are computed using the
111 | \code{computeSumFactors} function from
112 | the \code{scran} package.
113 |
114 | \strong{Covariates}
115 | If \code{X} is not \code{NULL} then it should be
116 | an \code{N} by \code{P} matrix
117 | of covariates for \code{N} cells and \code{P} covariates.
118 | Such a matrix would typically
119 | be returned by a call to \code{model.matrix}
120 | \strong{with no intercept}. It is also highly
121 | recommended that any numerical (ie non-factor or one-hot-encoded)
122 | covariates be standardized
123 | to have mean 0 and standard deviation 1.
124 |
125 | \strong{cellassign}
126 | A call to \code{cellassign} returns an object
127 | of class \code{cellassign}. To access the
128 | MLE estimates of cell types, call \code{fit$cell_type}.
129 | To access all MLE parameter
130 | estimates, call \code{fit$mle_params}.
131 |
132 | \strong{Returning a SingleCellExperiment}
133 |
134 | If \code{return_SCE} is true, a call to \code{cellassign} will return
135 | the input SingleCellExperiment, with the following added:
136 | \itemize{
137 | \item A column \code{cellassign_celltype} to \code{colData(sce)} with the MAP
138 | estimate of the cell type
139 | \item A slot \code{sce@metadata$cellassign} containing the cellassign fit.
140 | Note that a \code{SingleCellExperiment} must be provided as \code{exprs_obj}
141 | for this option to be valid.
142 | }
143 | }
144 | \examples{
145 | data(example_sce)
146 | data(example_marker_mat)
147 |
148 | fit <- em_result <- cellassign(example_sce[rownames(example_marker_mat),],
149 | marker_gene_info = example_marker_mat,
150 | s = colSums(SummarizedExperiment::assay(example_sce, "counts")),
151 | learning_rate = 1e-2,
152 | shrinkage = TRUE,
153 | verbose = FALSE)
154 |
155 |
156 | }
157 |
--------------------------------------------------------------------------------
/docs/404.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
58 |
59 |
108 |
109 |
110 |
111 |
112 |
113 |
138 |
139 |
140 |
141 |
142 |
143 |
144 |
145 |
146 |
--------------------------------------------------------------------------------
/docs/authors.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
114 |
124 |
125 |
126 |
127 |
137 |
115 |
122 |
123 |
116 |
118 |
119 | Content not found. Please use links in the navbar.
120 |
121 | Page not found (404)
117 |
58 |
59 |
108 |
109 |
110 |
111 |
112 |
113 |
143 |
144 |
145 |
146 |
147 |
148 |
149 |
150 |
151 |
--------------------------------------------------------------------------------
/docs/pkgdown.css:
--------------------------------------------------------------------------------
1 | /* Sticky footer */
2 |
3 | /**
4 | * Basic idea: https://philipwalton.github.io/solved-by-flexbox/demos/sticky-footer/
5 | * Details: https://github.com/philipwalton/solved-by-flexbox/blob/master/assets/css/components/site.css
6 | *
7 | * .Site -> body > .container
8 | * .Site-content -> body > .container .row
9 | * .footer -> footer
10 | *
11 | * Key idea seems to be to ensure that .container and __all its parents__
12 | * have height set to 100%
13 | *
14 | */
15 |
16 | html, body {
17 | height: 100%;
18 | }
19 |
20 | body > .container {
21 | display: flex;
22 | height: 100%;
23 | flex-direction: column;
24 | }
25 |
26 | body > .container .row {
27 | flex: 1 0 auto;
28 | }
29 |
30 | footer {
31 | margin-top: 45px;
32 | padding: 35px 0 36px;
33 | border-top: 1px solid #e5e5e5;
34 | color: #666;
35 | display: flex;
36 | flex-shrink: 0;
37 | }
38 | footer p {
39 | margin-bottom: 0;
40 | }
41 | footer div {
42 | flex: 1;
43 | }
44 | footer .pkgdown {
45 | text-align: right;
46 | }
47 | footer p {
48 | margin-bottom: 0;
49 | }
50 |
51 | img.icon {
52 | float: right;
53 | }
54 |
55 | img {
56 | max-width: 100%;
57 | }
58 |
59 | /* Fix bug in bootstrap (only seen in firefox) */
60 | summary {
61 | display: list-item;
62 | }
63 |
64 | /* Typographic tweaking ---------------------------------*/
65 |
66 | .contents .page-header {
67 | margin-top: calc(-60px + 1em);
68 | }
69 |
70 | /* Section anchors ---------------------------------*/
71 |
72 | a.anchor {
73 | margin-left: -30px;
74 | display:inline-block;
75 | width: 30px;
76 | height: 30px;
77 | visibility: hidden;
78 |
79 | background-image: url(./link.svg);
80 | background-repeat: no-repeat;
81 | background-size: 20px 20px;
82 | background-position: center center;
83 | }
84 |
85 | .hasAnchor:hover a.anchor {
86 | visibility: visible;
87 | }
88 |
89 | @media (max-width: 767px) {
90 | .hasAnchor:hover a.anchor {
91 | visibility: hidden;
92 | }
93 | }
94 |
95 |
96 | /* Fixes for fixed navbar --------------------------*/
97 |
98 | .contents h1, .contents h2, .contents h3, .contents h4 {
99 | padding-top: 60px;
100 | margin-top: -40px;
101 | }
102 |
103 | /* Sidebar --------------------------*/
104 |
105 | #sidebar {
106 | margin-top: 30px;
107 | position: -webkit-sticky;
108 | position: sticky;
109 | top: 70px;
110 | }
111 | #sidebar h2 {
112 | font-size: 1.5em;
113 | margin-top: 1em;
114 | }
115 |
116 | #sidebar h2:first-child {
117 | margin-top: 0;
118 | }
119 |
120 | #sidebar .list-unstyled li {
121 | margin-bottom: 0.5em;
122 | }
123 |
124 | .orcid {
125 | height: 16px;
126 | /* margins are required by official ORCID trademark and display guidelines */
127 | margin-left:4px;
128 | margin-right:4px;
129 | vertical-align: middle;
130 | }
131 |
132 | /* Reference index & topics ----------------------------------------------- */
133 |
134 | .ref-index th {font-weight: normal;}
135 |
136 | .ref-index td {vertical-align: top;}
137 | .ref-index .icon {width: 40px;}
138 | .ref-index .alias {width: 40%;}
139 | .ref-index-icons .alias {width: calc(40% - 40px);}
140 | .ref-index .title {width: 60%;}
141 |
142 | .ref-arguments th {text-align: right; padding-right: 10px;}
143 | .ref-arguments th, .ref-arguments td {vertical-align: top;}
144 | .ref-arguments .name {width: 20%;}
145 | .ref-arguments .desc {width: 80%;}
146 |
147 | /* Nice scrolling for wide elements --------------------------------------- */
148 |
149 | table {
150 | display: block;
151 | overflow: auto;
152 | }
153 |
154 | /* Syntax highlighting ---------------------------------------------------- */
155 |
156 | pre {
157 | word-wrap: normal;
158 | word-break: normal;
159 | border: 1px solid #eee;
160 | }
161 |
162 | pre, code {
163 | background-color: #f8f8f8;
164 | color: #333;
165 | }
166 |
167 | pre code {
168 | overflow: auto;
169 | word-wrap: normal;
170 | white-space: pre;
171 | }
172 |
173 | pre .img {
174 | margin: 5px 0;
175 | }
176 |
177 | pre .img img {
178 | background-color: #fff;
179 | display: block;
180 | height: auto;
181 | }
182 |
183 | code a, pre a {
184 | color: #375f84;
185 | }
186 |
187 | a.sourceLine:hover {
188 | text-decoration: none;
189 | }
190 |
191 | .fl {color: #1514b5;}
192 | .fu {color: #000000;} /* function */
193 | .ch,.st {color: #036a07;} /* string */
194 | .kw {color: #264D66;} /* keyword */
195 | .co {color: #888888;} /* comment */
196 |
197 | .message { color: black; font-weight: bolder;}
198 | .error { color: orange; font-weight: bolder;}
199 | .warning { color: #6A0366; font-weight: bolder;}
200 |
201 | /* Clipboard --------------------------*/
202 |
203 | .hasCopyButton {
204 | position: relative;
205 | }
206 |
207 | .btn-copy-ex {
208 | position: absolute;
209 | right: 0;
210 | top: 0;
211 | visibility: hidden;
212 | }
213 |
214 | .hasCopyButton:hover button.btn-copy-ex {
215 | visibility: visible;
216 | }
217 |
218 | /* headroom.js ------------------------ */
219 |
220 | .headroom {
221 | will-change: transform;
222 | transition: transform 200ms linear;
223 | }
224 | .headroom--pinned {
225 | transform: translateY(0%);
226 | }
227 | .headroom--unpinned {
228 | transform: translateY(-100%);
229 | }
230 |
231 | /* mark.js ----------------------------*/
232 |
233 | mark {
234 | background-color: rgba(255, 255, 51, 0.5);
235 | border-bottom: 2px solid rgba(255, 153, 51, 0.3);
236 | padding: 1px;
237 | }
238 |
239 | /* vertical spacing after htmlwidgets */
240 | .html-widget {
241 | margin-bottom: 10px;
242 | }
243 |
244 | /* fontawesome ------------------------ */
245 |
246 | .fab {
247 | font-family: "Font Awesome 5 Brands" !important;
248 | }
249 |
250 | /* don't display links in code chunks when printing */
251 | /* source: https://stackoverflow.com/a/10781533 */
252 | @media print {
253 | code a:link:after, code a:visited:after {
254 | content: "";
255 | }
256 | }
257 |
--------------------------------------------------------------------------------
/docs/reference/dot-onLoad.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
114 |
130 |
131 |
132 |
142 |
115 |
129 |
116 |
118 |
119 | Articles
117 |
120 |
128 | All vignettes
121 | 122 | 123 | 127 |
60 |
61 |
110 |
111 |
112 |
113 |
114 |
115 |
156 |
157 |
158 |
159 |
160 |
161 |
162 |
163 |
164 |
--------------------------------------------------------------------------------
/docs/reference/initialize_X.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
116 |
143 |
144 |
145 |
155 |
117 |
135 |
142 |
118 |
121 |
122 |
123 | Check for tensorflow
119 | 120 |dot-onLoad.Rd
124 |
126 |
127 | Check for tensorflow
125 |.onLoad(libname, pkgname)128 | 129 | 130 |
Value
131 | 132 |Installs tensorflow if not already installed
133 | 134 |
60 |
61 |
110 |
111 |
112 |
113 |
114 |
115 |
143 |
144 |
145 |
155 |
156 |
157 |
158 |
159 |
160 |
161 |
162 |
163 |
164 |
--------------------------------------------------------------------------------
/docs/reference/get_mle_cell_type.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
60 |
61 |
110 |
111 |
112 |
113 |
114 |
115 |
157 |
158 |
159 |
160 |
161 |
162 |
163 |
164 |
165 |
--------------------------------------------------------------------------------
/docs/reference/extract_expression_matrix.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
116 |
144 |
145 |
146 |
156 |
117 |
136 |
143 |
118 |
121 |
122 |
123 | Get MLE estimates of type of each cell
119 | 120 |get_mle_cell_type.Rd
124 |
126 |
127 | Get MLE estimates of type of each cell
125 |get_mle_cell_type(gamma)128 | 129 | 130 |
Value
131 | 132 |A vector of MLE cell types, where the names are 133 | taken from the column names of the input matrix
134 | 135 |
60 |
61 |
110 |
111 |
112 |
113 |
114 |
115 |
156 |
157 |
158 |
159 |
160 |
161 |
162 |
163 |
164 |
--------------------------------------------------------------------------------
/docs/reference/holik_data.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
116 |
143 |
144 |
145 |
155 |
117 |
135 |
142 |
118 |
121 |
122 |
123 | Extract expression matrix from expression object
119 | 120 |extract_expression_matrix.Rd
124 |
126 |
127 | Extract expression matrix from expression object
125 |extract_expression_matrix(exprs_obj, sce_assay = "counts")128 | 129 | 130 |
Value
131 | 132 |The cleaned expression matrix (of counts) from whatever input to cellassign
61 |
62 |
111 |
112 |
113 |
114 |
115 |
116 |
161 |
162 |
163 |
164 |
165 |
166 |
167 |
168 |
169 |
--------------------------------------------------------------------------------
/docs/reference/example_TME_markers.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
117 |
148 |
149 |
150 |
160 |
118 |
139 |
147 |
119 |
122 |
123 |
124 | Example bulk RNA-seq data
120 | 121 |holik_data.Rd
125 |
128 |
129 | An example bulk RNA-seq dataset from Holik et al. Nucleic Acids Research 2017 to 126 | demonstrate deriving marker genes
127 |holik_data
130 |
131 |
132 | Format
133 | 134 |An object of class list of length 2.
Examples
137 |138 |data(holik_data)
61 |
62 |
111 |
112 |
113 |
114 |
115 |
116 |
161 |
162 |
163 |
164 |
165 |
166 |
167 |
168 |
169 |
--------------------------------------------------------------------------------
/docs/reference/example_sce.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
117 |
148 |
149 |
150 |
160 |
118 |
139 |
147 |
119 |
122 |
123 |
124 | Example tumour microevironment markers
120 | 121 |example_TME_markers.Rd
125 |
128 |
129 | A set of example marker genes for commonly profiling the 126 | human tumour mircoenvironment
127 |example_TME_markers
130 |
131 |
132 | Format
133 | 134 |An object of class list of length 2.
Examples
137 |138 |data(example_TME_markers)
60 |
61 |
110 |
111 |
112 |
113 |
114 |
115 |
163 |
164 |
165 |
166 |
167 |
168 |
169 |
170 |
171 |
--------------------------------------------------------------------------------
/docs/reference/example_cellassign_fit.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
116 |
150 |
151 |
152 |
162 |
117 |
136 |
137 |
140 |
149 |
118 |
121 |
122 |
123 | Example SingleCellExperiment
119 | 120 |example_sce.Rd
124 |
126 |
127 | An example SingleCellExperiment for 10 marker genes and 500 cells.
example_sce
128 |
129 |
130 | Format
131 | 132 |An object of class SingleCellExperiment with 200 rows and 500 columns.
See also
134 | 135 |example_cellassign_fit
Examples
138 |139 |data(example_sce)
61 |
62 |
111 |
112 |
113 |
114 |
115 |
116 |
165 |
166 |
167 |
168 |
169 |
170 |
171 |
172 |
173 |
--------------------------------------------------------------------------------
/docs/reference/example_marker_mat.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
117 |
152 |
153 |
154 |
164 |
118 |
138 |
139 |
142 |
151 |
119 |
122 |
123 |
124 | Example cellassign fit
120 | 121 |example_cellassign_fit.Rd
125 |
128 |
129 | An example fit of calling cellassign on both
126 | example_marker_mat and example_sce
example_cellassign_fit
130 |
131 |
132 | Format
133 | 134 |An object of class cellassign of length 3.
See also
136 | 137 |example_cellassign_fit
Examples
140 |141 |data(example_cellassign_fit)
61 |
62 |
111 |
112 |
113 |
114 |
115 |
116 |
165 |
166 |
167 |
168 |
169 |
170 |
171 |
172 |
173 |
--------------------------------------------------------------------------------
/vignettes/constructing-markers-from-purified-data.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Constructing marker genes from purified scRNA-seq data"
3 | author: "Allen W Zhang and Kieran R Campbell"
4 | date: "April 2019"
5 | package: "cellassign"
6 | output: BiocStyle::html_document
7 | vignette: >
8 | %\VignetteIndexEntry{Constructing marker genes from purified scRNA-seq data}
9 | %\VignetteEngine{knitr::rmarkdown}
10 | %\VignetteEncoding{UTF-8}
11 | ---
12 |
13 | ```{r setup, include = FALSE}
14 | knitr::opts_chunk$set(
15 | collapse = TRUE,
16 | warnings = FALSE,
17 | messages = FALSE,
18 | comment = "#>"
19 | )
20 | ```
21 |
22 | ```{r, include = FALSE}
23 | suppressPackageStartupMessages({
24 | library(magrittr)
25 | library(limma)
26 | library(org.Hs.eg.db)
27 | library(edgeR)
28 | library(matrixStats)
29 | library(pheatmap)
30 | library(cellassign)
31 | })
32 | ```
33 |
34 | # Overview
35 |
36 | In many situations, marker genes for cell types are either known _a priori_
37 | as expert knowledge, or can be curated through databases such as the [Cellmark](http://biocc.hrbmu.edu.cn/CellMarker/) database. Alternatively,
38 | if purified expression data exists (either in bulk or single-cell form), it
39 | is possible to quickly derive marker genes using the `findMarkers` function
40 | in the [scran](http://bioconductor.org/packages/release/bioc/html/scran.html)
41 | R package.
42 |
43 | Below we detail a case study in deriving marker genes through a differential
44 | expression approach.
45 |
46 | # Data
47 |
48 | ## Overview
49 |
50 | We take bulk RNA-seq data from [Holik et al. Nucleic Acids Research 2017](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5389713/) to derive
51 | marker genes for 3 different cell lines. This is packaged with `cellassign`
52 | as `holik_data`:
53 |
54 | ```{r}
55 | data(holik_data)
56 | ```
57 |
58 | which contains a matrix of counts, where each row is a gene
59 | (index by entrez ID) and each column is a sample:
60 |
61 | ```{r}
62 | head(holik_data$counts[,1:2])
63 | ```
64 |
65 | as well as a vector with the cell line of origin for each sample:
66 |
67 | ```{r}
68 | head(holik_data$cell_line)
69 | ```
70 |
71 |
72 | ## Preparation
73 |
74 | We first provide a map from entrez IDs to gene symbols:
75 |
76 | ```{r}
77 | entrez_map <- select(org.Hs.eg.db,
78 | as.character(rownames(holik_data$counts)),
79 | c("SYMBOL"), "ENTREZID")
80 | gene_annotations <- entrez_map %>%
81 | dplyr::rename(GeneID=ENTREZID,
82 | Symbol=SYMBOL)
83 | ```
84 |
85 | Then construct the `DGEList` object for input to `limma voom`,
86 | filtering out lowly expressed genes:
87 |
88 | ```{r}
89 | dge <- DGEList(counts = holik_data$counts,
90 | group = holik_data$cell_line,
91 | genes = gene_annotations,
92 | remove.zeros = TRUE)
93 | genes_to_keep <- rowSums(cpm(dge$counts) > 0.5) >= 2
94 | dge_filt <- dge[genes_to_keep,]
95 | ```
96 |
97 | and finally calculate the normalization factors:
98 |
99 | ```{r}
100 | dge_filt <- calcNormFactors(dge_filt, method="TMM")
101 | ```
102 |
103 | # Differential expression
104 |
105 | We next perform differential expression using Limma Voom on a
106 | subset of 3 samples: HCC827, H2228, H1975:
107 |
108 | ```{r}
109 | dge_subset <- dge_filt[,dge_filt$samples$group %in% c("HCC827", "H2228", "H1975")]
110 | design <- model.matrix(~ 0+dge_subset$samples$group)
111 | colnames(design) <- levels(dge_subset$samples$group)
112 | v <- voom(dge_subset, design)
113 | fit <- lmFit(v, design)
114 | ```
115 |
116 | Next, fit contrasts to find differentially expressed genes between
117 | cell types:
118 |
119 | ```{r}
120 | contrast.matrix <- makeContrasts(H2228 - H1975,
121 | HCC827 - H1975,
122 | HCC827 - H2228,
123 | levels = design)
124 | fit2 <- contrasts.fit(fit, contrast.matrix)
125 | fit2 <- eBayes(fit2)
126 | ```
127 |
128 | Finally, compute gene summary statistics and filter to only
129 | significantly differentially expressed geens (FDR < 0.05):
130 |
131 | ```{r}
132 | tt <- topTable(fit2, n=Inf)
133 | tt_sig <- tt %>%
134 | dplyr::filter(adj.P.Val < 0.05)
135 |
136 | head(tt_sig)
137 | ```
138 |
139 | # Marker gene derivation
140 |
141 | To derive marker genes, we first create a log fold change
142 | matrix using H1975 as the baseline expression:
143 |
144 | ```{r}
145 | lfc_table <- tt_sig[,c("H2228...H1975", "HCC827...H1975")]
146 | lfc_table <- lfc_table %>%
147 | dplyr::mutate(H1975=0,
148 | H2228=H2228...H1975,
149 | HCC827=HCC827...H1975) %>%
150 | dplyr::select(H1975, H2228, HCC827)
151 | rownames(lfc_table) <- tt_sig$GeneID
152 | ```
153 |
154 |
155 | Then, for each gene, we subtract the minimum log fold change, as
156 | we care about overexpression of genes relative to some minimum
157 | expression level, as this defines a marker gene:
158 |
159 | ```{r}
160 | lfc_table <- as.matrix(lfc_table)
161 | lfc_table <- lfc_table - rowMins(lfc_table)
162 | lfc_table <- as.data.frame(lfc_table)
163 | ```
164 |
165 | We now define a helper function for turning log fold changes into
166 | a binary matrix. This takes a matrix and a threshold, and any values
167 | less than or equal to the threshold are set to 0, and all others to 1:
168 |
169 | ```{r}
170 | binarize <- function(x, threshold) {
171 | x[x <= threshold] <- -Inf
172 | x[x > -Inf] <- 1
173 | x[x == -Inf] <- 0
174 | return(x)
175 | }
176 | ```
177 |
178 | Next, we implement a basic procedure for binarizing this matrix.
179 | Essentially, we look for the largest 'gap' in expression for each gene,
180 | and the cell types with expression above this gap are designated has
181 | having that gene as a marker:
182 |
183 | ```{r}
184 | # Find the biggest difference
185 | maxdiffs <- apply(lfc_table, 1, function(x) max(diff(sort(x))))
186 |
187 | #
188 | thres_vals <- apply(lfc_table, 1, function(x) sort(x)[which.max(diff(sort(x)))])
189 | expr_mat_thres <- plyr::rbind.fill(lapply(1:nrow(lfc_table), function(i) {
190 | binarize(lfc_table[i,], thres_vals[i])
191 | }))
192 | rownames(expr_mat_thres) <- rownames(lfc_table)
193 | marker_gene_mat <- expr_mat_thres[(maxdiffs >= quantile(maxdiffs, c(.99)))
194 | & (thres_vals <= log(2)),] %>%
195 | as.matrix
196 | ```
197 |
198 | Finally, we add back in gene symbols rather than entrez ids:
199 |
200 | ```{r, warning=FALSE}
201 | suppressMessages({
202 | symbols <- plyr::mapvalues(
203 | rownames(marker_gene_mat),
204 | from = gene_annotations$GeneID,
205 | to = gene_annotations$Symbol
206 | )
207 | })
208 |
209 | is_na <- is.na(symbols)
210 |
211 | marker_gene_mat <- marker_gene_mat[!is_na,]
212 | rownames(marker_gene_mat) <- symbols[!is_na]
213 | ```
214 |
215 | And there we have a marker gene matrix for our cell types:
216 |
217 | ```{r}
218 | head(marker_gene_mat)
219 | ```
220 |
221 | ```{r, fig.width = 10, fig.height = 3}
222 | pheatmap(t(marker_gene_mat))
223 | ```
224 |
225 | Note that the expression data used for input to `CellAssign` should
226 | use only these as input.
227 |
228 | # Technical
229 |
230 | ```{r}
231 | sessionInfo()
232 | ```
233 |
234 |
--------------------------------------------------------------------------------
/docs/reference/print.cellassign.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
117 |
152 |
153 |
154 |
164 |
118 |
138 |
139 |
142 |
151 |
119 |
122 |
123 |
124 | Example cell marker matrix
120 | 121 |example_marker_mat.Rd
125 |
128 |
129 | An example matrix for 10 genes and 2 cell types showing the membership 126 | of marker genes to cell types
127 |example_marker_mat
130 |
131 |
132 | Format
133 | 134 |An object of class matrix with 10 rows and 2 columns.
See also
136 | 137 |example_cellassign_fit
Examples
140 |141 |data(example_marker_mat)
60 |
61 |
110 |
111 |
112 |
113 |
114 |
115 |
178 |
179 |
180 |
181 |
182 |
183 |
184 |
185 |
186 |
--------------------------------------------------------------------------------
/docs/reference/inference_tensorflow.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
116 |
165 |
166 |
167 |
177 |
117 |
132 |
142 |
143 |
155 |
164 |
118 | Print a
119 |
120 |
121 |
122 |
123 | Print a cellassign fit
119 |
120 | print.cellassign.Rd
124 |
126 |
127 | Print a cellassign fit
# S3 method for cellassign 128 | print(x, ...)129 | 130 |
Arguments
131 || x | 135 |An object of class |
136 |
|---|---|
| ... | 139 |Additional arguments (unused) |
140 |
Value
144 | 145 |Prints a structured representation of the cellassign
Examples
148 |154 |#> A cellassign fit for 500 cells, 10 genes, 2 cell types with 0 covariates 150 | #> To access cell types, call celltypes(x) 151 | #> To access cell type probabilities, call cellprobs(x) 152 | #>153 |
60 |
61 |
110 |
111 |
112 |
113 |
114 |
115 |
161 |
162 |
163 |
164 |
165 |
166 |
167 |
168 |
169 |
--------------------------------------------------------------------------------
/docs/reference/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
116 |
148 |
149 |
150 |
160 |
117 |
140 |
147 |
118 |
121 |
122 |
123 | cellassign inference in tensorflow, semi-supervised version
119 | 120 |inference_tensorflow.Rd
124 |
126 |
127 | cellassign inference in tensorflow, semi-supervised version
125 |inference_tensorflow(Y, rho, s, X, G, C, N, P, B = 10, shrinkage, 128 | verbose = FALSE, n_batches = 1, rel_tol_adam = 1e-04, 129 | rel_tol_em = 1e-04, max_iter_adam = 1e+05, max_iter_em = 20, 130 | learning_rate = 1e-04, random_seed = NULL, min_delta = 2, 131 | dirichlet_concentration = rep(0.01, C))132 | 133 | 134 |
Value
135 | 136 |A list of MLE cell type calls, MLE parameter estimates, 137 | and log likelihoods during optimization.
138 | 139 |
58 |
59 |
108 |
109 |
110 |
111 |
112 |
113 |
225 |
226 |
227 |
228 |
229 |
230 |
231 |
232 |
233 |
--------------------------------------------------------------------------------
/docs/reference/simulate_cellassign.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
114 |
212 |
213 |
214 |
224 |
115 |
204 |
205 |
211 |
116 |
118 |
119 | Reference
117 |
60 |
61 |
110 |
111 |
112 |
113 |
114 |
115 |
208 |
209 |
210 |
211 |
212 |
213 |
214 |
215 |
216 |
--------------------------------------------------------------------------------
/docs/reference/marker_list_to_mat.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
116 |
195 |
196 |
197 |
207 |
117 |
132 |
173 |
174 |
185 |
194 |
118 |
121 |
122 |
123 | Simulate from the cellassign model
119 | 120 |simulate_cellassign.Rd
124 |
126 |
127 | Simulate RNA-seq counts from the cell-assign model
125 |simulate_cellassign(rho, s, pi, delta, B = 20, a, beta, X = NULL, 128 | min_Y = 0, max_Y = 1000)129 | 130 |
Arguments
131 || rho | 135 |A gene by cell type binary matrix relating markers to cell types |
136 |
|---|---|
| s | 139 |A vector of cell-specific size factors |
140 |
| pi | 143 |An ordinal vector relating each cell to its true marker type assignment |
144 |
| delta | 147 |Gene by cell type matrix delta (all entries with corresponding zeros 148 | in rho will be ignored) |
149 |
| B | 152 |Granularity of spline-based fitting of dispersions |
153 |
| a | 156 |Alpha parameters for spline inference of dispersions |
157 |
| beta | 160 |A gene by covariate vector of coefficients - the first column 161 | should correspond to the intercept (baseline expression) values |
162 |
| X | 165 |A cell by covariate matrix of covariates - the intercept column will 166 | always be added. |
167 |
| b | 170 |Beta parameters for spline inference of dispersions |
171 |
Value
175 | 176 |An N by G matrix of simulated counts
177 |Details
178 | 179 |The number of genes, cells, and cell types is automatically 180 | inferred from the dimensions of rho (gene by cell-type) and 181 | s (vector of length number of cells). The specification of X 182 | is optional - a column of ones will always be added as an intercept.
183 | 184 |
61 |
62 |
111 |
112 |
113 |
114 |
115 |
116 |
193 |
194 |
195 |
196 |
197 |
198 |
199 |
200 |
201 |
--------------------------------------------------------------------------------
/vignettes/introduction-to-cellassign.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Assigning single-cells to known cell types with CellAssign"
3 | author: "Allen W Zhang and Kieran R Campbell"
4 | date: "October 2019"
5 | package: "cellassign"
6 | output: BiocStyle::html_document
7 | vignette: >
8 | %\VignetteIndexEntry{Introduction to CellAssign}
9 | %\VignetteEngine{knitr::rmarkdown}
10 | %\VignetteEncoding{UTF-8}
11 | ---
12 |
13 | ```{r setup, include = FALSE}
14 | knitr::opts_chunk$set(
15 | collapse = TRUE,
16 | warnings = FALSE,
17 | messages = FALSE,
18 | comment = "#>"
19 | )
20 | ```
21 |
22 | # Overview
23 |
24 | `cellassign` assigns cells measured using single cell RNA sequencing
25 | to known cell types based on marker gene information. Unlike other
26 | methods for assigning cell types from single cell RNA-seq data,
27 | `cellassign` does not require labeled single cell or purified bulk
28 | expression data -- `cellassign` only needs to know whether or not
29 | each given gene is a marker of each cell type:
30 |
31 | ```{r, echo = FALSE}
32 | knitr::include_graphics("cellassign_overview.png")
33 | ```
34 |
35 | Inference is performed using [Tensorflow](http://tensorflow.org/). For more
36 | details please see the
37 | [manuscript](https://www.biorxiv.org/content/10.1101/521914v1).
38 |
39 | # Installation
40 |
41 | `cellassign` depends on `tensorflow`, which can be installed as follows:
42 |
43 | ```{r, eval=FALSE}
44 | install.packages("tensorflow")
45 | library(tensorflow)
46 | install_tensorflow(extra_packages = "tensorflow-probability")
47 | ```
48 |
49 | Please ensure this installs version 2 of tensorflow. You can check this by calling
50 |
51 | ```{r}
52 | tensorflow::tf_config()
53 | ```
54 |
55 | You can confirm that the installation succeeded by running:
56 |
57 | ```{r, eval=FALSE}
58 | sess = tf$Session()
59 | hello <- tf$constant('Hello, TensorFlow!')
60 | sess$run(hello)
61 | ```
62 |
63 | Note that the `tf` object is created automatically when the `tensorflow` library is loaded to provide access to the Tensorflow interface.
64 |
65 | For more details see the [Rstudio page on tensorflow installation](https://tensorflow.rstudio.com/tensorflow/articles/installation.html).
66 |
67 | `cellassign` can then be installed through Bioconductor via
68 |
69 | ```{r, eval=FALSE}
70 | BiocManager::install('cellassign')
71 | ```
72 |
73 | or the development version through github using the `devtools` package :
74 |
75 | ```{r, eval=FALSE}
76 | devtools::install_github("Irrationone/cellassign")
77 | ```
78 |
79 |
80 | # Basic usage
81 |
82 | We begin by illustrating basic usage of `cellassign` on some
83 | example data bundled with the package. First, load the relevant libraries:
84 |
85 | ```{r, results='hide', message=FALSE, warning=FALSE}
86 | library(SingleCellExperiment)
87 | library(cellassign)
88 | ```
89 |
90 | We use an example `SingleCellExperiment` consisting of 200 genes
91 | and 500 cells:
92 |
93 | ```{r}
94 | data(example_sce)
95 | print(example_sce)
96 | ```
97 |
98 | The true cell types are annotated for convenience in the `Group`
99 | slot of the `SingleCellExperiment`:
100 |
101 | ```{r}
102 | print(head(example_sce$Group))
103 | ```
104 |
105 |
106 | Also provided is an example gene-by-cell-type binary matrix, whose
107 | entries are 1 if a gene is a marker for a given cell type and 0 otherwise:
108 |
109 | ```{r}
110 | data(example_marker_mat)
111 | print(example_marker_mat)
112 | ```
113 |
114 | We further require size factors for each cell. These are stored
115 | in `sizeFactors(example_sce)` - for your data we recommend computing
116 | them using the `computeSumFactors` function from the `scran` package. Note: **it is highly recommended to compute size factors using the full set of genes, before subsetting to markers for input to cellassign**.
117 |
118 | ```{r}
119 | s <- sizeFactors(example_sce)
120 | ```
121 |
122 | We then call `cellassign` using the `cellassign()` function, passing
123 | in the above information. **It is critical that gene expression data containing only marker genes is used as input to cellassign**. We do this here by subsetting the input `SingleCellExperiment` using the row names (gene names) of the marker matrix. This also ensures that the order of the genes in the gene expression data matches the order of the genes in the marker matrix.
124 |
125 |
126 | ```{r}
127 | fit <- cellassign(exprs_obj = example_sce[rownames(example_marker_mat),],
128 | marker_gene_info = example_marker_mat,
129 | s = s,
130 | learning_rate = 1e-2,
131 | shrinkage = TRUE,
132 | verbose = FALSE)
133 | ```
134 |
135 | This returns a `cellassign` object:
136 |
137 | ```{r}
138 | print(fit)
139 | ```
140 |
141 | We can access the maximum likelihood estimates (MLE) of cell type using the `celltypes` function:
142 |
143 | ```{r}
144 | print(head(celltypes(fit)))
145 | ```
146 |
147 | By default, this assigns a cell to a type of the probability of assignment is greater than 0.95, and "unassigned" otherwise. This can be changed with the `assign_prob` parameter.
148 |
149 | It is also possible to get all MLE parameters using `mleparams`:
150 |
151 | ```{r}
152 | print(str(mleparams(fit)))
153 | ```
154 |
155 | We can also visualize the probabilities of assignment using the `cellprobs` function that returns a probability matrix for each cell and cell type:
156 |
157 | ```{r}
158 | pheatmap::pheatmap(cellprobs(fit))
159 | ```
160 |
161 |
162 | Finally, since this is simulated data we can check the concordance
163 | with the true group values:
164 |
165 | ```{r}
166 | print(table(example_sce$Group, celltypes(fit)))
167 | ```
168 |
169 | # Example set of markers for tumour microenvironment
170 |
171 | A set of example markers are included with the `cellassign` package
172 | for common cell types in the human tumour microenvironment. Users
173 | should be aware that
174 |
175 | 1. This set is provided as an _example_ only and we recommend
176 | researchers derive marker gene sets for their own use
177 | 2. The `cellassign` workflow is typically iterative, including
178 | ensuring all markers are expressed in your expression data, and
179 | removing cell types from the input marker matrix that do not appear
180 | to be present
181 |
182 | The marker genes are available for the following cell types:
183 |
184 | * B cells
185 | * T cells
186 | * Cytotoxic T cells
187 | * Monocyte/Macrophage
188 | * Epithelial cells
189 | * Myofibroblasts
190 | * Vascular smooth muscle cells
191 | * Endothelial cells
192 |
193 | These can be accessed by calling
194 |
195 | ```{r}
196 | data(example_TME_markers)
197 | ```
198 |
199 | Note that this is a list of two marker lists:
200 |
201 | ```{r}
202 | names(example_TME_markers)
203 | ```
204 |
205 | Where `symbol` contains gene symbols:
206 |
207 | ```{r}
208 | lapply(head(example_TME_markers$symbol, n = 4), head, n = 4)
209 | ```
210 |
211 | and `ensembl` contains the equivalent ensembl gene ids:
212 |
213 | ```{r}
214 | lapply(head(example_TME_markers$ensembl, n = 4), head, n = 4)
215 | ```
216 |
217 | To use these with `cellassign` we can turn them into the binary
218 | marker by cell type matrix:
219 |
220 | ```{r}
221 | marker_mat <- marker_list_to_mat(example_TME_markers$ensembl)
222 |
223 | marker_mat[1:3, 1:3]
224 | ```
225 |
226 | *Important*: the single cell experiment or input gene expression
227 | matrix should be subset accordingly to match the rows of the marker
228 | input matrix, e.g. if `sce` is a `SingleCellExperiment` with ensembl
229 | IDs as rownames then call
230 |
231 | ```{r, eval = FALSE}
232 | sce_marker <- sce[intersect(rownames(marker_mat), rownames(sce)),]
233 | ```
234 |
235 | Note that the rows in the single cell experiment or gene expression
236 | matrix should be ordered identically to those in the marker input
237 | matrix.
238 |
239 | You can the proceed using `cellassign` as before.
240 |
241 |
242 | # Advanced usage
243 |
244 | ## Options for a `cellassign()` call
245 |
246 | There are several options to a call to `cellassign` that can alter
247 | the results:
248 |
249 | * `min_delta`: the minimum log-fold change in expression above which a
250 | genemust be over-expressed in the cells of which it is a marker compared to
251 | all others
252 | * `X`: a covariate matrix, see section below
253 | * `shrinkage`: whether to impose a hierarchical prior on the values of `delta`
254 | (cell type specific increase in expression of marker genes)
255 |
256 |
257 | ## Constructing a marker gene matrix
258 |
259 | Here we demonstrate a method of constructing the binary marker gene
260 | matrix that encodes our *a priori* knowledge of cell types.
261 |
262 | For two types of cells (`Group1` and `Group2`) we know *a priori* several good
263 | marker genes, e.g.:
264 |
265 | | Cell type | Genes |
266 | | --------- | ----- |
267 | | Group1 | Gene186, Gene269, Gene526, Gene536, Gene994 |
268 | | Group2 | Gene205, Gene575, Gene754, Gene773, Gene949 |
269 |
270 | To use this in `cellassign`, we must turn this into a *named list*, where
271 | the names are the cell types and the entries are marker genes
272 | (not necessarily mutually exclusive) for each cell type:
273 |
274 | ```{r}
275 | marker_gene_list <- list(
276 | Group1 = c("Gene186", "Gene269", "Gene526", "Gene536", "Gene994"),
277 | Group2 = c("Gene205", "Gene575", "Gene754", "Gene773", "Gene949")
278 | )
279 |
280 | print(str(marker_gene_list))
281 | ```
282 |
283 | We can then directly provide this to `cellassign` or turn it into a binary
284 | marker gene matrix first using the `marker_list_to_mat` function:
285 |
286 | ```{r}
287 | print(marker_list_to_mat(marker_gene_list))
288 | ```
289 |
290 | This has automatically included an `other` group for cells that do not fall
291 | into either type - this can be excluded by setting `include_other = FALSE`.
292 |
293 | ## Adding covariates
294 |
295 | Covariates corresponding to batch, sample, or patient-specific effects can
296 | be included in the `cellassign` model. For example, if we have two covariates
297 | `x1` and `x2`:
298 |
299 | ```{r}
300 | N <- ncol(example_sce)
301 | x1 <- rnorm(N)
302 | x2 <- rnorm(N)
303 | ```
304 |
305 | We can construct a design matrix using the `model.matrix` function in R:
306 |
307 | ```{r}
308 | X <- model.matrix(~ 0 + x1 + x2)
309 | ```
310 |
311 | Note we explicitly set no intercept by passing in `0` in the beginning.
312 | We can then perform an equivalent cell assignment passing this in also:
313 |
314 | ```{r, eval = FALSE}
315 | fit <- cellassign(exprs_obj = example_sce,
316 | marker_gene_info = example_marker_mat,
317 | X = X,
318 | s = s,
319 | learning_rate = 1e-2,
320 | shrinkage = TRUE,
321 | verbose = FALSE)
322 | ```
323 |
324 |
325 | # Technical
326 |
327 | ```{r}
328 | sessionInfo()
329 | ```
330 |
331 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | Apache License
2 | ==============
3 |
4 | _Version 2.0, January 2004_
5 | _<
117 |
180 |
181 |
182 |
192 |
118 |
133 |
145 |
146 |
169 |
179 |
119 |
122 |
123 |
124 | Convert a list of marker genes to a binary matrix
120 | 121 |marker_list_to_mat.Rd
125 |
128 |
129 | Given a list of cell types and marker genes, convert to a binary 126 | cell type by gene matrix required by cellassign.
127 |marker_list_to_mat(marker_list, include_other = TRUE)130 | 131 |
Arguments
132 || marker_list | 136 |A list where each entry is named by a cell type and 137 | contains a character vector of gene names belonging to that cell type |
138 |
|---|---|
| include_other | 141 |If |
143 |
Value
147 | 148 |A cell type by gene binary matrix with 1 if a gene is a marker for 149 | a cell type and 0 otherwise
150 |Details
151 | 152 |This function takes a list of marker genes and converts it to a binary 153 | gene by cell type matrix. The input list should be the same 154 | length as the number of cell types with names corresponding to cell types. 155 | Each element of the list should be a character vector of the genes corresponding 156 | to that cell type. There is no requirement for mutually-exclusive marker genes.
157 | 158 |Examples
159 |168 |marker_list <- list( 160 | `cell_type_1` = c("geneA", "geneB"), 161 | `cell_type_2` = c("geneB", "geneC") 162 | ) 163 | marker_list_to_mat(marker_list)#> cell_type_1 cell_type_2 other 164 | #> geneA 1 0 0 165 | #> geneB 1 1 0 166 | #> geneC 0 1 0167 |