score_markers_pairwise.hpp

Go to the documentation of this file.

#ifndef SCRAN_MARKERS_SCORE_MARKERS_PAIRWISE_HPP
#define SCRAN_MARKERS_SCORE_MARKERS_PAIRWISE_HPP
 
#include "cohens_d.hpp"
#include "simple_diff.hpp"
 
#include "scan_matrix.hpp"
#include "average_group_stats.hpp"
#include "PrecomputedPairwiseWeights.hpp"
#include "create_combinations.hpp"
 
#include <vector>
 
#include "scran_blocks/scran_blocks.hpp"
#include "tatami/tatami.hpp"
#include "tatami_stats/tatami_stats.hpp"
 
namespace scran_markers {
 
struct ScoreMarkersPairwiseOptions {
    double threshold = 0;
 
    int num_threads = 1;
 
    bool compute_cohens_d = true;
 
    bool compute_auc = true;
 
    bool compute_delta_mean = true;
 
    bool compute_delta_detected = true;
 
    scran_blocks::WeightPolicy block_weight_policy = scran_blocks::WeightPolicy::VARIABLE;
 
    scran_blocks::VariableWeightParameters variable_block_weight_parameters;
};
 
template<typename Stat_>
struct ScoreMarkersPairwiseBuffers {
    std::vector<Stat_*> mean;
 
    std::vector<Stat_*> detected;
 
    Stat_* cohens_d = NULL;
 
    Stat_* auc = NULL;
 
    Stat_* delta_mean = NULL;
 
    Stat_* delta_detected = NULL;
};
 
template<typename Stat_>
struct ScoreMarkersPairwiseResults {
    std::vector<std::vector<Stat_> > mean;
 
    std::vector<std::vector<Stat_> > detected;
 
    std::vector<Stat_> cohens_d;
 
    std::vector<Stat_> auc;
 
    std::vector<Stat_> delta_mean;
 
    std::vector<Stat_> delta_detected;
};
 
namespace internal {
 
template<typename Index_, typename Stat_>
void process_simple_pairwise_effects(
    Index_ ngenes,
    size_t ngroups,
    size_t nblocks,
    size_t ncombos,
    std::vector<Stat_>& combo_means,
    std::vector<Stat_>& combo_vars,
    std::vector<Stat_>& combo_detected,
    const ScoreMarkersPairwiseBuffers<Stat_>& output,
    const std::vector<Stat_>& combo_weights,
    double threshold,
    int num_threads)
{
    std::vector<Stat_> total_weights_per_group;
    const Stat_* total_weights_ptr = combo_weights.data();
    if (nblocks > 1) {
        total_weights_per_group = compute_total_weight_per_group(ngroups, nblocks, combo_weights.data());
        total_weights_ptr = total_weights_per_group.data();
    }
    PrecomputedPairwiseWeights<Stat_> preweights(ngroups, nblocks, combo_weights.data());
 
    tatami::parallelize([&](size_t, Index_ start, Index_ length) -> void {
        size_t in_offset = ncombos * static_cast<size_t>(start);
        const auto* tmp_means = combo_means.data() + in_offset;
        const auto* tmp_variances = combo_vars.data() + in_offset;
        const auto* tmp_detected = combo_detected.data() + in_offset;
 
        size_t squared = ngroups * ngroups;
        for (size_t gene = start, end = start + length; gene < end; ++gene) {
            average_group_stats(gene, ngroups, nblocks, tmp_means, tmp_detected, combo_weights.data(), total_weights_ptr, output.mean, output.detected);
 
            // Computing the effect sizes.
            size_t out_offset = gene * squared;
            if (output.cohens_d != NULL) {
                internal::compute_pairwise_cohens_d(tmp_means, tmp_variances, ngroups, nblocks, preweights, threshold, output.cohens_d + out_offset);
            }
 
            if (output.delta_detected != NULL) {
                internal::compute_pairwise_simple_diff(tmp_detected, ngroups, nblocks, preweights, output.delta_detected + out_offset);
            }
 
            if (output.delta_mean != NULL) {
                internal::compute_pairwise_simple_diff(tmp_means, ngroups, nblocks, preweights, output.delta_mean + out_offset);
            }
 
            tmp_means += ncombos;
            tmp_variances += ncombos;
            tmp_detected += ncombos;
        }
    }, ngenes, num_threads);
}
 
template<typename Stat_>
ScoreMarkersPairwiseBuffers<Stat_> fill_pairwise_results(size_t ngenes, size_t ngroups, ScoreMarkersPairwiseResults<Stat_>& store, const ScoreMarkersPairwiseOptions& opt) {
    ScoreMarkersPairwiseBuffers<Stat_> output;
 
    internal::fill_average_results(ngenes, ngroups, store.mean, store.detected, output.mean, output.detected);
 
    size_t num_effect_sizes = ngenes * ngroups * ngroups; // already size_t's, no need to cast.
 
    if (opt.compute_cohens_d) {
        store.cohens_d.resize(num_effect_sizes);
        output.cohens_d = store.cohens_d.data();
    }
    if (opt.compute_auc) {
        store.auc.resize(num_effect_sizes);
        output.auc = store.auc.data();
    }
    if (opt.compute_delta_mean) {
        store.delta_mean.resize(num_effect_sizes);
        output.delta_mean = store.delta_mean.data();
    }
    if (opt.compute_delta_detected) {
        store.delta_detected.resize(num_effect_sizes);
        output.delta_detected = store.delta_detected.data();
    }
 
    return output;
}
 
}
template<typename Value_, typename Index_, typename Group_, typename Stat_>
void score_markers_pairwise(
    const tatami::Matrix<Value_, Index_>& matrix, 
    const Group_* group, 
    const ScoreMarkersPairwiseOptions& options,
    const ScoreMarkersPairwiseBuffers<Stat_>& output) 
{
    Index_ NC = matrix.ncol();
    auto group_sizes = tatami_stats::tabulate_groups(group, NC); 
 
    // In most cases this doesn't really matter, but we do it for consistency with the 1-block case,
    // and to account for variable weighting where non-zero block sizes get zero weight.
    auto group_weights = scran_blocks::compute_weights<Stat_>(group_sizes, options.block_weight_policy, options.variable_block_weight_parameters);
 
    size_t ngroups = group_sizes.size();
    size_t payload_size = static_cast<size_t>(matrix.nrow()) * ngroups; // cast to size_t to avoid overflow.
    std::vector<Stat_> group_means(payload_size), group_vars(payload_size), group_detected(payload_size);
 
    if (output.auc != NULL || matrix.prefer_rows()) {
        internal::scan_matrix_by_row<true>(
            matrix, 
            ngroups,
            group,
            1,
            static_cast<int*>(NULL),
            ngroups,
            NULL,
            group_means,
            group_vars,
            group_detected,
            output.auc,
            group_sizes,
            group_weights,
            options.threshold,
            options.num_threads
        );
 
    } else {
        internal::scan_matrix_by_column(
            matrix,
            ngroups,
            group,
            group_means,
            group_vars,
            group_detected,
            group_sizes,
            options.num_threads
        );
    }
 
    internal::process_simple_pairwise_effects(
        matrix.nrow(),
        ngroups,
        1,
        ngroups,
        group_means,
        group_vars,
        group_detected,
        output,
        group_weights,
        options.threshold,
        options.num_threads);
}
 
template<typename Value_, typename Index_, typename Group_, typename Block_, typename Stat_>
void score_markers_pairwise_blocked(
    const tatami::Matrix<Value_, Index_>& matrix, 
    const Group_* group, 
    const Block_* block,
    const ScoreMarkersPairwiseOptions& options,
    const ScoreMarkersPairwiseBuffers<Stat_>& output) 
{
    Index_ NC = matrix.ncol();
    size_t ngroups = output.mean.size();
    size_t nblocks = tatami_stats::total_groups(block, NC); 
 
    auto combinations = internal::create_combinations(ngroups, group, block, NC);
    auto combo_sizes = internal::tabulate_combinations<Index_>(ngroups, nblocks, combinations);
    size_t ncombos = combo_sizes.size();
    auto combo_weights = scran_blocks::compute_weights<Stat_>(combo_sizes, options.block_weight_policy, options.variable_block_weight_parameters);
 
    size_t payload_size = static_cast<size_t>(matrix.nrow()) * ncombos; // cast to size_t to avoid overflow.
    std::vector<Stat_> combo_means(payload_size), combo_vars(payload_size), combo_detected(payload_size);
 
    if (output.auc != NULL || matrix.prefer_rows()) {
        internal::scan_matrix_by_row<false>(
            matrix, 
            ngroups,
            group,
            nblocks,
            block,
            ncombos,
            combinations.data(),
            combo_means,
            combo_vars,
            combo_detected,
            output.auc,
            combo_sizes,
            combo_weights, 
            options.threshold,
            options.num_threads
        );
 
    } else {
        internal::scan_matrix_by_column(
            matrix,
            ncombos,
            combinations.data(),
            combo_means,
            combo_vars,
            combo_detected,
            combo_sizes,
            options.num_threads
        );
    }
 
    internal::process_simple_pairwise_effects(
        matrix.nrow(),
        ngroups,
        nblocks,
        ncombos,
        combo_means,
        combo_vars,
        combo_detected,
        output,
        combo_weights,
        options.threshold,
        options.num_threads);
}
 
template<typename Stat_ = double, typename Value_, typename Index_, typename Group_>
ScoreMarkersPairwiseResults<Stat_> score_markers_pairwise(const tatami::Matrix<Value_, Index_>& matrix, const Group_* group, const ScoreMarkersPairwiseOptions& options) {
    size_t ngroups = tatami_stats::total_groups(group, matrix.ncol());
    ScoreMarkersPairwiseResults<Stat_> res;
    auto buffers = internal::fill_pairwise_results(matrix.nrow(), ngroups, res, options);
    score_markers_pairwise(matrix, group, options, buffers);
    return res; 
}
 
template<typename Stat_ = double, typename Value_, typename Index_, typename Group_, typename Block_>
ScoreMarkersPairwiseResults<Stat_> score_markers_pairwise_blocked(const tatami::Matrix<Value_, Index_>& matrix, const Group_* group, const Block_* block, const ScoreMarkersPairwiseOptions& options) {
    size_t ngroups = tatami_stats::total_groups(group, matrix.ncol());
    ScoreMarkersPairwiseResults<Stat_> res;
    auto buffers = internal::fill_pairwise_results(matrix.nrow(), ngroups, res, options);
    score_markers_pairwise_blocked(matrix, group, block, options, buffers);
    return res;
}
 
}
 
#endif