Global

Methods

aggregateAcrossCells(x, groups, optionsopt) → {AggregateAcrossCellsResults}

Source:

Aggregate per-cell expression profiles for each group of cells. This is typically used to summarize data into per-cluster expression profiles for easier inspection.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

Some expression matrix, typically containing normalized log-expression values.
groups Int32Array | Int32WasmArray

Array containing group IDs for each cell. 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.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
average boolean <optional>
 false

Whether to compute the average expression instead of the sum for each group. Similarly, the proportion of detected expression is reported, rather than the number of detected cells in each group.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the aggregation results.

Type
AggregateAcrossCellsResults

buildLabelledReference(features, loaded, referenceFeatures, optionsopt) → {BuildLabelledReferenceResults}

Source:

Build the reference dataset for annotation. The build process involves harmonizing the identities of the features available in the test dataset compared to the reference. Specifically, a feature must be present in both datasets in order to be retained. Of those features in the intersection, only the top markers from each pairwise comparison are ultimately used for classification.

Needless to say, features should match up to the rows of the ScranMatrix that is actually used for annotation in labelCells.

Parameters:
Name Type Attributes Default Description
features Array

An array of feature identifiers (usually strings) of length equal to the number of rows in the test matrix. Each entry should contain the identifier for the corresponding row of the test matrix. Any null entries are considered to be incomparable. If any identifiers are duplicated, only the first occurrence is used and the rest are ignored.
loaded LoadLabelledReferenceResults

A reference dataset, typically loaded with loadLabelledReferenceFromBuffers.
referenceFeatures Array

An array of feature identifiers (usually strings) of length equal to the number of features in reference. Each entry may also be an array of synonymous identifiers, in which case the first identifier that matches to an entry of features is used. Contents of referenceFeatures are expected to exhibit some overlap with identifiers in features. Any null entries are considered to be incomparable. If multiple entries of referenceFeatures match to the same feature in features, only the first matching entry is used and the rest are ignored.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
top number <optional>
 20

Number of top marker features to use. These features are taken from each pairwise comparison between labels.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the built reference dataset.

Type
BuildLabelledReferenceResults

buildNeighborSearchIndex(x, optionsopt) → {BuildNeighborSearchIndexResults}

Source:

Build the nearest neighbor search index.

Parameters:
Name Type Attributes Default Description
x RunPcaResults | Float64WasmArray | Array | TypedArray

Numeric coordinates of each cell in the dataset. For array inputs, this is expected to be in column-major format where the rows are the variables and the columns are the cells. For a RunPcaResults input, we extract the principal components.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfDims number <optional>
<nullable>
 null

Number of variables/dimensions per cell. Only used (and required) for array-like x.
numberOfCells number <optional>
<nullable>
 null

Number of cells. Only used (and required) for array-like x.
approximate boolean <optional>
 true

Whether to build an index for an approximate neighbor search.
Returns:

Index object to use for neighbor searches.

Type
BuildNeighborSearchIndexResults

buildSnnGraph(x, optionsopt) → {BuildSnnGraphResults}

Source:

Build a shared nearest graph.

Parameters:
Name Type Attributes Default Description
x BuildNeighborSearchIndexResults | FindNearestNeighborsResults

Either a pre-built neighbor search index for the dataset (see buildNeighborSearchIndex), or a pre-computed set of neighbor search results for all cells (see findNearestNeighbors).
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
scheme number <optional>
 "rank"

Weighting scheme for the edges between cells. This can be based on the top ranks of the shared neighbors ("rank"), the number of shared neighbors ("number") or the Jaccard index of the neighbor sets between cells ("jaccard").
neighbors number <optional>
 10

Number of nearest neighbors to use to construct the graph. Ignored if x is a FindNearestNeighborsResults object.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the graph.

Type
BuildSnnGraphResults

cbind(inputs) → {ScranMatrix}

Source:

Combine matrices by column, where all matrices contain data for the same features, in the same order.

Parameters:
Name Type Description
inputs Array

Array of one or more ScranMatrix objects. All of these should have the same number and order of features.
Returns:

A ScranMatrix containing the matrices after combining them by column.

Type
ScranMatrix

cbindWithNames(inputs, names) → {object}

Source:

Combine matrices by column, after subsetting each matrix to the intersection of common features.

Parameters:
Name Type Description
inputs Array

Array of one or more ScranMatrix objects.
names Array

Array of length equal to inputs. Each entry should be an Array containing the row names of the corresponding entry of inputs. Names should correspond to the rows of that entry of inputs. Any null names are ignored. If names are duplicated within each array, only the first occurrence is considered in the intersection.
Returns:

An object containing:

  • matrix, a ScranMatrix containing the combined matrices.
  • indices, an Int32Array of length equal to the number of rows in matrix. This contains the index of the row in the first entry of inputs corresponding to each row of matrix, i.e., the gene at the i-th row of matrix is the same as the gene at the indices[i]-th row of inputs[0]. This is guaranteed to be sorted.
  • names, an array of names identifying the rows of matrix. This is constructed by indexing the first entry of names with indices.
Type
object

centerSizeFactors(sizeFactors, optionsopt) → {Float64WasmArray}

Source:

Center size factors in preparation for log-transformation. This is usually called by logNormCounts internally, but can also be directly called by users to reconstitute the size factors used in the log-normalized matrix.

Parameters:
Name Type Attributes Default Description
sizeFactors TypedArray | WasmArray

Array of non-negative size factors, one per cell.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell, see logNormCounts.
buffer Float64WasmArray <optional>
<nullable>
 null

Buffer in which to store the output size factors. Length should be equal to that of sizeFactors. If null, an array is allocated by the function.
Returns:

Array containing the centered size factors. If buffer is provided, it is returned directly.

Type
Float64WasmArray

chooseHvgs(x, optionsopt) → {Uint8WasmArray}

Source:

Choose the highly variable genes from variance modelling statistics.

Parameters:
Name Type Attributes Default Description
x TypedArray | ModelGeneVariancesResults

A TypedArray of statistics, where larger values correspond to higher variability; or a ModelGeneVariancesResults object, in which case the residuals are used as the statistics.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
number number <optional>
 4000

Number of highly variable genes to select.
minimum number <optional>
 0

Minimum value of the residual to consider for a highly variable gene. By default, a highly variable gene must have a non-negative residual.
Returns:

Array of length equal to the total number of genes, where the chosen highly variable genes are marked with a value of 1 and all other genes have values of zero.

Type
Uint8WasmArray

chooseTemporaryPath(optionsopt) → {string}

Source:

Choose a temporary file path on the system's default temporary directory (Node.js) or on the virtual file system (browser). This can be used to enable environment-agnostic creation of temporary files.

Parameters:
Name Type Attributes Default Description
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
extension string <optional>
 ""

File extension to use for any temporary file that might be created.
Returns:

Temporary file path.

Type
string

clusterKmeans(x, clusters, optionsopt) → {ClusterKmeansResults}

Source:

Cluster cells using k-means.

Parameters:
Name Type Attributes Default Description
x RunPcaResults | Float64WasmArray | Array | TypedArray

Numeric coordinates of each cell in the dataset. For array inputs, this is expected to be in column-major format where the rows are the variables and the columns are the cells. For a RunPcaResults input, we extract the principal components.
clusters number

Number of clusters to create. This should not be greater than the number of cells.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfDims number <optional>
<nullable>
 null

Number of variables/dimensions per cell. Only used (and required) for array-like x.
numberOfCells number <optional>
<nullable>
 null

Number of cells. Only used (and required) for array-like x.
initMethod string <optional>
 "pca-part"

Initialization method. Setting "random" will randomly select clusters cells as centers. Setting "kmeans++" will use the weighted sampling approach of Arthur and Vassilvitskii (2007). Setting "pca-part" will use PCA partitioning.
initSeed number <optional>
 5768

Seed to use for random number generation during initialization.
initPCASizeAdjust number <optional>
 1

Adjustment factor for the cluster sizes, used when initMethod = "pca-part". Larger values (up to 1) will prioritize partitioning of clusters with more cells.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the clustering results.

Type
ClusterKmeansResults

clusterSnnGraph(x, optionsopt) → {ClusterSnnGraphMultiLevelResults|ClusterSnnGraphWalktrapResults|ClusterSnnGraphLeidenResults}

Source:

Cluster cells using community detection on the SNN graph.

Parameters:
Name Type Attributes Default Description
x BuildSnnGraphResults

The shared nearest neighbor graph constructed by buildSnnGraph.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
method string <optional>
 "multilevel"

Community detection method to use. This should be one of "multilevel", "walktrap" or "leiden".
multiLevelResolution number <optional>
 1

The resolution of the multi-level clustering, when method = "multilevel". Larger values result in more fine-grained clusters.
leidenResolution number <optional>
 1

The resolution of the Leiden clustering, when method = "leiden". Larger values result in more fine-grained clusters.
leidenModularityObjective boolean <optional>
 false

Whether to use the modularity as the objective function when method = "leiden". By default, the Constant-Potts Model is used instead. Set to true to get an interpretation of the resolution on par with that of method = "multilevel".
walktrapSteps number <optional>
 4

Number of steps for the Walktrap algorithm, when method = "walktrap".
Returns:

Object containing the clustering results. The class of this object depends on the choice of method.

Type
ClusterSnnGraphMultiLevelResults | ClusterSnnGraphWalktrapResults | ClusterSnnGraphLeidenResults

computeTopThreshold(x, number, optionsopt) → {number}

Source:

Compute the filter threshold required to retain the top number values.

Parameters:
Name Type Attributes Default Description
x Array | TypedArray

Array of numeric values, typically per-gene statistics.
number number

Number of top values to retain after filtering on the returned threshold. This may be approximate in the presence of ties.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
largest boolean <optional>
 true

Whether the top values in x are defined as the largest numeric values. If false, the top values are considered to be the smallest.
copy boolean <optional>
 true

Whether to copy x before sorting. If false, x may be modified in-place.
Returns:

Threshold to be applied to x to obtain the top (approximately) number values. If largest = true, filtering is performed by taking all values in x that are greater than or equal to the returned threshold; if false, filtering is performed by taking all values in x that are less than or equal to the returned threshold. If x is zero-length, NaN is returned.

Type
number

convertToFactor(x, optionsopt) → {object}

Source:

Convert an arbitrary array into a R-style factor, with integer indices into an array of levels. This is useful for formatting grouping or blocking vectors for scoreMarkers, modelGeneVar, etc.

Parameters:
Name Type Attributes Default Description
x Array | TypedArray

Array of values to be converted into a factor.

Note that TypedArray views on Wasm-allocated buffers should only be provided if buffer is also provided; otherwise, a Wasm memory allocation may invalidate the view.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
asWasmArray boolean <optional>
 true

Whether to return an Int32WasmArray instance for the indices. If false, an Int32Array is returned instead. Only used if buffer is not supplied.
buffer Int32WasmArray | Int32Array <optional>
<nullable>
 null

Array in which the output is to be stored. If provided, this should be of length equal to that of x.
levels Array <optional>
<nullable>
 null

An existing array of known levels to be matched against x. Values in x that are not in levels are considered to be invalid. If null, the levels are automatically inferred from x; these will be sorted if all-numeric or all-string.
action string <optional>
 "error"

Action to take when invalid values (i.e., null, NaNs) are detected in x.

  • "none": the index is silently set to placeholder.
  • "warn": a warning is raised on the first occurrence of an invalid value, and the index is set to placeholder.
  • "error": an error is raised.
placeholder number <optional>
 -1

Placeholder index to use upon detecting invalid values in x.
Returns:

Object containing:

  • ids: an Int32WasmArray or Int32Array of length equal to x, containing the index into levels for each cell.
  • levels: an array of unique levels, such that Array.from(ids).map(i => levels[i]) returns the same contents as x (aside from invalid values). If an input levels is supplied, this is returned directly.

If buffer was supplied, it is used as the value of the ids property.

Type
object

createBigUint64WasmArray(length) → {BigUint64WasmArray}

Source:

Helper function to create a BigUint64WasmArray from the wasmarrays.js package.

Parameters:
Name Type Description
length number

Length of the array.
Returns:

BigUint64WasmArray on the scran.js Wasm heap.

Type
BigUint64WasmArray

createBlock(ncells, optionsopt) → {Int32WasmArray}

Source:

Create a blocking factor for a set of contiguous blocks, usually to accompany the output of cbind on matrices representing different batches. This can be used as the blocking factor in functions such as modelGeneVar or scoreMarkers. Note that no protection is provided against empty blocks; if this is a possibility, use dropUnusedBlock on the output of this function.

Parameters:
Name Type Attributes Default Description
ncells Array | TypedArray

Array of integers specifying the number of cells in each block.

Note that TypedArray views on Wasm-allocated buffers should only be provided if buffer is also provided; otherwise, a Wasm memory allocation may invalidate the view.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
buffer Int32WasmArray <optional>
<nullable>
 null

Array in which the output is to be stored. If provided, this should be of length equal to the sum of ncells.
Returns:

Array containing the blocking factor. Each value specifies the block of origin for each cell.

If buffer was supplied, it is used as the return value.

Type
Int32WasmArray

createFloat64WasmArray(length) → {Float64WasmArray}

Source:

Helper function to create a Float64WasmArray from the wasmarrays.js package.

Parameters:
Name Type Description
length number

Length of the array.
Returns:

Float64WasmArray on the scran.js Wasm heap.

Type
Float64WasmArray

createInt32WasmArray(length) → {Int32WasmArray}

Source:

Helper function to create a Int32WasmArray from the wasmarrays.js package.

Parameters:
Name Type Description
length number

Length of the array.
Returns:

Int32WasmArray on the scran.js Wasm heap.

Type
Int32WasmArray

createNewHdf5File(path) → {H5File}

Source:

Create a new HDF5 file.

Parameters:
Name Type Description
path string

Path to the file.
Returns:

A new file is created at path. A H5File object is returned.

Type
H5File

createUint8WasmArray(length) → {Uint8WasmArray}

Source:

Helper function to create a Uint8WasmArray from the wasmarrays.js package.

Parameters:
Name Type Description
length number

Length of the array.
Returns:

Uint8WasmArray on the scran.js Wasm heap.

Type
Uint8WasmArray

delayedArithmetic(x, operation, value, optionsopt) → {ScranMatrix}

Source:

Apply delayed arithmetic to a ScranMatrix object.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

A ScranMatrix object.
operation string

The operation to perform, one of "+", "*", "/" or "-".
value number | Array | WasmArray | TypedArray

The other operand in the arithmetic operation. If a scalar, this is applied element-wise to each entry of x. If a vector, it is assumed to map to either the rows or columns of x (see along) and each entry is applied to all values of the corresponding row/column.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
right boolean <optional>
 true

Whether value is applied to the right of x. Only relevant for subtraction or division.
along string <optional>
 "row"

Whether an array-like value maps to the rows ("row") or columns ("column"). If rows, value should have length equal to x.numberOfRows(). If columns, value should have length equal to x.numberOfColumns().
inPlace boolean <optional>
 false

Whether to modify x in place. If false, a new ScranMatrix is returned.
Returns:

A ScranMatrix containing the delayed arithmetic operation on x. If inPlace = true, this is a reference to x, otherwise it is a new ScranMatrix.

Type
ScranMatrix

delayedMath(x, operation, optionsopt) → {ScranMatrix}

Source:

Apply delayed math to a ScranMatrix object.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

A ScranMatrix object.
operation string

The operation to perform, one of "log", "sqrt", "abs", "log1p", "round" or "exp".
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
logBase number <optional>
 null

Base of the logarithm to use when operation = "log". Defaults to the natural base.
inPlace boolean <optional>
 false

Whether to modify x in place. If false, a new ScranMatrix is returned.
Returns:

A ScranMatrix containing the delayed math operation on x. If inPlace = true, this is a reference to x, otherwise it is a new ScranMatrix.

Type
ScranMatrix

dropUnusedLevels(x) → {Array}

Source:

Reindex the factor indices to remove unused levels. This is done by adjusting the indices such that every index from [0, N) is represented at least once, where N is the number of (used) levels.

Parameters:
Name Type Description
x Int32WasmArray | TypedArray | Array

Array of factor indices such as that produced by convertToFactor.
Returns:

x is modified in place to remove unused levels.

An array (denoted here as y) is returned that represents the mapping between the original and modified IDs, i.e., running x.map(i => y[i]) will recover the input x. This is most commonly used to create a new array of levels, i.e., y.map(i => old_levels[i]) will drop the unused levels.

Type
Array

emptyClusterSnnGraphResults(numberOfCells, optionsopt) → {ClusterSnnGraphMultiLevelResults|ClusterSnnGraphWalktrapResults|ClusterSnnGraphLeidenResults}

Source:

Create an empty ClusterSnnGraphMultiLevelResults object (or one of its counterparts), to be filled with custom results. Note that filling requires use of fillable: true in the various getters to obtain a writeable memory view.

Parameters:
Name Type Attributes Default Description
numberOfCells number

Number of cells in the dataset.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
method string <optional>
 "multilevel"

Community detection method to use. This should be one of "multilevel", "walktrap" or "leiden".
numberOfLevels number <optional>
 1

Number of levels for which to allocate space when method="multilevel".
numberOfMergeSteps number <optional>
 1

Number of merge steps for which to allocate space when method="walktrap".
Returns:

Object with space allocated to store the clustering results.

Type
ClusterSnnGraphMultiLevelResults | ClusterSnnGraphWalktrapResults | ClusterSnnGraphLeidenResults

emptyPerCellAdtQcMetricsResults(numberOfCells, numberOfSubsets) → {PerCellAdtQcMetricsResults}

Source:

Create an empty PerCellAdtQcMetricsResults object, to be filled with custom results. This is typically used to generate a convenient input into later computePerCellAdtQcFilters calls. Note that filling requires use of fillable: true in the various getters to obtain a writeable memory view.

Parameters:
Name Type Description
numberOfCells number

Number of cells in the dataset.
numberOfSubsets number

Number of feature subsets.
Returns:

Object with allocated memory but no actual values.

Type
PerCellAdtQcMetricsResults

emptyPerCellCrisprQcMetricsResults(numberOfCells) → {PerCellCrisprQcMetricsResults}

Source:

Create an empty PerCellCrisprQcMetricsResults object, to be filled with custom results. This is typically used to generate a convenient input into later suggestCrisprQcFilters calls. Note that filling requires use of fillable: true in the various getters to obtain a writeable memory view.

Parameters:
Name Type Description
numberOfCells number

Number of cells in the dataset.
Returns:

Object with allocated memory to store QC metrics, but no actual values.

Type
PerCellCrisprQcMetricsResults

emptyPerCellRnaQcMetricsResults(numberOfCells, numberOfSubsets) → {PerCellRnaQcMetricsResults}

Source:

Create an empty PerCellRnaQcMetricsResults object, to be filled with custom results. This is typically used to generate a convenient input into later suggestRnaQcFilters calls. Note that filling requires use of fillable: true in the various getters to obtain a writeable memory view.

Parameters:
Name Type Description
numberOfCells number

Number of cells in the dataset.
numberOfSubsets number

Number of feature subsets.
Returns:

Object with allocated memory to store QC metrics, but no actual values.

Type
PerCellRnaQcMetricsResults

emptySuggestAdtQcFiltersResults(numberOfSubsets, numberOfBlocks) → {SuggestAdtQcFiltersResults}

Source:

Create an empty SuggestAdtQcFiltersResults object, to be filled with custom results. This is typically used to generate a convenient input into later filterCells calls.

Parameters:
Name Type Description
numberOfSubsets number

Number of feature subsets.
numberOfBlocks number

Number of blocks in the dataset.
Returns:

Object with allocated memory to store QC filters, but no actual values.

Type
SuggestAdtQcFiltersResults

emptySuggestCrisprQcFiltersResults(numberOfBlocks) → {SuggestCrisprQcFiltersResults}

Source:

Create an empty SuggestCrisprQcFiltersResults object, to be filled with custom results. This is typically used to generate a convenient input into later filterCells calls.

Parameters:
Name Type Description
numberOfBlocks number

Number of blocks in the dataset.
Returns:

Object with allocated memory to store QC filters, but no actual values.

Type
SuggestCrisprQcFiltersResults

emptySuggestRnaQcFiltersResults(numberOfSubsets, numberOfBlocks) → {SuggestRnaQcFiltersResults}

Source:

Create an empty SuggestRnaQcFiltersResults object, to be filled with custom results. Note that filling requires use of fillable: true in the various getters to obtain a writeable memory view.

Parameters:
Name Type Description
numberOfSubsets number

Number of feature subsets.
numberOfBlocks number

Number of blocks in the dataset.
Returns:

Object with allocated memory to store QC filters, but no actual values.

Type
SuggestRnaQcFiltersResults

existsFile(path) → {boolean}

Source:

Check if a file exists on the native file system (Node.js) or the virtual file system (browser).

Parameters:
Name Type Description
path string

Path to the file on the relevant file system.
Returns:

Whether the file exists.

Type
boolean

extractHdf5MatrixDetails(file, name) → {object}

Source:

Extract the format and dimensions of a HDF5 matrix.

Parameters:
Name Type Description
file string

Path to the HDF5 file. For browsers, the file should have been saved to the virtual filesystem.
name string

Name of the dataset inside the file. This can be a HDF5 Dataset for dense matrices or a HDF5 Group for sparse matrices. For the latter, both H5AD and 10X-style sparse formats are supported.
Returns:

An object containing:

  • rows, the number of rows in the matrix.
  • columns, the number of columns.
  • format, whether the matrix is dense, CSR or CSC.
  • integer, whether the matrix data is stored as integers or doubles.
Type
object

extractHdf5ObjectNames(path, optionsopt) → {object}

Source:

Extract object names from a HDF5 file.

Parameters:
Name Type Attributes Default Description
path string

Path to a HDF5 file. For web applications, this should be saved to the virtual filesystem with writeFile.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
group string <optional>
 ""

Group to use as the root of the search. If an empty string is supplied, the entire file is used as the root.
recursive boolean <optional>
 true

Whether to recursively extract names inside child groups.
Returns:

Nested object where the keys are the names of the HDF5 objects and values are their types. HDF5 groups are represented by nested Javascript objects in the values; these nested objects are empty if recursive = false. HDF5 datasets are represented by strings specifying the data type - i.e., "integer", "float", "string" or "other".

Type
object

extractMatrixMarketDimensions(buffer, optionsopt) → {object}

Source:

Extract dimensions and other details from a MatrixMarket file.

Parameters:
Name Type Attributes Default Description
buffer Uint8WasmArray | Array | TypedArray | string

Byte array containing the contents of a Matrix Market file with non-negative counts. This can be raw text or Gzip-compressed.

Alternatively, this can be a string containing a file path to a MatrixMarket file. On browsers, this should be a path in the virtual filesystem, typically created with writeFile.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
compressed boolean <optional>
 null

Whether the buffer is Gzip-compressed. If null, we detect this automatically from the magic number in the header.
Returns:

An object containing the number of rows, columns and lines in the matrix.

Type
object

filterCells(x, filters) → {ScranMatrix}

Source:

Filter out low-quality cells.

Parameters:
Name Type Description
x ScranMatrix

The count matrix.
filters Uint8WasmArray | Array | TypedArray

An array of length equal to the number of columns in x, where truthy elements specify the cells to be discarded.
Returns:

A matrix of the same type as x, filtered by column to remove all cells specified in filters.

Type
ScranMatrix

findNearestNeighbors(x, k, optionsopt) → {FindNearestNeighborsResults}

Source:

Find the nearest neighbors for each cell.

Parameters:
Name Type Attributes Default Description
x NeighborSearchIndex

The neighbor search index built by buildNeighborSearchIndex.
k number

Number of neighbors to find.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the search results.

Type
FindNearestNeighborsResults

free(xnullable)

Source:

Try to free a scran.js object's memory (typically involving some memory allocated on the Wasm heap) by calling its free method.

Parameters:
Name Type Attributes Description
x object <nullable>

Instance of a scran.js or wasmarrays.js class to be freed. May also be null or undefined.
Returns:

The output of x.free() - unless x is undefined or null, in which case nothing is performed.

groupedSizeFactors(x, groups, optionsopt) → {Float64WasmArray}

Source:

Compute group-based size factors, where composition biases are removed between groups and library size normalization is performed within groups. This allows us to generate per-cell size factors in spite of the sparsity.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The count matrix, usually after filtering.
groups Int32WasmArray | Array | TypedArray

Array containing the group assignment for each cell. 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.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
center boolean <optional>
 true

Whether to return centered size factors. If false, the size factors can be interpreted as the scaling to match reference.
allowZeros boolean <optional>
 false

Whether size factors of zero should be allowed for the groups. If true, any size factors of zero are converted to the smallest non-zero size factor across all groups. If false, an error is raised instead.
allowZeros boolean <optional>
 false

Whether non-finite size factors should be allowed for the groups. If true, size factors of infinity or NaN are converted to the largest non-zero size factor across all groups or 1, respectively. If false, an error is raised instead.
buffer Float64WasmArray <optional>
<nullable>
 null

Output buffer for the size factors. This should have length equal to the number of columns in x.
priorCount number <optional>
 10

Prior count to use for shrinking size factors towards the relative library size. Larger values result in stronger shrinkage when the coverage is low.
reference number <optional>
<nullable>
 null

Group to use as a reference. This should be an entry in groups. If null, it is automatically determined.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Array of length equal to the number of columns in x, containing the size factors for all cells.

If buffer was supplied, it is used as the return value.

Type
Float64WasmArray

guessFeatures(features, optionsopt) → {object}

Source:

Guess the identity of the features from their names.

Parameters:
Name Type Attributes Default Description
features Array

Array of strings containing feature identifiers, typically Ensembl IDs or gene symbols. Elements may also be null or undefined if an identifier is missing.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceTaxonomy boolean <optional>
 false

Whether to force the use of taxonomy IDs for human and mouse. This is false for back compatibility.
Returns:

An object containing:

  • species, the inferred species as a string. This can be either "human" or "mouse", or an NCBI taxonomy ID (one of 6239, 10116, 9541, 7227, 7955, 9598). If forceTaxonomy = true, human and mouse are replaced with 9606 and 10090, respectively.
  • type: the feature identifier type. This can either be "ensembl" or "symbol".
  • confidence: the percentage of entries in x that are consistent with the inferred identity.
Type
object

heapSize() → {number}

Source:
Returns:

The current size of the Wasm heap, typically used for diagnostic reporting.

Type
number

hypergeometricTest(markersInSet, numberOfMarkers, featureSetSize, numberOfFeatures, optionsopt) → {Float64Array}

Source:

Perform a hypergeometric test, typically for over-enrichment of markers across feature sets. This can be computed for multiple feature sets by providing arrays as some or all of the arguments. If multiple arrays are supplied, they must be of the same length.

Parameters:
Name Type Attributes Default Description
markersInSet number | Array | TypedArray | WasmArray

Number of detected markers that are also in the feature set.
numberOfMarkers number | Array | TypedArray | WasmArray

Total number of detected markers.
featureSetSize number | Array | TypedArray | WasmArray

Size of the feature set.
numberOfFeatures number | Array | TypedArray | WasmArray

Total number of features.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
assumeSorted boolean <optional>
 false

Whether the input arrays are already sorted such that markersInSet is the slowest-changing value. Setting this to true can avoid an extra sorting step for greater efficiency.
Returns:

An array of length equal to that of the supplied arrays (or 1, if no arrays are supplied). The i-th entry contains the p-value for enrichment computed using the i-th entry of each supplied array.

Type
Float64Array

initialize(optionsopt) → {boolean}

Source:
Parameters:
Name Type Attributes Default Description
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfThreads number <optional>
 4

Number of threads to use for calculations. This will spin up the requested number of Web Workers during module initialization.
localFile boolean <optional>
 false

Whether or not to look for the Wasm and worker scripts locally. This should only be true when using old versions of Node.js where file URLs are not supported, and is ignored completely outside of Node.js contexts.
Returns:

The Wasm bindings are initialized and true is returned. If the bindings were already initialized (e.g., by a previous call), nothing is done and false is returned.

Type
boolean

initializeDenseMatrixFromDenseArray(numberOfRows, numberOfColumns, values, optionsopt) → {ScranMatrix}

Source:

Initialize a dense matrix from a column-major array.

Parameters:
Name Type Attributes Default Description
numberOfRows number

Number of rows.
numberOfColumns number

Number of columns.
values WasmArray | TypedArray | Array

Array of length equal to the product of numberOfRows and numberOfColumns, containing the values to store in the array.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceInteger boolean <optional>
 true

Whether to coerce values to integers via truncation.
Returns:

A dense matrix, filled by column with the contents of values.

Type
ScranMatrix

initializeSparseMatrixFromCompressedVectors(numberOfRows, numberOfColumns, values, indices, pointers, optionsopt) → {ScranMatrix}

Source:

Initialize a sparse matrix from its compressed components.

Parameters:
Name Type Attributes Default Description
numberOfRows number

Number of rows in the matrix.
numberOfColumns number

Number of columns in the matrix.
values WasmArray

Values of the non-zero elements. This is generally expected to contain non-negative integers; otherwise, users should set forceInteger = false.
indices WasmArray

Row indices of the non-zero elements. This should be of the same length as values.
pointers WasmArray

Pointers specifying the start of each column in indices. This should have length equal to numberOfColumns + 1.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
byRow boolean <optional>
 true

Whether the input arrays are supplied in the compressed sparse column format. If true, indices should contain column indices and pointers should specify the start of each row in indices.
forceInteger boolean <optional>
 true

Whether to coerce values to integers via truncation.
layered boolean <optional>
 true

Whether to create a layered sparse matrix, see tatami_layered for more details. Only used if values contains an integer type and/or forceInteger = true. Setting to true assumes that values contains only non-negative integers.
Returns:

Matrix containing sparse data.

Type
ScranMatrix

initializeSparseMatrixFromDenseArray(numberOfRows, numberOfColumns, values, optionsopt) → {ScranMatrix}

Source:

Initialize a sparse matrix from a dense array.

Parameters:
Name Type Attributes Default Description
numberOfRows number

Number of rows in the matrix.
numberOfColumns number

Number of columns in the matrix.
values WasmArray | Array | TypedArray

Values of all elements in the matrix, stored in column-major order. This is generally expected to contain non-negative integers; otherwise, users should set forceInteger = false.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceInteger boolean <optional>
 true

Whether to coerce values to integers via truncation.
layered boolean <optional>
 true

Whether to create a layered sparse matrix, see tatami_layered for more details. Only used if values contains an integer type and/or forceInteger = true. Setting to true assumes that values contains only non-negative integers.
Returns:

Matrix containing sparse data.

Type
ScranMatrix

initializeSparseMatrixFromHdf5(file, name, optionsopt) → {ScranMatrix}

Source:

Initialize a (potentially layered) sparse matrix from a HDF5 file, either from a dense array (via initializeSparseMatrixFromHdf5DenseArray) or a group containing a compressed sparse matrix (via initializeSparseMatrixFromHdf5SparseMatrix).

Parameters:
Name Type Attributes Default Description
file string

Path to the HDF5 file. For browsers, the file should have been saved to the virtual filesystem.
name string

Name of the matrix inside the file. This can be a HDF5 Dataset for dense matrices or a HDF5 Group for sparse matrices. For the latter, both H5AD and 10X-style sparse formats are supported.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceInteger boolean <optional>
 true

Whether to coerce all elements to integers via truncation.
layered boolean <optional>
 true

Whether to create a layered sparse matrix, see tatami_layered for more details. Only used if the relevant HDF5 dataset contains an integer type and/or forceInteger = true. Setting to true assumes that the matrix contains only non-negative integers.
subsetRow Array | TypedArray | Int32WasmArray <optional>
<nullable>
 null

Row indices to extract. All indices must be non-negative integers less than the number of rows in the sparse matrix.
subsetColumn Array | TypedArray | Int32WasmArray <optional>
<nullable>
 null

Column indices to extract. All indices must be non-negative integers less than the number of columns in the sparse matrix.
Returns:

Matrix containing sparse data.

Type
ScranMatrix

initializeSparseMatrixFromHdf5DenseArray(file, name, optionsopt) → {ScranMatrix}

Source:

Initialize a (potentially layered) sparse matrix from a two-dimensional HDF5 dataset.

Parameters:
Name Type Attributes Default Description
file string

Path to the HDF5 file. For browsers, the file should have been saved to the virtual filesystem.
name string

Name of the dataset inside the file.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
transposed boolean <optional>
 false

Whether the matrix is transposed inside the file, i.e., the last dimension represents the rows.
forceInteger boolean <optional>
 false

Whether to coerce all elements to integers via truncation.
layered boolean <optional>
 true

Whether to create a layered sparse matrix, see tatami_layered for more details. Only used if the relevant HDF5 dataset contains an integer type and/or forceInteger = true. Setting to true assumes that the matrix contains only non-negative integers.
subsetRow Array | TypedArray | Int32WasmArray <optional>
<nullable>
 null

Row indices to extract. All indices must be non-negative integers less than the number of rows in the sparse matrix.
subsetColumn Array | TypedArray | Int32WasmArray <optional>
<nullable>
 null

Column indices to extract. All indices must be non-negative integers less than the number of columns in the sparse matrix.
Returns:

Matrix containing sparse data.

Type
ScranMatrix

initializeSparseMatrixFromHdf5SparseMatrix(file, name, numberOfRows, numberOfColumns, byColumn, optionsopt) → {ScranMatrix}

Source:

Initialize a (potentially layered) sparse matrix from a HDF5 group containing the usual data, indices, and indptr components of a compressed sparse matrix.

Parameters:
Name Type Attributes Default Description
file string

Path to the HDF5 file. For browsers, the file should have been saved to the virtual filesystem.
name string

Name of the dataset inside the file.
numberOfRows number

Number of rows in the matrix.
numberOfColumns number

Number of columns in the matrix.
byColumn boolean

Whether the matrix is in the compressed sparse column (CSC) format. If false, the format is assumed to be compressed sparse row (CSR) instead.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceInteger boolean <optional>
 false

Whether to coerce all elements to integers via truncation.
layered boolean <optional>
 true

Whether to create a layered sparse matrix, see tatami_layered for more details. Only used if the relevant HDF5 dataset contains an integer type and/or forceInteger = true. Setting to true assumes that the matrix contains only non-negative integers.
subsetRow Array | TypedArray | Int32WasmArray <optional>
<nullable>
 null

Row indices to extract. All indices must be non-negative integers less than the number of rows in the sparse matrix.
subsetColumn Array | TypedArray | Int32WasmArray <optional>
<nullable>
 null

Column indices to extract. All indices must be non-negative integers less than the number of columns in the sparse matrix.
Returns:

Matrix containing sparse data.

Type
ScranMatrix

initializeSparseMatrixFromMatrixMarket(buffer, optionsopt) → {ScranMatrix}

Source:

Initialize a sparse matrix from a buffer containing a MatrixMarket file.

Parameters:
Name Type Attributes Default Description
buffer Uint8WasmArray | Array | TypedArray | string

Byte array containing the contents of a Matrix Market file with non-negative counts. This can be raw text or Gzip-compressed.

Alternatively, this can be a string containing a file path to a MatrixMarket file. On browsers, this should be a path in the virtual filesystem, typically created with writeFile.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
compressed boolean <optional>
<nullable>
 null

Whether the buffer is Gzip-compressed. If null, we detect this automatically from the magic number in the header.
layered boolean <optional>
 true

Whether to create a layered sparse matrix, see tatami_layered for more details.
Returns:

Matrix containing sparse data.

Type
ScranMatrix

initializeSparseMatrixFromRds(x, optionsopt) → {ScranMatrix}

Source:

Initialize a sparse matrix from an RDS file.

Parameters:
Name Type Attributes Default Description
x RdsObject

Handle to an object inside an RDS file. This should be an integer/numeric matrix, dgCMatrix or dgTMatrix object.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceInteger boolean <optional>
 true

Whether to coerce all elements to integers via truncation.
layered boolean <optional>
 true

Whether to create a layered sparse matrix, see tatami_layered for more details. Only used if the R matrix is of an integer type and/or forceInteger = true. Setting to true assumes that the matrix contains only non-negative integers.
Returns:

Sparse matrix.

Type
ScranMatrix

initializeTsne(x, optionsopt) → {TsneStatus}

Source:
Parameters:
Name Type Attributes Default Description
x BuildNeighborSearchIndexResults | FindNearestNeighborsResults

Either a pre-built neighbor search index for the dataset (see buildNeighborSearchIndex), or a pre-computed set of neighbor search results for all cells (see findNearestNeighbors).
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
perplexity number <optional>
 30

Perplexity to use when computing neighbor probabilities in the t-SNE.
checkMismatch boolean <optional>
 true

Whether to check for a mismatch between the perplexity and the number of searched neighbors. Only relevant if x is a FindNearestNeighborsResults object.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the initial status of the t-SNE algorithm.

Type
TsneStatus

initializeUmap(x, optionsopt) → {UmapStatus}

Source:
Parameters:
Name Type Attributes Default Description
x BuildNeighborSearchIndexResults | FindNearestNeighborsResults

Either a pre-built neighbor search index for the dataset (see buildNeighborSearchIndex), or a pre-computed set of neighbor search results for all cells (see findNearestNeighbors).
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
neighbors number <optional>
 15

Number of neighbors to use in the UMAP algorithm. Ignored if x is a FindNearestNeighborsResults object.
epochs number <optional>
 500

Number of epochs to run the UMAP algorithm.
minDist number <optional>
 0.01

Minimum distance between points in the UMAP algorithm.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the initial status of the UMAP algorithm.

Type
UmapStatus

integrateCellLabels(x, integrated, assigned, optionsopt) → {LabelCellsResults}

Source:

Integrate cell labels across multiple reference datasets.

Parameters:
Name Type Attributes Default Description
x ScranMatrix | Float64WasmArray

The count matrix, or log-normalized matrix, containing features in the rows and cells in the columns. If a Float64WasmArray is supplied, it is assumed to contain a column-major dense matrix.
integrated IntegratedLabelledReferences

An integrated set of reference datasets, typically generated by integrateLabelledReferences.
assigned Array

An array of length equal to the number of references in integrated. This should contain the result of classification of x with each individual reference via labelCells. Each element should be a LabelCells object; or an Array, TypedArray or Int32WasmArray of length equal to the number of cells in x.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfFeatures number <optional>
<nullable>
 null

Number of features, used when x is a Float64WasmArray.
numberOfCells number <optional>
<nullable>
 null

Number of cells, used when x is a Float64WasmArray.
quantile number <optional>
 0.8

Quantile on the correlations to use to compute the score for each label.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Integrated labelling results for each cell in x.

Type
LabelCellsResults

integrateLabelledReferences(features, loaded, referenceFeatures, reference, optionsopt) → {IntegrateLabelledReferencesResults}

Source:

Integrate multiple reference datasets.

Parameters:
Name Type Attributes Default Description
features Array

An array of feature identifiers (usually strings) of length equal to the number of rows in the test matrix. Each entry should contain a single identifier for the corresponding row of the test matrix. Any null entries are considered to be incomparable. If any entries are duplicated, only the first occurrence is used and the rest are ignored.
loaded Array

Array of LabelledReference objects, typically created with loadLabelledReferenceFromBuffers.
referenceFeatures Array

Array of length equal to loaded, containing arrays of feature identifiers (usually strings) of length equal to the number of features the corresponding entry of loaded. Each entry may also be an array of synonymous identifiers, in which case the first identifier that matches to an entry of features is used. Contents of referenceFeatures are expected to exhibit some overlap with identifiers in features. Any null entries are considered to be incomparable. If multiple entries of referenceFeatures match to the same feature in features, only the first matching entry is used and the rest are ignored.
reference Array

Array of BuildLabelledReferenceResults objects, typically generated by calling buildLabelledReference on the same features and the corresponding entries of loaded and referenceFeatures. This should have length equal to that of loaded.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the integrated references.

Type
IntegrateLabelledReferencesResults

labelCells(x, reference, optionsopt) → {LabelCellsResults}

Source:

Label cells based on similarity in expression to a reference dataset.

Parameters:
Name Type Attributes Default Description
x ScranMatrix | Float64WasmArray

The count matrix, or log-normalized matrix, containing features in the rows and cells in the columns. If a Float64WasmArray is supplied, it is assumed to contain a column-major dense matrix.
reference BuildLabelledReferenceResults

A built reference dataset, typically generated by buildLabelledReference.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfFeatures number <optional>
<nullable>
 null

Number of features, used when x is a Float64WasmArray.
numberOfCells number <optional>
<nullable>
 null

Number of cells, used when x is a Float64WasmArray.
quantile number <optional>
 0.8

Quantile on the correlations to use to compute the score for each label.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Labelling results for each cell in x.

Type
LabelCellsResults

loadHdf5Dataset(path, name) → {object}

Source:

Load a dataset from a HDF5 file.

Parameters:
Name Type Description
path string

Path to a HDF5 file. For web applications, this should be saved to the virtual filesystem with writeFile.
name string

Name of a dataset inside the HDF5 file.
Returns:

An object containing:

  • dimensions, an array containing the dimensions of the dataset.
  • contents, a Int32Array, Float64Array or array of strings, depending on the type of the dataset.
Type
object

loadLabelledReferenceFromBuffers(ranks, markers, labels) → {LoadLabelledReferenceResults}

Source:

Load a reference dataset for annotation.

Parameters:
Name Type Description
ranks Uint8Array

Buffer containing the Gzipped CSV file containing a matrix of ranks. Each line corresponds to a sample and contains a comma-separated vector of ranks across all features. All lines should contain the same number of entries. This is effectively a row-major matrix where rows are samples and columns are features. (Advanced users may note that this is transposed in C++.)
markers Uint8Array

Buffer containing the Gzipped GMT file containing the markers for each pairwise comparison between labels. For markers, the GMT format is a tab-separated file with possibly variable numbers of fields for each line. Each line corresponds to a pairwise comparison between labels, defined by the first two fields. The remaining fields should contain indices of marker features (referring to columns of matrix) that are upregulated in the first label when compared to the second. Markers should be sorted in order of decreasing strength.
labels Uint8Array

Buffer containing the Gzipped text file containing the label for each sample. Each line should contain an integer representing a particular label, from [0, N) where N is the number of unique labels. The number of lines should be equal to the number of rows in matrix. The actual names of the labels are usually held elsewhere.
Returns:

Object containing the reference dataset.

Type
LoadLabelledReferenceResults

logNormCounts(x, optionsopt) → {ScranMatrix}

Source:

Compute log-transformed normalized expression values.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The count matrix, usually after filtering.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
sizeFactors Float64WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array of positive numbers containing the size factor for each cell in x. This should have length equal to the number of columns in x. If null, size factors are computed from the column sums of x.
center boolean <optional>
 true

Whether to center the size factors so that the normalized expression values are comparable in magnitude to the input counts. Set this to false if sizeFactors are provided and already centered, e.g., with centerSizeFactors.
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell. 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. This is used to adjust the scaling of cells in different blocks, to avoid excessive up-scaling of low-coverage blocks.

Alternatively, this may be null, in which case all cells are assumed to be in the same block.

This option is ignored if center = false, in which case it is assumed that scaling has already been provided in the input sizeFactors.
allowZeros boolean <optional>
 false

Whether size factors of zero should be allowed. If true, size factors of zero are converted to the smallest non-zero size factor across all cells. If false, an error is raised instead.
allowZeros boolean <optional>
 false

Whether non-finite size factors should be allowed. If true, size factors of infinity or NaN are converted to the largest non-zero size factor in the dataset or 1, respectively. If false, an error is raised instead.
Returns:

A matrix of the same type as x containing log-transformed normalized expression values.

Type
ScranMatrix

maximumThreads() → {number}

Source:

Maximum number of threads available for computation. This depends on the value specified during module initialization in initialize.

Returns:

Maximum number of available threads.

Type
number

medianSizeFactors(x, optionsopt) → {Float64WasmArray}

Source:

Compute median-based size factors to remove composition biases. This is similar to the DESeq2 normalization strategy, and the factors can be directly used in logNormCounts.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The count matrix, usually after filtering.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
center boolean <optional>
 true

Whether to return centered size factors. If false, the size factors can be interpreted as the scaling to match reference.
reference Array | TypedArray | Float64WasmArray <optional>
<nullable>
 null

Reference profile to normalize against. This should be an array of length equal to the number of rows in x. If null, this is automatically set to the row means of x.
buffer Float64WasmArray <optional>
<nullable>
 null

Output buffer for the size factors. This should have length equal to the number of columns in x.
priorCount number <optional>
 10

Prior count to use for shrinking size factors towards the relative library size. Larger values result in stronger shrinkage when the coverage is low.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Array of length equal to the number of columns in x, containing the size factors for all cells.

If buffer was supplied, it is used as the return value.

Type
Float64WasmArray

mnnCorrect(x, block, optionsopt) → {Float64WasmArray}

Source:

Perform mutual nearest neighbor (MNN) correction on a low-dimensional representation. This is primarily used to remove batch effects.

Parameters:
Name Type Attributes Default Description
x RunPcaResults | TypedArray | Array | Float64WasmArray

A matrix of low-dimensional results where rows are dimensions and columns are cells. If this is a RunPcaResults object, the PCs are automatically extracted. Otherwise, the matrix should be provided as an array in column-major form, with specification of numberOfDims and numberOfCells.
block Int32WasmArray | Array | TypedArray

Array containing the block assignment for each cell. 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. This is used to segregate cells in order to perform normalization within each block.
options object <optional>
 {}

Further optional parameters.

Properties
Name Type Attributes Default Description
buffer Float64WasmArray <optional>
<nullable>
 null

Buffer of length equal to the product of the number of cells and dimensions, to be used to store the corrected coordinates for each cell. If null, this is allocated and returned by the function.
numberOfDims number <optional>
<nullable>
 null

Number of dimensions in x. This should be specified if an array-like object is provided, otherwise it is ignored.
numberOfCells number <optional>
<nullable>
 null

Number of cells in x. This should be specified if an array-like object is provided, otherwise it is ignored.
k number <optional>
 15

Number of neighbors to use in the MNN search.
numberOfMADs number <optional>
 3

Number of MADs to use to define the threshold on the distances to the neighbors, see comments here.
robustIterations number <optional>
 2

Number of robustness iterations to use for computing the center of mass, see comments here.
robustTrim number <optional>
 0.25

Proportion of furthest observations to remove during robustness iterations, see comments here.
referencePolicy string <optional>
 "max-rss"

What policy to use to choose the first reference batch. This can be the largest batch ("max-size"), the most variable batch ("max-variance"), the batch with the highest RSS ("max-rss") or batch 0 in block ("input").
approximate boolean <optional>
 true

Whether to perform an approximate nearest neighbor search.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Array of length equal to x, containing the batch-corrected low-dimensional coordinates for all cells. Values are organized using the column-major layout. This is equal to buffer if provided.

Type
Float64WasmArray

modelGeneVariances(x, optionsopt) → {ModelGeneVariancesResults}

Source:

Model the mean-variance trend across genes.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The normalized log-expression matrix.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell. 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. This is used to segregate cells in order to fit the mean-variance trend within each block. Alternatively, this may be null, in which case all cells are assumed to be in the same block.
span number <optional>
 0.3

Span to use for the LOWESS trend fitting.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the variance modelling results.

Type
ModelGeneVariancesResults

perCellAdtQcMetrics(x, subsetsnullable, optionsopt) → {PerCellAdtQcMetricsResults}

Source:

Compute the per-cell QC metrics from an ADT count matrix.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The ADT count matrix.
subsets Array <nullable>

Array of arrays of boolean values specifying the feature subsets. Each internal array corresponds to a subset and should be of length equal to the number of rows. Each entry of each internal array specifies whether the corresponding row of x belongs to that subset; any value interpretable as a boolean can be used here.

Alternatively, each internal array may be any TypedArray or TypedWasmArray. Each array should be of length equal to the number of rows and values are interpreted as booleans.

Alternatively null, which is taken to mean that there are no subsets.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the ADT-based QC metrics.

Type
PerCellAdtQcMetricsResults

perCellCrisprQcMetrics(x, optionsopt) → {PerCellCrisprQcMetricsResults}

Source:

Compute per-cell QC metrics from the CRISPR guide count matrix.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The count matrix for CRISPR guides.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the QC metrics.

Type
PerCellCrisprQcMetricsResults

perCellRnaQcMetrics(x, subsetsnullable, optionsopt) → {PerCellRnaQcMetricsResults}

Source:

Compute per-cell QC metrics from the RNA count matrix.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The RNA count matrix for genes.
subsets Array <nullable>

Array of arrays of boolean values specifying the feature subsets. Each internal array corresponds to a subset and should be of length equal to the number of rows. Each entry of each internal array specifies whether the corresponding row of x belongs to that subset; any value interpretable as a boolean can be used here.

Alternatively, each internal array may be any TypedArray or TypedWasmArray. Each array should be of length equal to the number of rows and values are interpreted as booleans.

Alternatively null, which is taken to mean that there are no subsets.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the QC metrics.

Type
PerCellRnaQcMetricsResults

perplexityToNeighbors(perplexity) → {number}

Source:
Parameters:
Name Type Description
perplexity number

Perplexity to use in the t-SNE algorithm.
Returns:

Appropriate number of neighbors to use in the nearest neighbor search.

Type
number

possibleCopy(x, copy) → {TypedArray|WasmArray}

Source:

Possibly copy an array out of the Wasm heap, avoiding potential invalidation at the cost of some efficiency.

Parameters:
Name Type Description
x TypedArray

Array of data, possibly on the scran.js Wasm heap.
copy string | boolean

Copying mode to use.
Returns:

The return value depends on the value of copy:

  • If copy = true, a TypedArray copy of x is created with x.slice() and returned. This is a good default to avoid invalidation of TypedArray views on the heap upon reallocation, by creating a Javascript-owned copy for downstream use.
  • If copy = false, x is returned directly. This avoids making any copy but runs the risk of invalidation when the Wasm heap is resized; it should only be used when no further Wasm allocations are performed within the lifetime of x.
  • If copy = "view", a WasmArray view is created from x and returned. This avoids any copy and is robust to invalidation but requires an extra WasmArray.array() call to create a TypedArray.
Type
TypedArray | WasmArray

quickAdtSizeFactors(x, optionsopt) → {Float64WasmArray}

Source:

Quickly compute size factors for an ADT count matrix. This generates k-means clusters from a matrix of PCs before calling groupedSizeFactors. The aim is to account for composition biases that are common in ADT-based data, while avoiding problems with per-cell sparsity.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

An ADT count matrix.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfClusters number <optional>
 20

Number of clusters to create. More clusters improves the accuracy of the size factors at the cost of precision.
numberOfPCs number <optional>
 25

Number of PCs to use. More PCs captures more biological signal at the cost of increasing noise.
totals Float64WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the total count for each column in x, to speed up the initial normalization. If null, this is computed from x.
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Blocking level for each column in x, see logNormCounts and runPca. For PCA, this is used to equalize the contribution of blocks of differing size.
buffer Float64WasmArray <optional>
<nullable>
 null

Buffer in which to store the output size factors. Length should be equal to the number of columns in x. If null, an array is allocated by the function.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Per-cell size factors for each column of x.

If buffer is supplied, it is directly used as the return value.

Type
Float64WasmArray

rbind(inputs) → {ScranMatrix}

Source:

Combine matrices by row, where all matrices contain data for the same cells, in the same order.

Parameters:
Name Type Description
inputs Array

Array of one or more ScranMatrix objects. All of these should have the same number and order of cells.
Returns:

A ScranMatrix containing the matrices after combining them by row.

Type
ScranMatrix

readFile(path) → {Uint8Array}

Source:

Read a byte array from a path on the native file system (Node.js) or the virtual file system (browser).

Parameters:
Name Type Description
path string

Path to a file on the relevant file system.
Returns:

Binary contents of the file.

Type
Uint8Array

readRds(buffer) → {RdsDetails}

Source:

Read the contents of an RDS file.

Parameters:
Name Type Description
buffer Uint8WasmArray | Array | TypedArray | string

Byte array containing the contents of an RDS file. This can be raw text or Gzip-compressed.

Alternatively, this can be a string containing a file path to a MatrixMarket file.
Returns:

Details of the file.

Type
RdsDetails

realizeFile(file, optionsopt) → {Object}

Source:

Realize a file so that it can be read by scran.js functions across both Node.js and browsers.

Parameters:
Name Type Attributes Default Description
file string | Uint8Array

In general, a Uint8Array buffer containing the file contents. For Node.js, this may also be a string containing a path to a file.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
extension string <optional>
 ""

File extension to use for any temporary file that might be created.
Returns:

Object with the following properties:

  • path: a string containing the path to the file on the local filesystem (Node.js) or virtual file system (browsers). For Node.js, file is returned directly if it is already a path; otherwise, a new file will be created in the system's default temporary directory.
  • flush: a function to be called to remove any temporary file created by this function. For Node.js, this will be a no-op if file is already a path.
Type
Object

remapFeatureSets(targetFeatures, referenceFeatures, referenceFeatureSets) → {object}

Source:

Remap feature sets from a "reference" feature namespace to a "target" namespace. This involves defining a common namespace consisting of feature names that are shared in both namespaces, and then mapping the feature sets to the common namespace.

The target_indices property returned by this function can be used to generate the indices of markers in testFeatureSetEnrichment. Given a function that determines whether a feature in the target namespace is a marker, we can populate markers as below:

let markers = [];
target_indices.forEach((x, i) => {
    if (is_marker(x)) { // in other words, 'targetFeatures[x]' is a marker.
        markers.push(i); // we want to store 'i' as this is the index into the common namespace.
    }
});
Parameters:
Name Type Description
targetFeatures Array

Array of strings containing the feature names in the target namespace. Any null entries are considered to be incomparable.
referenceFeatures Array

Array of strings containing the feature names in the reference namespace. Any null entries are considered to be incomparable.
referenceFeatureSets Array

Array of feature sets. Each entry corresponds to a set and is an Array/TypedArray containing integer indices of features belonging to that set. Indices are relative to referenceFeatures.
Returns:

Object containing:

  • target_indices: an Int32Array of length equal to the number of common features between targetFeatures and referenceFeatures. Each entry is an index into targetFeatures to identify the feature in the common namespace, i.e., the common namespace can be defined as Array.from(target_indices).map(i => targetFeatures[i]).
  • reference_indices: an Int32Array of length equal to the size of the common namespace. Each entry is an index into referenceFeatures to identify the feature in the common namespace. i.e., the common namespace can be defined as Array.from(reference_indices).map(i => referenceFeatures[i]) (which is guaranteed to be the same as the corresponding operation on target_indices).
  • sets: an Array of Int32Arrays containing the membership of each feature set. Each integer is an index into the common namespace defined by target_indices and reference_indices.
Type
object

removeFile(path)

Source:

Remove a file from the native file system (Node.js) or the virtual file system (browser).

Parameters:
Name Type Description
path string

Path to the file on the relevant file system.
Returns:

Deletes the specified file from the relevant file system. If path does not exist, this function is a no-op.

resetLevels(x, newLevels, optionsopt)

Source:

Change the levels of a factor, updating the indices appropriately.

Parameters:
Name Type Attributes Default Description
x object

Factor object produced by convertToFactor.
newLevels Array

Array of new levels. This should be a superset of x.levels.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
action string <optional>
 "error"

Action to take when newLevels is not a superset of x.levels. This can be "error", "warn" or "none".
placeholder number <optional>
 -1

Placeholder index corresponding to invalid values of x.ids. Any placeholders in x.ids will be preserved on function return. Additionally, if entries of x.ids refer to entries of x.levels that are missing in newLevels, they will be set to the placeholder value on function return; this is only relevant if action = "warn" or "none".
Returns:

x is modified by reference such that x.levels is set to newLevels. x.ids is updated so that the indices now refer to the appropriate value in newLevels.

runPca(x, optionsopt) → {RunPcaResults}

Source:

Run a principal components analysis on the log-expression matrix. This is usually done on a subset of features, and possibly with some kind of blocking on a per-cell batch factor.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The log-normalized expression matrix.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
features Uint8WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array specifying which features should be retained (e.g., HVGs). This should be of length equal to the number of rows in x; elements should be true to retain each row. If null, all features are retained.
numberOfPCs number <optional>
 25

Number of top principal components to compute.
scale boolean <optional>
 false

Whether to scale each feature to unit variance.
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell. 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. This is used to segregate cells in order to compute filters within each block. Alternatively, this may be null, in which case all cells are assumed to be in the same block.
blockMethod string <optional>
 "regress"

How to adjust the PCA for the blocking factor.

  • "regress" will regress out the factor, effectively performing a PCA on the residuals. This only makes sense in limited cases, e.g., inter-block differences are linear and the composition of each block is the same.
  • "project" will compute the rotation vectors from the residuals but will project the cells onto the PC space. This focuses the PCA on within-block variance while avoiding any assumptions about the nature of the inter-block differences.
  • "none" will ignore any blocking factor, i.e., as if block = null. Any inter-block differences will both contribute to the determination of the rotation vectors and also be preserved in the PC space.

This option is only used if block is not null.
blockWeights bool <optional>
 true

Whether to weight each block so that it contributes the same number of effective observations to the covariance matrix. This ensures that, past a certain size (default 1000 cells), larger blocks do not dominate the definition of the PC space. Only used if block is not null.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing the computed PCs.

Type
RunPcaResults

runTsne(x, optionsopt) → {object}

Source:

Run the t-SNE algorithm to the specified number of iterations. This is a wrapper around initializeTsne and run.

Parameters:
Name Type Attributes Default Description
x BuildNeighborSearchIndexResults | FindNearestNeighborsResults

Either a pre-built neighbor search index for the dataset (see buildNeighborSearchIndex), or a pre-computed set of neighbor search results for all cells (see findNearestNeighbors).
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
perplexity number <optional>
 30

Perplexity to use when computing neighbor probabilities in the t-SNE.
checkMismatch boolean <optional>
 true

Whether to check for a mismatch between the perplexity and the number of searched neighbors. Only relevant if x is a FindNearestNeighborsResults object.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
maxIterations number <optional>
 1000

Maximum number of iterations to perform.
Returns:

Object containing coordinates of the t-SNE embedding, see TsneStatus.extractCoordinates for more details.

Type
object

runUmap(x, optionsopt) → {object}

Source:

Run the UMAP algorithm. This is a wrapper around initializeUmap and run.

Parameters:
Name Type Attributes Default Description
x BuildNeighborSearchIndexResults | FindNearestNeighborsResults

Either a pre-built neighbor search index for the dataset (see buildNeighborSearchIndex), or a pre-computed set of neighbor search results for all cells (see findNearestNeighbors).
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
neighbors number <optional>
 15

Number of neighbors to use in the UMAP algorithm. Ignored if x is a FindNearestNeighborsResults object.
epochs number <optional>
 500

Number of epochs to run the UMAP algorithm.
minDist number <optional>
 0.01

Minimum distance between points in the UMAP algorithm.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing coordinates of the UMAP embedding, see UmapStatus.extractCoordinates for more details.

Type
object

scaleByNeighbors(embeddings, numberOfCells, optionsopt) → {Float64WasmArray}

Source:

Scale embeddings based on the variation between neighboring cells. This aims to equalize the noise across embeddings for the same population of cells across different data modalities, allowing them to be combined into a single embedding for coordinated downstream analyses.

Parameters:
Name Type Attributes Default Description
embeddings Array

Array of Float64WasmArrays containing column-major matrices where rows are dimensions and columns are cells. All entries of this array should contain data for the same number and ordering of cells.
numberOfCells number

Number of cells in all embeddings.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
neighbors number <optional>
 20

Number of neighbors to use for quantifying variation. Larger values provide a more stable calculation but assume larger subpopulations.
indices Array <optional>
<nullable>
 null

Array of BuildNeighborSearchIndexResults objects, where each entry is constructed from the corresponding entry of embeddings (see buildNeighborSearchIndex). This can be used to avoid redundant calculation of indices if they are already available.
buffer Float64WasmArray <optional>
<nullable>
 null

Array in which to store the combined embedding. This should have length equal to the product of numberOfCells and the sum of dimensions of all embeddings.
approximate boolean <optional>
 true

Should we construct an approximate search index if indices is not supplied?
weights Array | TypedArray | Float64WasmArray <optional>
<nullable>
 null

Array of length equal to the number of embeddings, containing a non-enegative relative weight for each embedding. This is used to scale each embedding if non-equal noise is desired in the combined embedding. If null, all embeddings receive the same weight.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Array containing the combined embeddings in column-major format, i.e., dimensions in rows and cells in columns.

If buffer was supplied, it is used as the return value.

Type
Float64WasmArray

scoreFeatureSet(x, features, optionsopt) → {object}

Source:

Compute per-cell scores for the activity of a feature set.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

Log-normalized expression matrix.
features Uint8Array | Uint8WasmArray | TypedArray | Array

An array of length equal to the number of rows in x, indicating which features belong to the set. A non-zero value for any entry indicates that the corresponding row of x is part of the feature set.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell. 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. Alternatively, this may be null, in which case all cells are assumed to be in the same block.
scale boolean <optional>
 false

Whether to scale the expression matrix to unit variance for each feature before computing the per-feature weights. Setting to true improves robustness (or reduces sensitivity) to the behavior of highly variable features in the set.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
Returns:

Object containing:

  • weights, a Float64Array containing per-gene weights for each feature in the set.
  • scores, a Float64Array containing the per-cell scores for each column of x.
Type
object

scoreMarkers(x, groups, optionsopt) → {ScoreMarkersResults}

Source:

Score genes as potential markers for each group of cells.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

Log-normalized expression matrix.
groups Int32WasmArray | Array | TypedArray

Array containing the group assignment for each cell. 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.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell. 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. This is used to segregate cells in order to perform comparisons within each block. Alternatively, this may be null, in which case all cells are assumed to be in the same block.
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use. If null, defaults to maximumThreads.
lfcThreshold number <optional>
 0

Log-fold change threshold to use for computing Cohen's d and AUC. Large positive values favor markers with large log-fold changes over those with low variance.
computeAuc boolean <optional>
 true

Whether to compute the AUCs as an effect size. This can be set to false for greater speed and memory efficiency.
computeMedian boolean <optional>
 false

Whether to compute the median effect sizes across all pairwise comparisons for each group. This can be used as a more robust/less sensitive alternative to the mean.
computeMaximum boolean <optional>
 false

Whether to compute the maximum effect size across all pairwise comparisons for each group. This could be used to find uniquely downregulated genes.
Returns:

Object containing the marker scoring results.

Type
ScoreMarkersResults

splitRows(matrix, split, optionsopt) → {object|MultiMatrix}

Source:

Split a ScranMatrix by row.

Parameters:
Name Type Attributes Default Description
matrix ScranMatrix

A ScranMatrix object.
split object

Object specifying how rows should be split. Each value should be an Array/TypedArray of 0-based row indices.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
singleNull boolean <optional>
 false

Whether null should be returned if split only contains one level and all rows are represented exactly once. This can be used to avoid the creation of a redundant ScranMatrix object.
createMultiMatrix boolean <optional>
 false

Whether the output should be returned as a MultiMatrix.
Returns:

Object with the same keys as split where each value is a ScranMatrix for the corresponding subset of rows. Alternatively, this is wrapped in a MultiMatrix if createMultiMatrix = true.

Type
object | MultiMatrix

subsetColumns(x, indices, optionsopt) → {ScranMatrix}

Source:

Slice a ScranMatrix by its columns.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The matrix of interest.
indices Array

Column indices to extract. Al indices must be a non-negative integer less than mat.numberOfColumns().
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
inPlace boolean <optional>
 false

Whether to modify x in place. If false, a new ScranMatrix is returned.
Returns:

A new ScranMatrix containing the subset of columns from mat specified by indices. If inPlace = true, this is a reference to x, otherwise it is a new ScranMatrix.

Type
ScranMatrix

subsetFactor(x, subset, optionsopt) → {object}

Source:

Subset a factor, possibly also dropping its unused levels. This is typically based on the same filtering vector as filterCells.

Parameters:
Name Type Attributes Default Description
x object

An object representing a factor, containing the following properties:

  • ids: An Int32Array or Int32WasmArray of integer indices.
  • levels: An array of levels that can be indexed by entries of ids.

This is typically produced by convertToFactor.
subset Array | TypedArray | WasmArray

Array specifying the subset to retain or filter out, depending on filter.

If filter = null, the array is expected to contain integer indices specifying the entries in x to retain. The ordering of indices in subset will be respected in the subsetted array.

If filter = true, the array should be of length equal to that of x. Each value is interpreted as a boolean and, if truthy, indicates that the corresponding entry of x should be filtered out.

If filter = false, the array should be of length equal to that of x. Each value is interpreted as a boolean and, if truthy, indicates that the corresponding entry of x should be retained.

Note that TypedArray views on Wasm-allocated buffers should only be provided if buffer is also provided; otherwise, a Wasm memory allocation may invalidate the view.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
drop boolean <optional>
 true

Whether to drop unused levels in the output, see dropUnusedLevels.
filter boolean <optional>
<nullable>
 null

Whether to retain truthy or falsey values in a subset boolean filter. If null, subset should instead contain the indices of elements to retain.
buffer Int32Array | Int32WasmArray <optional>
<nullable>
 null

Array in which the output is to be stored, of the same type as x.ids. If provided, this should be of length equal to subset, if filter = null; the number of truthy elements in subset, if filter = false; or the number of falsey elements in subset, if filter = true.
Returns:

An object like x, containing:

  • ids: An Int32Array or Int32WasmArray of integer indices, subsetted from those in x.ids.
  • levels: Array of levels that can be indexed by entries of the output ids. If drop = true, this may be a subset of x.levels where every entry is represented at least once in the output ids.

If buffer is supplied, the returned ids will be set to buffer.

Type
object

subsetRows(x, indices, optionsopt) → {ScranMatrix}

Source:

Slice a ScranMatrix by its rows.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

The matrix of interest.
indices Array

Row indices to extract. All indices must be non-negative integers less than mat.numberOfRows().
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
inPlace boolean <optional>
 false

Whether to modify x in place. If false, a new ScranMatrix is returned.
Returns:

A ScranMatrix containing the subset of rows from mat specified by indices. If inPlace = true, this is a reference to x, otherwise it is a new ScranMatrix.

Type
ScranMatrix

suggestAdtQcFilters(metrics, optionsopt) → {SuggestAdtQcFiltersResults}

Source:

Define filters based on the per-cell QC metrics from the ADT count matrix.

Parameters:
Name Type Attributes Default Description
metrics PerCellAdtQcMetricsResults

Per-cell QC metrics, usually computed by perCellAdtQcMetrics.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfMADs number <optional>
 3

Number of median absolute deviations to use to define low-quality outliers.
minDetectedDrop number <optional>
 0.1

Minimum relative drop in the number of detected ADTs before a cell is to be considered a low-quality cell. By default, cells must exhibit at least a 10% decrease from the median before filtering is applied.
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell. 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. This is used to segregate cells in order to compute filters within each block. Alternatively, this may be null, in which case all cells are assumed to be in the same block.
Returns:

Object containing the filtering results.

Type
SuggestAdtQcFiltersResults

suggestCrisprQcFilters(metrics, optionsopt) → {SuggestCrisprQcFiltersResults}

Source:

Define filters based on the per-cell QC metrics for CRISPR guide counts.

Parameters:
Name Type Attributes Default Description
metrics PerCellCrisprQcMetricsResults

Per-cell QC metrics, usually computed by perCellCrisprQcMetrics.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfMADs number <optional>
 3

Number of median absolute deviations to use to define low-quality outliers.
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell. 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. This is used to segregate cells in order to compute filters within each block. Alternatively, this may be null, in which case all cells are assumed to be in the same block.
Returns:

Object containing the filtering results.

Type
SuggestCrisprQcFiltersResults

suggestRnaQcFilters(metrics, optionsopt) → {SuggestRnaQcFiltersResults}

Source:

Define filters based on the per-cell QC metrics computed from an RNA count matrix.

Parameters:
Name Type Attributes Default Description
metrics PerCellRnaQcMetricsResults

Per-cell QC metrics, usually computed by perCellRnaQcMetrics.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfMADs number <optional>
 3

Number of median absolute deviations to use to define low-quality outliers.
block Int32WasmArray | Array | TypedArray <optional>
<nullable>
 null

Array containing the block assignment for each cell. 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. This is used to segregate cells in order to compute filters within each block. Alternatively, this may be null, in which case all cells are assumed to be in the same block.
Returns:

Object containing the filtering results.

Type
SuggestRnaQcFiltersResults

terminate()

Source:
Returns:

All worker threads are terminated and the module is deleted from the cache. This is useful for releasing thread resources at the end of the analysis when scran.js functions are no longer required. Of course, workers will automatically shut down on program exit anyway, so calling this function is not essential.

testFeatureSetEnrichment(markers, featureSets, totalFeatures, optionsopt) → {object}

Source:

Test for feature set enrichment among markers using the hypergeometricTest function. We assume that all feature names have already been converted into integer indices before running this function; i.e., features are represented as indices into a "common namespace" consisting of an array of unique feature names. See remapFeatureSets for more details.

Parameters:
Name Type Attributes Default Description
markers Array | TypedArray

Array of marker identities. Each entry of the array is a unique integer index identifying a marker feature in the common namespace, where each index lies in [0, totalFeatures).

In other words, given a common namespace array X containing the feature names, the marker names can be obtained as Array.from(markers).map(i => X[i]).
featureSets Array

Array containing the feature sets. Each entry corresponds to a single feature set and may be an Array or TypedArray. Each array should contain unique indices for the features belonging to the set.

In other words, given a common namespace array X containing the feature names, the names of the features in set s can be obtained as Array.from(featureSets[s]).map(i => X[i]).
totalFeatures number

Total number of features in the common namespace.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
numberOfThreads number <optional>
<nullable>
 null

Number of threads to use for computing the p-values, see hypergeometricTest.
Returns:

Object containing:

  • count: Int32Array containing the number of markers present in each set.
  • size: Int32Array containing the size of each set.
  • pvalue: Float64Array containing the p-value for enrichment in each set.
Type
object

transpose(x, optionsopt) → {ScranMatrix}

Source:

Transpose a ScranMatrix object.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

A ScranMatrix object.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
inPlace boolean <optional>
 false

Whether to modify x in place. If false, a new ScranMatrix is returned.
Returns:

A ScranMatrix containing the transposition of x. If inPlace = true, this is a reference to x, otherwise it is a new ScranMatrix.

Type
ScranMatrix

wasmArraySpace() → {number}

Source:
Returns:

Integer containing the wasmarrays.js identifier for scran.js's memory space. This can be used with createWasmArray() and related functions from wasmarrays.js.

Type
number

writeFile(path, buffer)

Source:

Write a byte array to a path on the native file system (Node.js) or to the virtual file system (browser).

Parameters:
Name Type Description
path string

Path to the output file on the relevant file system.
buffer Uint8Array

Buffer to write to file.
Returns:

buffer is written to the binary file path.

writeSparseMatrixToHdf5(x, path, name, optionsopt)

Source:

Write a sparse ScranMatrix into HDF5 file, in the form of its compressed sparse components. This can be considered the reverse operation of initializeSparseMatrixFromHDF5.

Parameters:
Name Type Attributes Default Description
x ScranMatrix

An input sparse matrix.
path string

Path to the HDF5 file. A new file will be created if no file is present.
name string

Name of the group inside the HDF5 file in which to save x.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
format string <optional>
 "tenx_matrix"

Format to use for saving x. This can be one of:

  • tenx_matrix, a compressed sparse column layout where the dimensions are stored in the shape dataset.
  • csr_matrix, a compressed sparse column (yes, column) layout where the dimensions are stored in the shape attribute of the HDF5 group. The discrepancy between the name and the layout is a consequence of the original framework operating on the transposed matrix (i.e., features in columns).
  • csc_matrix, a compressed sparse row layout where the dimensions are stored in the shape attribute of the group. Discrepancy is for the same reason as described for csr_matrix.
forceInteger boolean <optional>
 false

Whether to force non-integer values in x to be coerced to integers.
Returns:

x is written to path at name.