scoreMarkers.js

  1. import * as gc from "./gc.js";
  2. import * as wasm from "./wasm.js";
  3. import * as utils from "./utils.js";
  5. /**
  6.  * Wrapper around the marker scoring results on the Wasm heap, typically produced by {@linkcode scoreMarkers}.
  7.  * @hideconstructor
  8.  */
  9. export class ScoreMarkersResults {
  10.     #id;
  11.     #results;
  12.     #has_median;
  13.     #has_max;
  15.     constructor(id, raw, has_median, has_max) {
  16.         this.#id = id;
  17.         this.#results = raw;
  18.         this.#has_median = has_median;
  19.         this.#has_max = has_max;
  20.     }
  22.     /**
  23.      * @return {number} Number of groups in the results.
  24.      */
  25.     numberOfGroups() {
  26.         return this.#results.num_groups();
  27.     }
  29.     /**
  30.      * @param {number} group - Group of interest.
  31.      * Should be non-negative and less than {@linkcode ScoreMarkersResults#numberOfGroups numberOfGroups}.
  32.      * @param {object} [options={}] - Optional parameters.
  33.      * @param {boolean} [options.copy=true] - Whether to copy the results from the Wasm heap, see {@linkcode possibleCopy}.
  34.      *
  35.      * @return {?(Float64Array|Float64WasmArray)} Array of length equal to the number of genes,
  36.      * containing the mean expression for the requested group in the requested block.
  37.      */
  38.     mean(group, options = {}) {
  39.         const { copy = true, ...others } = options;
  40.         utils.checkOtherOptions(others);
  41.         return utils.possibleCopy(this.#results.mean(group), copy);
  42.     }
  44.     /**
  45.      * @param {number} group - Group of interest.
  46.      * Should be non-negative and less than {@linkcode ScoreMarkersResults#numberOfGroups numberOfGroups}.
  47.      * @param {object} [options={}] - Optional parameters.
  48.      * @param {boolean} [options.copy=true] - Whether to copy the results from the Wasm heap, see {@linkcode possibleCopy}.
  49.      *
  50.      * @return {Float64Array|Float64WasmArray} Array of length equal to the number of genes,
  51.      * containing the proportion of cells with detectable expression for the requested group in the requested block.
  52.      */
  53.     detected(group, options = {}) {
  54.         const { copy = true, ...others } = options;
  55.         utils.checkOtherOptions(others);
  56.         return utils.possibleCopy(this.#results.detected(group), copy);
  57.     }
  59.     #check_forbidden(summary) {
  60.         if ((summary == "maximum" && !(this.#has_max)) || (summary == "median" && !(this.#has_median))) {
  61.             throw new Error("summary type '" + summary + "' not available");
  62.         }
  63.     }
  65.     /**
  66.      * @param {number} group - Group of interest.
  67.      * Should be non-negative and less than {@linkcode ScoreMarkersResults#numberOfGroups numberOfGroups}.
  68.      * @param {object} [options={}] - Optional parameters.
  69.      * @param {string} [options.summary="mean"] - Summary statistic to be computed from the Cohen's d values of all pairwise comparisons involving `group`.
  70.      * This can be the `"minimum"` across comparisons, `"mean"` or `"min-rank"`.
  71.      * If the relevant options are set in {@linkcode scoreMarkers}, `"maximum"` and `"median"` are also supported.
  72.      * @param {boolean} [options.copy=true] - Whether to copy the results from the Wasm heap, see {@linkcode possibleCopy}.
  73.      *
  74.      * @return {Float64Array|Float64WasmArray} Array of length equal to the number of genes,
  75.      * containing the summarized Cohen's d for the comparisons between `group` and all other groups.
  76.      */
  77.     cohensD(group, options = {}) {
  78.         const { summary = "mean", copy = true, ...others } = options;
  79.         utils.checkOtherOptions(others);
  80.         this.#check_forbidden(summary);
  81.         return utils.possibleCopy(wasm.call(_ => this.#results.cohens_d(group, summary)), copy);
  82.     }
  84.     /**
  85.      * AUCs are only computed if `computeAuc = true` in {@linkcode scoreMarkers}.
  86.      * If `false`, this method will throw an error.
  87.      *
  88.      * @param {number} group - Group of interest.
  89.      * Should be non-negative and less than {@linkcode ScoreMarkersResults#numberOfGroups numberOfGroups}.
  90.      * @param {object} [options={}] - Optional parameters.
  91.      * @param {string} [options.summary="mean"] - Summary statistic to be computed from the AUCs of all pairwise comparisons involving `group`.
  92.      * This can be the `"minimum"` across comparisons, `"mean"` or `"min-rank"`.
  93.      * If the relevant options are set in {@linkcode scoreMarkers}, `"maximum"` and `"median"` are also supported.
  94.      * @param {boolean} [options.copy=true] - Whether to copy the results from the Wasm heap, see {@linkcode possibleCopy}.
  95.      *
  96.      * @return {Float64Array|Float64WasmArray} Array of length equal to the number of genes,
  97.      * containing the summarized AUC for the comparisons between `group` and all other groups.
  98.      */
  99.     auc(group, options = {}) {
  100.         const { summary = "mean", copy = true, ...others } = options;
  101.         utils.checkOtherOptions(others);
  102.         this.#check_forbidden(summary);
  103.         return utils.possibleCopy(wasm.call(_ => this.#results.auc(group, summary)), copy);
  104.     }
  106.     /**
  107.      * @param {number} group - Group of interest.
  108.      * Should be non-negative and less than {@linkcode ScoreMarkersResults#numberOfGroups numberOfGroups}.
  109.      * @param {object} [options={}] - Optional parameters.
  110.      * @param {string} [options.summary="mean"] - Summary statistic to be computed from the log-fold changes of all pairwise comparisons involving `group`.
  111.      * This can be the `"minimum"` across comparisons, `"mean"` or `"min-rank"`.
  112.      * If the relevant options are set in {@linkcode scoreMarkers}, `"maximum"` and `"median"` are also supported.
  113.      * @param {boolean} [options.copy=true] - Whether to copy the results from the Wasm heap, see {@linkcode possibleCopy}.
  114.      *
  115.      * @return {Float64Array|Float64WasmArray} Array of length equal to the number of genes,
  116.      * containing the summarized delta-mean for the comparisons between `group` and all other groups.
  117.      * This can be interpreted as the log-fold change if log-expression values are used in {@linkcode scoreMarkers}.
  118.      */
  119.     deltaMean(group, options = {}) {
  120.         const { summary = "mean", copy = true, ...others } = options;
  121.         utils.checkOtherOptions(others);
  122.         this.#check_forbidden(summary);
  123.         return utils.possibleCopy(wasm.call(_ => this.#results.delta_mean(group, summary)), copy);
  124.     }
  126.     /**
  127.      * @param {number} group - Group of interest.
  128.      * Should be non-negative and less than {@linkcode ScoreMarkersResults#numberOfGroups numberOfGroups}.
  129.      * @param {object} [options={}] - Optional parameters.
  130.      * @param {string} [options.summary="mean"] - Summary statistic to be computed from the delta-detected values of all pairwise comparisons involving `group`.
  131.      * This can be the `"minimum"` across comparisons, `"mean"` or `"min-rank"`.
  132.      * If the relevant options are set in {@linkcode scoreMarkers}, `"maximum"` and `"median"` are also supported.
  133.      * @param {boolean} [options.copy=true] - Whether to copy the results from the Wasm heap, see {@linkcode possibleCopy}.
  134.      *
  135.      * @return {Float64Array|Float64WasmArray} Array of length equal to the number of genes,
  136.      * containing the summarized delta-detected for the comparisons between `group` and all other groups.
  137.      */
  138.     deltaDetected(group, options = {}) {
  139.         const { summary = "mean", copy = true, ...others } = options;
  140.         utils.checkOtherOptions(others);
  141.         this.#check_forbidden(summary);
  142.         return utils.possibleCopy(wasm.call(_ => this.#results.delta_detected(group, summary)), copy);
  143.     }
  145.     /**
  146.      * @return Frees the memory allocated on the Wasm heap for this object.
  147.      * This invalidates this object and all references to it.
  148.      */
  149.     free() {
  150.         if (this.#results !== null) {
  151.             gc.release(this.#id);
  152.             this.#results = null;
  153.         }
  154.         return;
  155.     }
  156. }
  158. /**
  159.  * Score genes as potential markers for each group of cells.
  160.  *
  161.  * @param {ScranMatrix} x - Log-normalized expression matrix.
  162.  * @param {(Int32WasmArray|Array|TypedArray)} groups - Array containing the group assignment for each cell.
  163.  * This should have length equal to the number of cells and contain all values from 0 to `n - 1` at least once, where `n` is the number of groups.
  164.  * @param {object} [options={}] - Optional parameters.
  165.  * @param {?(Int32WasmArray|Array|TypedArray)} [options.block=null] - Array containing the block assignment for each cell.
  166.  * This should have length equal to the number of cells and contain all values from 0 to `n - 1` at least once, where `n` is the number of blocks.
  167.  * This is used to segregate cells in order to perform comparisons within each block.
  168.  * Alternatively, this may be `null`, in which case all cells are assumed to be in the same block.
  169.  * @param {?number} [options.numberOfThreads=null] - Number of threads to use.
  170.  * If `null`, defaults to {@linkcode maximumThreads}.
  171.  * @param {number} [options.threshold=0] - Threshold on the magnitude of differences between groups, used when computing Cohen's d and AUC.
  172.  * Large positive values favor markers with large differences over those with low variance.
  173.  * For log-expression values in `x`, this can be interpreted as a minimum log-fold change.
  174.  * @param {boolean} [options.computeAuc=true] - Whether to compute the AUCs as an effect size.
  175.  * This can be set to `false` for greater speed and memory efficiency.
  176.  * @param {boolean} [options.computeMedian=false] - Whether to compute the median effect sizes across all pairwise comparisons for each group.
  177.  * This can be used as a more robust/less sensitive alternative to the mean.
  178.  * @param {boolean} [options.computeMaximum=false] - Whether to compute the maximum effect size across all pairwise comparisons for each group.
  179.  * This could be used to find uniquely downregulated genes.
  180.  *
  181.  * @return {ScoreMarkersResults} Object containing the marker scoring results.
  182.  */
  183. export function scoreMarkers(x, groups, options = {}) {
  184.     const { block = null, threshold = 0, computeAuc = true, computeMedian = false, computeMaximum = false , numberOfThreads = null, ...others } = options;
  185.     utils.checkOtherOptions(others);
  187.     var output;
  188.     var block_data;
  189.     var group_data;
  190.     let nthreads = utils.chooseNumberOfThreads(numberOfThreads);
  192.     try {
  193.         group_data = utils.wasmifyArray(groups, "Int32WasmArray");
  194.         if (group_data.length != x.numberOfColumns()) {
  195.             throw new Error("length of 'groups' should be equal to number of columns in 'x'");
  196.         }
  198.         var bptr = 0;
  199.         var use_blocks = false;
  200.         if (block !== null) {
  201.             block_data = utils.wasmifyArray(block, "Int32WasmArray");
  202.             if (block_data.length != x.numberOfColumns()) {
  203.                 throw new Error("'block' must be of length equal to the number of columns in 'x'");
  204.             }
  205.             use_blocks = true;
  206.             bptr = block_data.offset;
  207.         }
  209.         output = gc.call(
  210.             module => module.score_markers(x.matrix, group_data.offset, use_blocks, bptr, threshold, computeAuc, computeMedian, computeMaximum, nthreads),
  211.             ScoreMarkersResults,
  212.             computeMedian,
  213.             computeMaximum
  214.         );
  216.     } catch (e) {
  217.         utils.free(output);
  218.         throw e;
  220.     } finally {
  221.         utils.free(block_data);
  222.         utils.free(group_data);
  223.     }
  225.     return output;
  226. }