InputsState

InputsState

This step handles the loading of all datasets into memory. This wraps various matrix initialization functions in scran.js, depending on the format of the supplied datasets.

Methods not documented here are not part of the stable API and should not be used by applications.

Classes

InputsState

Methods

(async) compute(datasets, parameters)

Description:

  • This method should not be called directly by users, but is instead invoked by runAnalysis.

Source:
Parameters:
Name Type Description
datasets object

An object containing data for one or more datasets. Each property corresponds to a single dataset and its value should satisfy the Dataset contract. See the description of the argument of the same name in runAnalysis.
parameters object

Parameter object, equivalent to the inputs property of the parameters in runAnalysis.

Properties
Name Type Attributes Description
block_factor string <nullable>

Name of the column of the cell annotations specifying the sample of origin for each cell. This is only used if a single count matrix is supplied.

If null, all cells are assumed to originate from the same sample.

If any entries of the blocking factor are invalid (i.e., null), they are removed from downstream analyses.
subset subset <nullable>

Object describing if any pre-analysis subsetting should be applied. This should contain field, a string specifying a field of the column annotation.

  • For categorical variables, the object should also contain values, an array of allowed values for that annotation. Cells are only retained if they are associated with any of the allowable values for that annotation field.
  • For continuous variables, the object should also contain ranges, an array of arrays. Each inner array should contain two numbers defining the start and end of a range. Ranges should be sorted and non-overlapping (boundaries excepted).

If subset is null, no subsetting is performed and all cells are used in the downstream analysis.
Returns:

The object is updated with the new results. A promise is returned that resolves to null once input loading is complete - this should be resolved before any downstream steps are run.

enableDatasetCache(cache)

Description:

  • Allow each Dataset reader (i.e., the datasets in compute) to cache any intermediate results during loading. By default, this is disabled as caching increases memory usage of the analysis without any major runtime improvements to compute when the datasets do not change.

    Setting cache = true is only useful if the instances in datasets are to be re-used outside of bakana, or if they are to be re-used in compute() in different combinations. In such cases, there may be a runtime improvement that warrants the increase in memory usage. If caching is used, the user is responsible for releasing cached resources via each instance's clear() method once they are no longer needed.

Source:
Parameters:
Name Type Description
cache boolean

Whether to allow Dataset instances to cache their results.

fetchBlock() → (nullable) {Int32Array}

Source:
Returns:

Array of length equal to the number of cells in the dataset, identifying the block to which each cell is assigned. Alternatively null, if no blocking is performed.

Type
Int32Array

fetchBlockLevels() → (nullable) {Array}

Source:
Returns:

Array of names of the blocks, or null if no blocking is performed.

Type
Array

fetchCellAnnotations() → {external:DataFrame}

Source:
Returns:

DataFrame containing per-cell annotations. Each row of the DataFrame corresponds to a cell in fetchCountMatrix, and each column represents a per-cell annotation field.

Note that this considers all cells in the dataset before QC filtering - see QualityControlState.applyFilter to obtain a filtered version of each column.

Type
external:DataFrame

fetchCountMatrix() → {external:MultiMatrix}

Source:
Returns:

A MultiMatrix object containing counts for one or more modalities. Each modality is represented by a separate count matrix, where each row of the matrix represents a feature of that modality. All matrices have the same number and ordering of cells in their columns.

Type
external:MultiMatrix

fetchDirectSubset(optionsopt) → (nullable) {Int32Array}

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

Optional parameters.

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

Whether to return a copy of the subsets to avoid pass-by-reference behaviors.
Returns:

Array containing the indices to use for direct subsetting - see setDirectSubset for more information. Alternatively null, if direct subsetting is not performed.

Type
Int32Array

fetchFeatureAnnotations() → {object}

Source:
Returns:

Object where each key is the name of a modality and each value is a DataFrame. Each row of the DataFrame corresponds to a feature in that modality (i.e., a row in the corresponding matrix from fetchCountMatrix) and each column represents a per-feature annotation field.

Type
object

fetchParameters() → {object}

Source:
Returns:

Object containing the parameters.

Type
object

setDirectSubset(indices, optionsopt)

Description:

  • Unlike most of the other methods, setDirectSubset can be called on an InputsState before compute. This means that a user can create the state object from createAnalysis, specify a subset of cells via setDirectSubset on the (currently empty) InputsState object in inputs, and then call runAnalysis to execute an analysis on the desired subset of cells.

Source:
Parameters:
Name Type Attributes Description
indices TypedArray | Array

Array containing the indices for the desired subset of cells. This should be sorted and non-duplicate. Any existing subset in this object will be overridden by indices.
options object <optional>

Optional parameters.

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

Whether to make a copy of indices before storing it inside the returned state object. If false, it is assumed that the caller makes no further use of the passed indices.
onOriginal boolean <optional>
 false

Whether indices contains indices on the original dataset or on the dataset in state. This distinction is only relevant if the current InputsState object already contains a specified subset. If false, the indices are assumed to refer to the already-subsetted dataset that exists in state; if true, the indices are assumed to refer to the original dataset from which the subset in state was created.
Returns:

The dataset in this InputsState object is subsetted to the desired indices.

undoSubset(indices)

Description:

  • Undo the effect of subsetting on an array of indices. This works with all subset specifications, e.g., via parameters.subset in compute, with setDirectSubset, or even from the implicit subsetting when the factor specified in parameters.block contains null entries.

Source:
Parameters:
Name Type Description
indices Array | TypedArray

Array of column indices to the subsetted matrix. Note that this will be modified in-place.
Returns:

Entries of indices are replaced with indices to the pre-subsetted matrix.