some wording changes in the documentation

R/find_de_neighborhoods.R

@@ -13,23 +13,23 @@ glmGamPoi::vars
 #' Find differential expression neighborhoods
 #'
 #' @param fit the `lemur_fit` generated by `lemur()`
-#' @param group_by If the `independent_matrix` is provided, `group_by` defines
-#'   how the pseudobulks are formed. This is typically the variable in the column
-#'   data that represents the independent unit of replication of the experiment
-#'   (e.g., the mouse or patient ID). The argument has to be wrapped in `vars(...)`.
-#' @param contrast a specification which contrast to fit. This defaults to the
+#' @param group_by defines
+#'   how the pseudobulks are formed. `group_by` is the name of the variable in the column
+#'   annotation that represents the independent unit of replication of the experiment
+#'   (e.g., which biopsy). The argument has to be wrapped in `vars(...)`.
+#' @param contrast specification of the contrast of interest. This defaults to the
 #'   `contrast` argument that was used for `test_de` and is stored in `fit$contrast`.
 #' @param selection_procedure specify the algorithm that is used to select the
 #'   neighborhoods for each gene. Broadly, `selection_procedure = "zscore"` is faster
-#'   but less precise than `selection_procedure = "contrast"`.
+#'   but less elaborate than `selection_procedure = "contrast"`.
 #' @param directions a string to define the algorithm to select the direction onto
 #'   which the cells are projected before searching for the neighborhood.
 #'   `directions = "random"` produces denser neighborhoods, whereas `directions = "contrast"`
 #'   has usually more power. \cr
 #'   Alternatively, this can also be a matrix with one direction for each gene
 #'   (i.e., a matrix of size `nrow(fit) * fit$n_embedding`).
 #' @param min_neighborhood_size the minimum number of cells per neighborhood. Default: `50`.
-#' @param de_mat the matrix with the differential expression values and is only relevant if
+#' @param de_mat the matrix with the differential expression values. This is only relevant if
 #'   `selection_procedure = "zscore"` or `directions = "random"`. Defaults
 #'   to an assay called `"DE"` that is produced by `lemur::test_de()`.
 #' @param test_data a `SummarizedExperiment` object or a named list of matrices. The
@@ -41,20 +41,20 @@ glmGamPoi::vars
 #'   forming the pseudobulk. If `test_method == "limma"`, only the continuous assay is needed. \cr
 #'   The arguments defaults to the test data split of when calling `lemur()`.
 #' @param test_data_col_data additional column data for the `test_data` argument.
-#' @param size_factor_method Set the procedure to calculate the size factor after pseudobulking. This argument
+#' @param size_factor_method the procedure to calculate the size factor after pseudobulking. This argument
 #'   is only relevant if `test_method` is `"glmGamPoi"` or `"edgeR"`. If `fit` is subsetted, using a
 #'   vector with the sequencing depth per cell ensures reasonable results.
 #'   Default: `NULL` which means that `colSums(assay(fit$test_data, count_assay_name))` is used.
 #' @param test_method choice of test for the pseudobulked differential expression.
 #'   [glmGamPoi](https://bioconductor.org/packages/glmGamPoi/) and
-#'   [edgeR](https://bioconductor.org/packages/edgeR/) work on an count assay.
-#'   [limma](http://bioconductor.org/packages/limma/) works on the continuous assay.
+#'   [edgeR](https://bioconductor.org/packages/edgeR/) work on the counts.
+#'   [limma](http://bioconductor.org/packages/limma/) works on continuous numbers (e.g., after logarithm transformation).
 #' @param continuous_assay_name,count_assay_name the assay or list names of `independent_data`.
 #' @param design,alignment_design the design to use for the fit. Default: `fit$design`
-#' @param add_diff_in_diff a boolean to specify if the log-fold change (plus significance) of
+#' @param add_diff_in_diff logical scalar to specify whether the logarithmic fold change (plus significance) of
 #'   the DE in the neighborhood against the DE in the complement of the neighborhood is calculated.
 #'   If `TRUE`, the result includes three additional columns starting with `"did_"` short for
-#'   difference-in-difference. Default: `TRUE`.
+#'   difference-in-difference..
 #' @param make_neighborhoods_consistent Include cells from outside the neighborhood if they are
 #'   at least 10 times in the k-nearest neighbors of the cells inside the neighborhood. Secondly,
 #'   remove cells from the neighborhood which are less than 10 times in the k-nearest neighbors of the

R/lemur_fit.R

@@ -10,17 +10,16 @@
 #'
 #' To access the values produced by [`lemur`], use the dollar notation (`$`):
 #' \describe{
-#'  \item{`fit$n_embedding`}{the number of embedding dimensions.}
-#'  \item{`fit$design`}{the specification of the design in [`lemur`]. Usually this is a [`stats::formula`].}
-#'  \item{`fit$base_point`}{a matrix (`nrow(fit) * fit$n_embedding`) with the base point for the Grassmann exponential map.}
-#'  \item{`fit$coefficients`}{a three-dimensional tensor (`nrow(fit) * fit$n_embedding * ncol(fit$design_matrix)`) with the coefficients for
-#'    the exponential map.}
-#'  \item{`fit$embedding`}{a matrix (`fit$n_embedding * ncol(fit)`) with the low dimensional position for each cell.}
-#'  \item{`fit$design_matrix`}{a matrix with covariates for each cell (`ncol(fit) * ncol(fit$design_matrix)`).}
-#'  \item{`fit$linear_coefficients`}{a matrix (`nrow(fit) * ncol(fit$design_matrix)`) with the coefficients for the linear regression.}
-#'  \item{`fit$alignment_coefficients`}{a 3D tensor with the coefficients for the alignment (`fit$n_embedding * fit$n_embedding * ncol(fit$design_matrix)`)}
-#'  \item{`fit$alignment_design`}{an alternative design specification for the alignment. This is typically a [`stats::formula`].}
-#'  \item{`fit$alignment_design_matrix`}{an alternative design matrix specification for the alignment.}
+#'  \item{`fit$n_embedding`}{the dimension of the latent space.}
+#'  \item{`fit$design`}{the specification of the design in [`lemur`]. Usually this is a design formula, see [`stats::formula`].}
+#'  \item{`fit$base_point`}{a matrix of size `nrow(fit)` x `fit$n_embedding` with the base point for the Grassmann exponential map.}
+#'  \item{`fit$coefficients`}{a three-dimensional tensor of size `nrow(fit)` x `fit$n_embedding` x `ncol(fit$design_matrix)` with the coefficients for the exponential map.}
+#'  \item{`fit$embedding`}{a matrix of size `fit$n_embedding` x `ncol(fit)` with the latent space coordinates of each cell.}
+#'  \item{`fit$design_matrix`}{a matrix with the covariate values for each cell, of size `ncol(fit)` x `ncol(fit$design_matrix)`.}
+#'  \item{`fit$linear_coefficients`}{a matrix (of size `nrow(fit)` x `ncol(fit$design_matrix)` with the coefficients for the linear regression.}
+#'  \item{`fit$alignment_coefficients`}{a 3-tensor with the coefficients for the alignment, of size `fit$n_embedding` x `fit$n_embedding` x `ncol(fit$design_matrix)`.}
+#'  \item{`fit$alignment_design`}{an alternative specification of the alignment, using a design, typically a [`stats::formula`].}
+#'  \item{`fit$alignment_design_matrix`}{an alternative specification of the alignment, using a design matrix.}
 #'  \item{`fit$contrast`}{a parsed version of the contrast specification from the `test_de` function or `NULL`.}
 #'  \item{`fit$colData`}{the column annotation `DataFrame`.}
 #'  \item{`fit$rowData`}{the row annotation `DataFrame`.}
@@ -34,8 +33,8 @@
 #' @aliases lemur_fit
 #'
 #' @examples
-#' # The easiest way to make a lemur_fit object, is to call `lemur`
-#' data(glioblastoma_example_data)
+#' # The easiest way to make a lemur_fit object is to call `lemur`
+#' data("glioblastoma_example_data")
 #' fit <- lemur(glioblastoma_example_data, design = ~ patient_id + condition,
 #'              n_emb = 5, verbose = FALSE)
 #'