geposan/R/analyze.R

#' Analyze by applying the specified preset.
#'
#' @param preset The preset to use which should be created using [preset()].
#' @param progress A function to be called for progress information. The
#'   function should accept a number between 0.0 and 1.0 for the current
#'   progress.
#'
#' @returns An object containing the results of the analysis with the following
#'   items:
#'   \describe{
#'     \item{`preset`}{The preset that was used.}
#'     \item{`results`}{A [data.table] with one row for each gene identified by
#'       it's ID (`gene` column). The additional columns contain the resulting
#'       scores per method and are named after the method IDs.}
#'   }
#'
#' @export
analyze <- function(preset, progress = NULL) {
    if (class(preset) != "geposan_preset") {
        stop("Preset is invalid. Use geposan::preset() to create one.")
    }

    # Available methods by ID.
    #
    # A method describes a way to perform a computation on gene distance data
    # that results in a single score per gene. The function should accept the
    # preset to apply (see [preset()]) and an optional progress function (that
    # may be called with a number between 0.0 and 1.0) as its parameters.
    #
    # The function should return a [data.table] with the following columns:
    #
    #  - `gene` Gene ID of the processed gene.
    #  - `score` Score for the gene between 0.0 and 1.0.
    methods <- list(
        "clusteriness" = clusteriness,
        "clusteriness_positions" = function(...) {
            clusteriness(..., use_positions = TRUE)
        },
        "correlation" = correlation,
        "correlation_positions" = function(...) {
            correlation(..., use_positions = TRUE)
        },
        "neural" = neural,
        "neural_positions" = function(...) {
            neural(..., use_positions = TRUE)
        },
        "proximity" = proximity
    )

    results <- cached("analysis", preset, {
        total_progress <- 0.0
        method_count <- length(preset$methods)
        results <- data.table(gene = preset$gene_ids)

        for (method_id in preset$methods) {
            method_progress <- if (!is.null(progress)) {
                function(p) {
                    progress(total_progress + p / method_count)
                }
            }

            method_results <- methods[[method_id]](
                preset,
                progress = method_progress
            )

            setnames(method_results, "score", method_id)

            results <- merge(
                results,
                method_results,
                by = "gene"
            )

            total_progress <- total_progress + 1 / method_count
        }

        # Count included species from the preset per gene.
        genes_n_species <- geposan::distances[
            species %chin% preset$species_ids,
            .(n_species = .N),
            by = "gene"
        ]

        setkey(genes_n_species, "gene")

        # Return the results for genes with enough species.
        results[genes_n_species[gene, n_species] >= preset$min_n_species]
    })

    if (!is.null(progress)) {
        progress(1.0)
    }

    structure(
        list(
            preset = preset,
            results = results
        ),
        class = "geposan_analysis"
    )
}