Global

Members

(constant) availableReaders

Description:

  • All known dataset readers. Each entry contains a Dataset class with the key defined as the format return value.

Source:

All known dataset readers. Each entry contains a Dataset class with the key defined as the format return value.

Methods

analysisDefaults()

Description:

  • Generate an object containing all of the default analysis parameters.

Source:
Returns:

An object where each property corresponds to an analysis step and contains the default parameters for that step. See the documentation for each step's compute method for more details:

See also configureBatchCorrection and configureApproximateNeighbors to synchronize certain parameter settings across multiple steps.

callScran(fun)

Description:

  • Call a scran.js function. This allows client applications to operate in the same scran.js memory space as bakana functions, which is not guaranteed if applications import scran.js on their own (e.g., due to name mangling with Webpack).

Source:
Parameters:
Name Type Description
fun function

A function that accepts the scran.js module object and presumably calls some of its functions.
Returns:

The return value of fun.

configureApproximateNeighbors(parameters, approximate)

Description:

  • Specify whether approximate neighbor searches should be performed across all affected steps. This is a convenient helper as it is generally unnecessary to switch between exact and approximate searches in different steps. Affected steps are BatchCorrectionState, CombineEmbeddingsState and NeighborIndexState.

Source:
Parameters:
Name Type Description
parameters object

Object containing parameters for all steps, e.g., from analysisDefaults.
approximate boolean

Whether to perform approximate nearest neighbor searces.
Returns:

parameters is modified with appropriate parameters in relevant steps, e.g., batch_correction, combine_embeddings and neighbor_index.

configureBatchCorrection(parameters, method)

Description:

  • Set the batch correction parameters across multiple steps. This is a convenient helper as the correction process is split across the PCA and batch correction steps. For MNN, we project cells onto rotation vectors computed within each batch in the various PCA steps (e.g., PcaState) before performing MNN correction in BatchCorrectionState; for linear regression, we need to regress by block in the PCA without any additional correction in BatchCorrectionState; and for no correction, we need to turn off any block handling in the PCA as well as removing any additional correction in BatchCorrectionState.

Source:
Parameters:
Name Type Description
parameters object

Object containing parameters for all steps, e.g., from analysisDefaults.
method string

Correction method to perform, one of "mnn", "regress" or "none".
Returns:

parameters is modified with appropriate parameters in batch_correction, pca and adt_pca.

createAnalysis()

Description:

  • Create a new analysis state in preparation for calling runAnalysis. Multiple states can be created and used interchangeably within the same Javascript runtime.

Source:
Returns:

A promise that resolves to an object containing states for all analysis steps. This object can be used as input into runAnalysis.

freeAnalysis(state)

Description:

  • Free the contents of an analysis state. This releases memory on the scran.js Wasm heap and terminates any workers associated with this analysis.

Source:
Parameters:
Name Type Description
state

An existing analysis state, produced by createAnalysis or loadAnalysis.
Returns:

A promise that resolves to null when all states are freed.

guessApproximateNeighborsConfig(parameters, optionsopt) → (nullable) {boolean}

Description:

  • Guess the value of approximate from configureApproximateNeighbors based on the parameter object. This effectively consolidates the various approximation parameters into a single setting.

Source:
Parameters:
Name Type Attributes Description
parameters object

Object containing parameters for all steps, typically after configureApproximateNeighbors.
options object <optional>

Optional parameters.

Properties
Name Type Attributes Description
strict boolean <optional>

Whether to only report approximate when the set of parameters modified by configureApproximateNeighbors are consistent.
Returns:

Whether or not approximate neighbor search was used. If strict = false and there is a mixture of approximate and exact matches, an approximate search is reported; otherwise, if strict = true, null is returned.

Type
boolean

guessBatchCorrectionConfig(parameters, optionsopt) → (nullable) {string}

Description:

  • Guess the method value from configureBatchCorrection based on the parameter object. This effectively consolidates the various correction parameters into a single setting.

Source:
Parameters:
Name Type Attributes Description
parameters object

Object containing parameters for all steps, typically after configureBatchCorrection.
options object <optional>

Optional parameters.

Properties
Name Type Attributes Description
strict boolean <optional>

Whether to only report the method when the set of parameters modified by configureBatchCorrection are consistent.
Returns:

One of "mnn", "regress" or "none", based on the expected set of modifications from configureBatchCorrection. If strict = false and there is no exact match to the expected set, the most appropriate method is returned; otherwise, if strict = true, null is returned.

Type
string

initialize(optionsopt)

Description:

  • Initialize the backend for computation. This is required prior to running any other bakana function.

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

Optional parameters.

Properties
Name Type Attributes Description
numberOfThreads number <optional>

Number of threads used by scran.js.
localFile boolean <optional>

Whether to use local file paths for imported modules in scran.js. This only needs to be true for old Node versions that do not support file URIs.
Returns:

A promise that resolves to null when initialization is complete.

promoteToNumber(x) → (nullable) {Float64Array}

Description:

  • Detect if an array contains only stringified numbers and, if so, convert it into a TypedArray. Conversion will still be performed for non-number strings corresponding to missing values or explicit not-a-number entries.

Source:
Parameters:
Name Type Description
x Array

Array of strings, usually corresponding to a column in a table read by readDSVFromBuffer.
Returns:

A Float64Array is returned if x contains stringified numbers. Otherwise, null is returned if the conversion could not be performed.

Type
Float64Array

(async) readLines2(x, optionsopt) → {Array}

Description:

  • Read lines of text from a file, possibly with decompression.

Source:
Parameters:
Name Type Attributes Default Description
x string | Uint8Array | SimpleFile | File

Contents of the file to be read. On Node.js, this may be a string containing a path to a file; on browsers, this may be a File object.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
compression string <optional>
<nullable>
 null

Compression of buffer, either "gz" or "none". If null, it is determined automatically from the buffer header.
chunkSize number <optional>
 65536

Chunk size in bytes to use for file reading (if x is a file path) and decompression (if compression="gz"). Larger values improve speed at the cost of memory.
Returns:

Array of strings where each entry contains a line in buffer. The newline itself is not included in each string.

Type
Array

(async) readTable2(x, optionsopt) → {Array}

Description:

  • Read a delimiter-separated table from a buffer, possibly with decompression. This assumes that newlines represent the end of each row of the table, i.e., there cannot be newlines inside quoted strings.

Source:
Parameters:
Name Type Attributes Default Description
x string | Uint8Array | SimpleFile | File

Contents of the file to be read. On Node.js, this may be a string containing a path to a file; on browsers, this may be a File object.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
compression string <optional>
<nullable>
 null

Compression of buffer, either "gz" or "none". If null, it is determined automatically from the buffer header.
delim string <optional>
 "\t"

Delimiter between fields.
chunkSize number <optional>
 1048576

Chunk size in bytes to use for file reading (if x is a path), parsing of rows, and decompression (if compression="gz"). Larger values improve speed at the cost of memory.
Returns:

Array of length equal to the number of lines in buffer. Each entry is an array of strings, containing the delim-separated fields for its corresponding line.

Type
Array

retrieveParameters(state) → {object}

Description:

  • Retrieve analysis parameters from a state object.

Source:
Parameters:
Name Type Description
state object

Object containing the analysis state, produced by createAnalysis or loadAnalysis.
Returns:

Object containing the analysis parameters for each step, similar to that created by analysisDefaults.

Type
object

runAnalysis(state, datasets, params, optionsopt)

Description:

  • Run a basic single-cell RNA-seq analysis with the specified files and parameters. This will cache the results from each step so that, if the parameters change, only the affected steps will be rerun.

Source:
Parameters:
Name Type Attributes Description
state object

Object containing the analysis state, produced by createAnalysis or loadAnalysis.
datasets object

Object where each (arbitrarily named) property corresponds to an input dataset. Each dataset should be a object that satisfies the Dataset contract.

Alternatively, datasets may be null if the input datasets were already loaded and cached in state. This avoids the need to respecify the inputs after a previous call to runAnalysis or from loadAnalysis.
params object

An object containing parameters for all steps. See analysisDefaults for more details.
options object <optional>

Optional parameters.

Properties
Name Type Attributes Default Description
startFun function <optional>
<nullable>
 null

Function that is called when each step is started. This should accept a single argument - the name of the step. The return value is ignored, but any promises will be awaited before the analysis proceeds to the next step. If null, nothing is executed.
finishFun function <optional>
<nullable>
 null

Function that is called on successful execution of each step. This should accept a single argument - the name of the step. The return value is ignored, but any promises will be awaited before the analysis proceeds to the next step. If null, nothing is executed.
Returns:

A promise that resolves to null when all asynchronous analysis steps are complete. The contents of state are modified by reference to reflect the latest state of the analysis with the supplied parameters.

saveGenewiseResults(state, pathnullable, optionsopt) → (nullable) {Object}

Description:

  • Save the per-gene analysis results as data frames in the takane format. This includes the marker tables for the clusters and custom selections, as well as the variance modelling statistics from the feature selection step. Each data frames has the same order of rows as the SingleCellExperiment saved by saveSingleCellExperiment; for easier downstream use, we set the row names of each data frame to row names of the SingleCellExperiment (or if no row names are available, we set each data frame's row names to the first column of the rowData).

Source:
Parameters:
Name Type Attributes Default Description
state object

Existing analysis state containing results, after one or more runs of runAnalysis.
path string <nullable>

Local path in which to save all results. If a local filesystem is present and directory is supplied, path defines the subdirectory within directory in which the SingleCellExperiment is to be saved. If null, results are directly saved to directory itself.
options object <optional>
 {}

Optional parameters.

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

Whether to save the marker detection results.
includeCustomSelections boolean <optional>
 true

Whether to save the custom selection results.
includeFeatureSelection boolean <optional>
 true

Whether to save the feature selection results.
directory string <optional>
<nullable>
 null

Directory in which to save the data frames. If null or if no local file system exists, files are stored in memory as Uint8Arrays.
Returns:

If directory is supplied and a local filesystem exists, the data frame components are saved to disk and null is returned. Otherwise, if directory = null or a local filesystem does not exist, an object is returned where each key is a local path to a component file and each value is a Uint8Array with the file contents.

Type
Object

saveSingleCellExperiment(state, name, optionsopt) → (nullable) {Object}

Description:

  • Save the analysis results into a SingleCellExperiment using the takane format. This uses a language-agnostic format mostly based on HDF5 and JSON, which can be read into a variety of frameworks like R and Python. The aim is to facilitate downstream analysis procedures that are not supported by bakana itself; for example, a bench scientist can do a first pass with kana before passing the results to a computational collaborator for deeper inspection.

Source:
Parameters:
Name Type Attributes Default Description
state object

Existing analysis state containing results, after one or more runs of runAnalysis.
name string

Name of the SingleCellExperiment. This may also contain forward slashes, in which case it is treated as a local path. If a local filesystem is present and directory is supplied, name defines the subdirectory within directory in which the SingleCellExperiment is to be saved.
options object <optional>
 {}

Optional parameters.

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

Whether to report 1-based indices, for use in 1-based languages like R. Currently, this only refers to the column indices of the custom selections reported in the SingleCellExperiment's metadata.
storeModalityColumnData boolean <optional>
 false

Whether to store modality-specific per-cell statistics (e.g., QC metrics, size factors) in the column data of the associated alternative Experiment. This can yield a cleaner SingleCellExperiment as statistics are assigned to the relevant modalities. That said, the default is still false as many applications (including bakana itself, via the AbstractArtifactdbDataset and friends) will not parse the column data of alternative Experiments. In such cases, all modality-specific metrics are stored in the main experiment's column data with a modality-specific name, e.g., kana::ADT::quality_control::sums.
directory string <optional>
<nullable>
 null

Directory in which to save the components of the SingleCellExperiment. If null or if no local file system exists, files are stored in memory as Uint8Arrays.
Returns:

If directory is supplied and a local filesystem exists, the components are saved to disk and null is returned. Otherwise, if directory = null or a local filesystem does not exist, an object is returned where each key is a local path to a component file and each value is a Uint8Array with the file contents.

Type
Object

searchZippedAlabaster(handle) → {Map}

Description:
Source:
Parameters:
Name Type Description
handle JSZip

A handle into the ZIP file, generated using the JSZip package.
Returns:

Object where the keys are the paths/names of possible SummarizedExperiment objects, and each value is a 2-element array of dimensions.

Type
Map

searchZippedArtifactdb(handle) → {Map}

Description:
Source:
Parameters:
Name Type Description
handle JSZip

A handle into the ZIP file, generated using the JSZip package.
Returns:

Object where the keys are the paths/names of possible SummarizedExperiment objects, and each value is a 2-element array of dimensions.

Type
Map

(async) serializeConfiguration(state, saver) → {object}

Description:

  • Save the analysis configuration to file, including the parameters and datasets. This can be stringified and saved to file, or it can be used in unserializeConfiguration.

Source:
Parameters:
Name Type Description
state object

State object produced by createAnalysis and run through runAnalysis.
saver function

Function to save files, see serializeDatasets for more details.
Returns:

Object containing the serialized analysis configuration, with the following properties:

  • parameters, an object containing parameters that can be used in runAnalysis.
  • datasets, an object containing serialized datasets that can be used in unserializeDatasets.
  • other, an object containing more parameters that need special handling outside of parameters. This typically involves calling setter functions directly on the State objects:
Type
object

(async) serializeDatasets(datasets, saver) → {object}

Description:

  • Format a collection of Dataset objects so that they can be saved to file.

Source:
Parameters:
Name Type Description
datasets object

Object containing Dataset instances, just like that used in InputsState.compute.
saver function

Function that converts a SimpleFile instance into an identifier string. Specifically, it should accept three arguments:

  1. A string containing the name of the Dataset.
  2. A string containing the format of the Dataset, e.g., "10X", "MatrixMarket".
  3. A SimpleFile object representing one of the files of that Dataset.

It should then return a string that uniquely identifies this file within datasets. The nature of this string is left to the application, e.g., it may be a file path for Node.js, a virtual file path in the browser, or some database identifier. This function may be async.
Returns:

Object containing information about the files and datasets in datasets.

Type
object
Description:

  • Specify a function to create links for data files.

Source:
Parameters:
Name Type Description
fun function

Function that accepts:

  • format: the string containing the format of the dataset that owns the file.
  • file: a SimpleFile representing the file contents.

It should return a string containing some unique identifier to the file. This is most typically used to register the file with some user-specified database system for later retrieval.
Returns:

fun is set as the global link creator for this step. The previous value of the creator is returned.

Description:

  • Specify a function to resolve links for data files.

Source:
Parameters:
Name Type Description
fun function

Function that accepts a string containing a linking idenfier and returns any value that can be used in the SimpleFile constructor i.e., a Uint8Array, File (on browser) or string containing a file path (on Node.js). This is most typically used to retrieve a file from some user-specified database system.
Returns:

fun is set as the global resolver for this step. The previous value of the resolver is returned.

setVisualizationAnimate(fun)

Description:

  • Specify a function to handle animation iterations for the low-dimensional embeddings. The exact nature of this handling is arbitrary - developers may post the contents to another thread, save them to file, etc.

Source:
Parameters:
Name Type Description
fun function

Function to process each animation iteration. This should accept four arguments, in the following order:

  • A string containing either "tsne" or "umap".
  • A Float64Array containing the x-coordinates for each cell.
  • A Float64Array containing the y-coordinates for each cell.
  • An integer specifying the iteration number.
Returns:

fun is set as the global animator function for t-SNE and UMAP. The previous value of the animator is returned.

subsetInputs(state, indices, optionsopt) → {object}

Description:

  • Create a new analysis state object consisting of a subset of cells from an existing analysis state. This assumes that the existing state already contains loaded matrix data in its inputs property, which allows us to create a cheap reference without reloading the data into memory.

Source:
Parameters:
Name Type Attributes Description
state object

State object such as that produced by createAnalysis or linkAnalysis. This should already contain loaded data, e.g., after a run of runAnalysis.
indices TypedArray | Array

Array containing the indices for the desired subset of cells. This should be sorted and non-duplicate. Any existing subset in state 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 state itself contains an analysis of a subsetted dataset. If false, the indices are assumed to refer to the columns of the already-subsetted dataset that exists in state; if true, the indices are assumed to refer to the columns of the original dataset from which the subset in state was created.
Returns:

A state object containing loaded matrix data in its inputs property. Note that the other steps do not have any results, so this object should be passed through runAnalysis before it can be used.

Type
object

summarizeArray(array, optionsopt) → {object}

Description:

  • Summarize an array, typically corresponding to a single column of per-cell annotation. This can be used as part of a preflight response in a Reader.

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

Per-cell annotation array of length equal to the number of cells for a given matrix. An Array is treated as categorical data and should contain strings, while TypedArrays are treated as continuous data.
options object <optional>

Optional parameters.

Properties
Name Type Attributes Default Description
limit number <optional>
 50

Maximum number of unique values to report for categorical x.
Returns:

Object containing type, a string indicating whether array was categorical or continuous.

If "categorical", the object will contain values, an array of unique values up to the length specified by limit. It will also contain truncated, a boolean indicating whether the actual number of unique values exceeds limit.

If "continuous", the object will contain the numbers min and max specifying the minimum and maximum value in x, respectively. min or max may be negative or positive infinity, respectively, if there is no bound on one or both ends. If min > max, all values in array are NaNs such that no bound can be found.

Type
object

terminate()

Description:

  • Terminate the backend, in particular shutting down all workers. This is typically necessary for a clean shutdown in Node.js applications.

Source:
Returns:

A promise that resolves to null when all workers are terminated.

(async) unserializeConfiguration(serialized, loader, optionsopt) → {object}

Description:

  • Load the analysis configuration from its serialized format. This is effectively the reverse operation of serializeConfiguration.

Source:
Parameters:
Name Type Attributes Default Description
serialized object

Configuration object produced by serializeConfiguration.
loader function

Function to load files, see unserializeDatasets for more details.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
state object <optional>
 null

Existing state object to fill with parameters, typically created by createAnalysis. This may need to be specified by the caller when state is also required to define the startFun and finishFun callbacks. If null, a new state object is created within this function.
startFun function <optional>
<nullable>
 null

Passed directly to runAnalysis.
finishFun function <optional>
<nullable>
 null

Passed directly to runAnalysis.
Returns:

State object containing analysis results. This is identical to the state passed into serializeConfiguration.

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

Type
object

(async) unserializeDatasets(serialized, loader) → {object}

Description:

  • Unserialize dataset information into their corresponding Dataset instances. This assumes that availableReaders has been configured for all dataset formats that might be present.

Source:
Parameters:
Name Type Description
serialized object

Object containing the output of serializeDatasets.
loader function

Function that accepts a single argument, the identifier string produced by saver in serializeDatasets; and returns any value that can be used in the SimpleFile constructor. This may be async.
Returns:

An object containing Dataset instances that can be directly used in InputsState.compute.

Type
object

Type Definitions

AlabasterProjectNavigator

Description:

  • Any class that satisfies the AlabasterProjectNavigator contract, so called as it is intended to "navigate" an alabaster-formatted object directory. This should provide the following methods:

    • get(path, asBuffer), a (possibly async) method that accepts a string path containing a relative path to a file inside an object directory. This should return a string containing a path to the file on the local filesystem, or a Uint8Array containing the contents of the file if no local filesystem exists. If asBuffer = true, a Uint8Array must be returned.
    • exists(path), a (possibly async) method that accepts a string path containing a relative path to a file inside an object directory. This should return a boolean indicating whether path exists in the object directory.
    • clean(localPath), a (possibly async) method that accepts a string containing a local path returned by get(). It should remove any temporary file that was created by get() at localPath. This will not be called if get() returns a Uint8Array.
Source:

Any class that satisfies the AlabasterProjectNavigator contract, so called as it is intended to "navigate" an alabaster-formatted object directory. This should provide the following methods:

  • get(path, asBuffer), a (possibly async) method that accepts a string path containing a relative path to a file inside an object directory. This should return a string containing a path to the file on the local filesystem, or a Uint8Array containing the contents of the file if no local filesystem exists. If asBuffer = true, a Uint8Array must be returned.
  • exists(path), a (possibly async) method that accepts a string path containing a relative path to a file inside an object directory. This should return a boolean indicating whether path exists in the object directory.
  • clean(localPath), a (possibly async) method that accepts a string containing a local path returned by get(). It should remove any temporary file that was created by get() at localPath. This will not be called if get() returns a Uint8Array.

ArtifactdbProjectNavigator

Description:

  • Any class that satisfies the ArtifactdbProjectNavigator contract, so called as it is intended to "navigate" an ArtifactDB project directory. This should provide the following methods:

    • metadata(p), a (possibly async) method that accepts a string p containing a relative path to a resource inside an ArtifactDB project directory, and returns an object containing the metadata for that object. Any redirections should be resolved by this method.

      Note that AbstractArtifactdbDataset will automatically cache the outputs of all metadata() calls between any invocations of clear, to improve efficiency when repeatedly accessing the same metadata. The same applies to AbstractArtifactdbResult.

    • file(p), a (possibly async) method that accepts a string p containing a relative path inside a project directory and returns the contents of the file at that path. The return value should typically be a Uint8Array; on Node.js, methods may alternatively return a string containing a path to the file on the local file system. The method does not need to handle redirections from p.

    Optionally, the ArtifactdbProjectNavigator class may implement a clear() method to remove any cached content. This will be called by AbstractArtifactdbDataset.clear and AbstractArtifactdbResult.clear.

Source:

Any class that satisfies the ArtifactdbProjectNavigator contract, so called as it is intended to "navigate" an ArtifactDB project directory. This should provide the following methods:

  • metadata(p), a (possibly async) method that accepts a string p containing a relative path to a resource inside an ArtifactDB project directory, and returns an object containing the metadata for that object. Any redirections should be resolved by this method.

    Note that AbstractArtifactdbDataset will automatically cache the outputs of all metadata() calls between any invocations of clear, to improve efficiency when repeatedly accessing the same metadata. The same applies to AbstractArtifactdbResult.

  • file(p), a (possibly async) method that accepts a string p containing a relative path inside a project directory and returns the contents of the file at that path. The return value should typically be a Uint8Array; on Node.js, methods may alternatively return a string containing a path to the file on the local file system. The method does not need to handle redirections from p.

Optionally, the ArtifactdbProjectNavigator class may implement a clear() method to remove any cached content. This will be called by AbstractArtifactdbDataset.clear and AbstractArtifactdbResult.clear.

Dataset

Description:
Source:

Any class that satisfies the Dataset contract. Each class contains methods to load data from some arbitrary data source into ScranMatrix objects (for the counts) and DataFrame objects (for the feature or cell annotations). The default set of known dataset reader classes is listed in the availableReaders object and includes TenxHdf5Dataset, TenxMatrixMarketDataset, H5adDataset and SummarizedExperimentDataset instances.