adt_quality_control.hpp

Go to the documentation of this file.

#ifndef SCRAN_QC_ADT_QUALITY_CONTROL_HPP
#define SCRAN_QC_ADT_QUALITY_CONTROL_HPP
 
#include <vector>
#include <limits>
#include <algorithm>
#include <type_traits>
#include <cstddef>
 
#include "tatami/tatami.hpp"
#include "sanisizer/sanisizer.hpp"
 
#include "per_cell_qc_metrics.hpp"
#include "choose_filter_thresholds.hpp"
#include "utils.hpp"
 
namespace scran_qc {
 
struct ComputeAdtQcMetricsOptions {
    int num_threads = 1;
 
    bool subset_containers_have_indices = true;
};
 
template<typename Sum_ = double, typename Detected_ = int>
struct ComputeAdtQcMetricsBuffers {
    Sum_* sum;
 
    Detected_* detected;
 
    std::vector<Sum_*> subset_sum;
};
 
template<typename Value_, typename Index_, typename Subset_, typename Sum_, typename Detected_>
void compute_adt_qc_metrics(
    const tatami::Matrix<Value_, Index_>& mat,
    const std::vector<Subset_>& subsets,
    const ComputeAdtQcMetricsBuffers<Sum_, Detected_>& output,
    const ComputeAdtQcMetricsOptions& options)
{
    PerCellQcMetricsBuffers<Sum_, Detected_, Value_, Index_> tmp;
    tmp.sum = output.sum;
    tmp.detected = output.detected;
    tmp.subset_sum = output.subset_sum;
 
    PerCellQcMetricsOptions opt;
    opt.num_threads = options.num_threads;
    opt.subset_containers_have_indices = options.subset_containers_have_indices;
    per_cell_qc_metrics(mat, subsets, tmp, opt);
}
 
template<typename Sum_ = double, typename Detected_ = int>
struct ComputeAdtQcMetricsResults {
    std::vector<Sum_> sum;
 
    std::vector<Detected_> detected;
 
    std::vector<std::vector<Sum_> > subset_sum;
};
 
template<typename Sum_ = double, typename Detected_ = int, typename Value_, typename Index_, typename Subset_>
ComputeAdtQcMetricsResults<Sum_, Detected_> compute_adt_qc_metrics(
    const tatami::Matrix<Value_, Index_>& mat,
    const std::vector<Subset_>& subsets,
    const ComputeAdtQcMetricsOptions& options
) {
    const auto NC = mat.ncol();
    ComputeAdtQcMetricsBuffers<Sum_, Detected_> x;
    ComputeAdtQcMetricsResults<Sum_, Detected_> output;
 
    tatami::resize_container_to_Index_size(output.sum, NC
#ifdef SCRAN_QC_TEST_INIT
        , SCRAN_QC_TEST_INIT
#endif
    );
    x.sum = output.sum.data();
 
    tatami::resize_container_to_Index_size(output.detected, NC
#ifdef SCRAN_QC_TEST_INIT
        , SCRAN_QC_TEST_INIT
#endif
    );
    x.detected = output.detected.data();
 
    const auto nsubsets = subsets.size();
    sanisizer::resize(x.subset_sum, nsubsets);
    sanisizer::resize(output.subset_sum, nsubsets);
    for (I<decltype(nsubsets)> s = 0; s < nsubsets; ++s) {
        tatami::resize_container_to_Index_size(output.subset_sum[s], NC
#ifdef SCRAN_QC_TEST_INIT
            , SCRAN_QC_TEST_INIT
#endif
        );
        x.subset_sum[s] = output.subset_sum[s].data();
    }
 
    compute_adt_qc_metrics(mat, subsets, x, options);
    return output;
}
 
struct ComputeAdtQcFiltersOptions {
    double detected_num_mads = 3;
 
    double detected_min_drop = 0.1;
 
    double subset_sum_num_mads = 3;
};
 
template<typename Float_, class Host_, typename Sum_, typename Detected_, typename BlockSource_>
void compute_adt_qc_filters_internal(
    Host_& host,
    const std::size_t num_cells,
    const ComputeAdtQcMetricsBuffers<Sum_, Detected_>& res,
    BlockSource_ block,
    const std::size_t num_blocks,
    const ComputeAdtQcFiltersOptions& options
) {
    constexpr bool unblocked = std::is_same<BlockSource_, bool>::value;
    auto buffer = [&]{
        if constexpr(unblocked) {
            return sanisizer::create<std::vector<Float_> >(num_cells);
        } else {
            return ChooseFilterThresholdsBlockedWorkspace<Float_>(num_cells, block, num_blocks);
        }
    }();
 
    {
        ChooseFilterThresholdsOptions opts;
        opts.num_mads = options.detected_num_mads;
        opts.log = true;
        opts.upper = false;
        opts.min_diff = -std::log(1 - options.detected_min_drop);
        host.get_detected() = [&]{
            if constexpr(unblocked) {
                return choose_filter_thresholds(num_cells, res.detected, buffer.data(), opts).lower;
            } else {
                return extract_filter_thresholds<true>(choose_filter_thresholds_blocked(num_cells, res.detected, block, num_blocks, buffer, opts));
            }
        }();
    }
 
    {
        const auto nsubsets = res.subset_sum.size();
        auto& host_subsets = host.get_subset_sum();
        sanisizer::resize(host_subsets, nsubsets);
 
        ChooseFilterThresholdsOptions opts;
        opts.num_mads = options.subset_sum_num_mads;
        opts.log = true;
        opts.lower = false;
 
        for (I<decltype(nsubsets)> s = 0; s < nsubsets; ++s) {
            const auto sub = res.subset_sum[s];
            host.get_subset_sum()[s] = [&]{
                if constexpr(unblocked) {
                    return choose_filter_thresholds(num_cells, sub, buffer.data(), opts).upper;
                } else {
                    return extract_filter_thresholds<false>(choose_filter_thresholds_blocked(num_cells, sub, block, num_blocks, buffer, opts));
                }
            }();
        }
    }
}
 
template<class Host_, typename Sum_, typename Detected_, typename BlockSource_, typename Output_>
void apply_adt_qc_filters_internal(
    const Host_& host,
    const std::size_t num_cells,
    const ComputeAdtQcMetricsBuffers<Sum_, Detected_>& metrics,
    BlockSource_ block,
    Output_* const output
) {
    constexpr bool unblocked = std::is_same<BlockSource_, bool>::value;
    std::fill_n(output, num_cells, 1);
 
    const auto& detected = host.get_detected();
    for (I<decltype(num_cells)> i = 0; i < num_cells; ++i) {
        auto thresh = [&]{
            if constexpr(unblocked) {
                return detected;
            } else {
                return detected[block[i]];
            }
        }();
        output[i] = output[i] && (metrics.detected[i] >= thresh);
    }
 
    const auto nsubsets = metrics.subset_sum.size();
    for (I<decltype(nsubsets)> s = 0; s < nsubsets; ++s) {
        const auto sub = metrics.subset_sum[s];
        const auto& sthresh = host.get_subset_sum()[s];
        for (I<decltype(num_cells)> i = 0; i < num_cells; ++i) {
            auto thresh = [&]{
                if constexpr(unblocked) {
                    return sthresh;
                } else {
                    return sthresh[block[i]];
                }
            }();
            output[i] = output[i] && (sub[i] <= thresh);
        }
    }
}
 
template<typename Sum_, typename Detected_>
ComputeAdtQcMetricsBuffers<const Sum_, const Detected_> adt_qc_results_to_buffers(const ComputeAdtQcMetricsResults<Sum_, Detected_>& metrics) {
    ComputeAdtQcMetricsBuffers<const Sum_, const Detected_> buffer;
    buffer.sum = metrics.sum.data();
    buffer.detected = metrics.detected.data();
    buffer.subset_sum.reserve(metrics.subset_sum.size());
    for (const auto& s : metrics.subset_sum) {
        buffer.subset_sum.push_back(s.data());
    }
    return buffer;
}
template<typename Float_ = double>
class AdtQcFilters {
public:
    Float_ get_detected() const {
        return my_detected;
    }
 
    const std::vector<Float_>& get_subset_sum() const {
        return my_subset_sum;
    }
 
    Float_& get_detected() {
        return my_detected;
    }
 
    std::vector<Float_>& get_subset_sum() {
        return my_subset_sum;
    }
 
private:
    Float_ my_detected = 0;
    std::vector<Float_> my_subset_sum;
 
public:
    template<typename Sum_, typename Detected_, typename Output_>
    void filter(const std::size_t num_cells, const ComputeAdtQcMetricsBuffers<Sum_, Detected_>& metrics, Output_* const output) const {
        apply_adt_qc_filters_internal(*this, num_cells, metrics, false, output);
    }
 
    template<typename Sum_, typename Detected_, typename Output_>
    void filter(const ComputeAdtQcMetricsResults<Sum_, Detected_>& metrics, Output_* const output) const {
        return filter(metrics.detected.size(), adt_qc_results_to_buffers(metrics), output);
    }
 
    template<typename Output_ = unsigned char, typename Sum_, typename Detected_>
    std::vector<Output_> filter(const ComputeAdtQcMetricsResults<Sum_, Detected_>& metrics) const {
        auto output = sanisizer::create<std::vector<Output_> >(metrics.detected.size()
#ifdef SCRAN_QC_TEST_INIT
            , SCRAN_QC_TEST_INIT
#endif
        );
        filter(metrics, output.data());
        return output;
    }
};
 
template<typename Float_ = double, typename Sum_, typename Detected_>
AdtQcFilters<Float_> compute_adt_qc_filters(
    const std::size_t num_cells,
    const ComputeAdtQcMetricsBuffers<Sum_, Detected_>& metrics,
    const ComputeAdtQcFiltersOptions& options
) {
    AdtQcFilters<Float_> output;
    compute_adt_qc_filters_internal<Float_>(output, num_cells, metrics, false, 0, options);
    return output;
}
 
template<typename Float_ = double, typename Sum_, typename Detected_>
AdtQcFilters<Float_> compute_adt_qc_filters(const ComputeAdtQcMetricsResults<Sum_, Detected_>& metrics, const ComputeAdtQcFiltersOptions& options) {
    return compute_adt_qc_filters(metrics.detected.size(), adt_qc_results_to_buffers(metrics), options);
}
 
template<typename Float_ = double>
class AdtQcBlockedFilters {
public:
    const std::vector<Float_>& get_detected() const {
        return my_detected;
    }
 
    const std::vector<std::vector<Float_> >& get_subset_sum() const {
        return my_subset_sum;
    }
 
    std::vector<Float_>& get_detected() {
        return my_detected;
    }
 
    std::vector<std::vector<Float_> >& get_subset_sum() {
        return my_subset_sum;
    }
 
private:
    std::vector<Float_> my_sum;
    std::vector<Float_> my_detected;
    std::vector<std::vector<Float_> > my_subset_sum;
 
public:
    template<typename Sum_, typename Detected_, typename Block_, typename Output_>
    void filter(const std::size_t num_cells, const ComputeAdtQcMetricsBuffers<Sum_, Detected_>& metrics, const Block_* block, Output_* const output) const {
        apply_adt_qc_filters_internal(*this, num_cells, metrics, block, output);
    }
 
    template<typename Sum_, typename Detected_, typename Block_, typename Output_>
    void filter(const ComputeAdtQcMetricsResults<Sum_, Detected_>& metrics, const Block_* const block, Output_* const output) const {
        return filter(metrics.detected.size(), adt_qc_results_to_buffers(metrics), block, output);
    }
 
    template<typename Output_ = unsigned char, typename Sum_, typename Detected_, typename Block_>
    std::vector<Output_> filter(const ComputeAdtQcMetricsResults<Sum_, Detected_>& metrics, const Block_* const block) const {
        auto output = sanisizer::create<std::vector<Output_> >(metrics.detected.size()
#ifdef SCRAN_QC_TEST_INIT
            , SCRAN_QC_TEST_INIT
#endif
        );
        filter(metrics, block, output.data());
        return output;
    }
};
 
template<typename Float_ = double, typename Sum_, typename Detected_, typename Block_>
AdtQcBlockedFilters<Float_> compute_adt_qc_filters_blocked(
    const std::size_t num_cells,
    const ComputeAdtQcMetricsBuffers<Sum_, Detected_>& metrics,
    const Block_* const block,
    const std::size_t num_blocks,
    const ComputeAdtQcFiltersOptions& options
) {
    AdtQcBlockedFilters<Float_> output;
    compute_adt_qc_filters_internal<Float_>(output, num_cells, metrics, block, num_blocks, options);
    return output;
}
 
template<typename Float_ = double, typename Sum_, typename Detected_, typename Block_>
AdtQcBlockedFilters<Float_> compute_adt_qc_filters_blocked(
    const ComputeAdtQcMetricsResults<Sum_, Detected_>& metrics,
    const Block_* const block,
    const std::size_t num_blocks,
    const ComputeAdtQcFiltersOptions& options
) {
    return compute_adt_qc_filters_blocked(metrics.detected.size(), adt_qc_results_to_buffers(metrics), block, num_blocks, options);
}
 
}
 
#endif