R/ti_sincell.R

In dynverse/dynmethods: A collection of trajectory inference methods

######################################### DO NOT EDIT! #########################################
#### This file is automatically generated from data-raw/2-generate_r_code_from_containers.R ####
################################################################################################

#' @title Sincell
#' 
#' @description
#' Will generate a trajectory using
#' [Sincell](https://doi.org/10.1093/bioinformatics/btv368).
#' 
#' This method was wrapped inside a
#' [container](https://github.com/dynverse/ti_sincell).
#' The original code of this method is available
#' [here](https://github.com/Cortalak/MCA_Sincell_0).
#' 
#' @references Juliá, M., Telenti, A., Rausell, A., 2015. Sincell: an
#' R/Bioconductor package for statistical assessment of cell-state hierarchies
#' from single-cell RNA-seq: Fig. 1. Bioinformatics 31, 3380–3382.
#' 
#' @param distance_method Distance method to be used. The available distances are
#' the Euclidean distance (method="euclidean"), Manhattan distance (also called L1
#' distance, method="L1"), cosine distance (method="cosine") , distance based on
#' Pearson (method="pearson") or Spearman (method="spearman") correlation
#' coefficients, and distance based on Mutual Information (method="MI"). Intervals
#' used to assess Mutual Information are indicated in the parameter 'bins'.
#' Domain: {euclidean, cosine, pearson, spearman, L1, MI}. Default: euclidean.
#' Format: character.
#' @param dimred_method Dimensionality reduction algorithm to be used. Options
#' are: Principal Component Analysis (method="PCA"), Independent Component
#' Analysis (method="ICA"; using fastICA() function in fastICA package),
#' t-Distributed Stochastic Neighbor Embedding (method="tSNE"; using Rtsne()
#' function in Rtsne package with parameters tsne.perplexity=1 and
#' tsne.theta=0.25), classical Multidimensional Scaling (method="classical-MDS";
#' using the cmdscale() function) and non-metric Multidimensional Scaling
#' (method="nonmetric-MDS";using the isoMDS() function in MASS package). if
#' method="PCA" is chosen, the proportion of variance explained by each of the
#' principal axes is plotted. We note that Sincell makes use of the Rtsne
#' implementation of the Barnes-Hut algorithm, which approximates the likelihood.
#' The user should be aware that this is a less accurate version of t-SNE than
#' e.g. the one used as basis of viSNE (Amir,E.D. et al. 2013, Nat Biotechnol 31,
#' 545-552). Domain: {none, PCA, ICA, tSNE, classical-MDS, nonmetric-MDS}.
#' Default: none. Format: character.
#' @param clust.method If clust.method="max.distance", clusters are defined as
#' subgraphs generated by a maximum pair-wise distance cut-off, that is: from a
#' totally connected graph where all cells are connected to each other, the
#' algorithm only keeps pairs of cells connected by a distance lower than a given
#' threshold.If clust.method="percent", clusters are defined as subgraphs
#' generated by a given rank-percentile of the shortest pair-wise distances, that
#' is; from a totally connected graph where all cells are connected to each other,
#' the algorithm only keeps the top 'x' percent of shortest pairwise distances as
#' indicated by "shortest.rank.percent".If clust.method="knn", unsupervised
#' K-Nearest Neighbors (K-NN) clustering is performed: From a totally disconnected
#' graph where none of the cells are connected to each other, the algorithm
#' connects each cell to its 'k' nearest neighbors. If parameter "mutual=TRUE",
#' Unsupervised K-Mutual Nearest Neighbours (K-MNN) clustering is performed, that
#' is: only reciprocal k nearest neighbors are connected.If
#' clust.method="k-medoids", clustering around medoids (a more robust version of
#' k-means) is performed with function "pam" from package "cluster" on the
#' distance matrix in mySincellObject$cell2celldist with a desired number of
#' groups indicated in parameter "num.clusters"Hierarchical agglomerative
#' clustering can be performed by internally calling function "hclust" where the
#' agglomeration method is indicated in parameter "clust.method" as one of
#' "ward.D", "ward.D2", "single", "complete", "average" (= UPGMA), "mcquitty" (=
#' WPGMA), "median" (= WPGMC) or "centroid" (= UPGMC). Clusters are obtained by
#' cutting the tree produced by hclust with function cutree with a desired number
#' of groups indicated in parameter "num.clusters". Domain: {max.distance,
#' percent, knn, k-medoids, ward.D, ward.D2, single, complete, average, mcquitty,
#' median, centroid}. Default: max.distance. Format: character.
#' @param mutual If clust.method="knn" and "mutual=TRUE", Unsupervised K-Mutual
#' Nearest Neighbours (K-MNN) clustering is performed, that is only reciprocal k
#' nearest neighbors are connected. Default: TRUE. Format: logical.
#' @param max.distance In max.distance algorithm, select up to which distance the
#' points will be linked. Domain: U(0, 5). Default: 0. Format: numeric.
#' @param k If clust.method="knn", k is an integer specifying the number of
#' nearest neighbors to consider in K-NN and K-KNN. Domain: U(1, 99). Default: 3.
#' Format: integer.
#' @param shortest.rank.percent In percent algorithm, select the percent of
#' shortest distances will be represented as links. Domain: U(0, 100). Default:
#' 10. Format: numeric.
#' @param graph.algorithm Graph building algorithm to be used; the Minimum
#' Spanning Tree (`graph.algorithm="MST"`), the Maximum Similarity Spanning Tree
#' (`graph.algorithm="SST"`) and the Iterative Mutual Clustering Graph
#' (`graph.algorithm="IMC"`). Domain: {MST, SST, IMC}. Default: MST. Format:
#' character.
#' @param graph.using.cells.clustering If graph.using.cells.clustering=TRUE and
#' graph.algorithm="MST" or graph.algorithm="MST", a precalculated clustering of
#' cells is used. The clustering of cells is taken from
#' SincellObject$cellsClustering as calculated by function sc_clusterObj().
#' Default: FALSE. Format: logical.
#' @param k_imc If IMC algorithm is selected, the number of nearest neighbors used
#' in the underlying K-Mutual Nearest Neighbour (K-MNN) algorithm is set to k.
#' Domain: U(1, 99). Default: 3. Format: integer.
#' @param pct_leaf_node_cutoff Leaf nodes are iteratively removed until the
#' percentage of leaf nodes is below the given cutoff. Removed nodes are projected
#' to their closest neighbour. This is to constrain the number of milestones being
#' created. Domain: U(0.01, 0.8). Default: 0.5. Format: numeric.
#' 
#' @keywords method
#' 
#' @return A TI method wrapper to be used together with
#' \code{\link[dynwrap:infer_trajectories]{infer_trajectory}}
#' @export
ti_sincell <- function(
    distance_method = "euclidean",
    dimred_method = "none",
    clust.method = "max.distance",
    mutual = TRUE,
    max.distance = 0L,
    k = 3L,
    shortest.rank.percent = 10L,
    graph.algorithm = "MST",
    graph.using.cells.clustering = FALSE,
    k_imc = 3L,
    pct_leaf_node_cutoff = 0.5
) {
  method_choose_backend(
    package_repository = NULL,
    package_name = NULL,
    function_name = NULL,
    package_version = NULL,
    container_id = "dynverse/ti_sincell:v0.9.9.01"
  )(
    distance_method = distance_method,
    dimred_method = dimred_method,
    clust.method = clust.method,
    mutual = mutual,
    max.distance = max.distance,
    k = k,
    shortest.rank.percent = shortest.rank.percent,
    graph.algorithm = graph.algorithm,
    graph.using.cells.clustering = graph.using.cells.clustering,
    k_imc = k_imc,
    pct_leaf_node_cutoff = pct_leaf_node_cutoff
  )
}