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.

formatMarkerResults(results, group, rankEffect)

Description:

  • Report marker results for a given group or cluster, ordered so that the strongest candidate markers appear first.

Source:
Parameters:
Name Type Description
results ScoreMarkersResults

The marker results object generated by the scoreMarkers function in scran.js.
group number

Integer specifying the group or cluster of interest. Any number can be used if it was part of the groups passed to scoreMarkers.
rankEffect string

Summarized effect size to use for ranking markers. This should follow the format of <effect>-<summary> where <effect> may be lfc, cohen, auc or delta_detected, and <summary> may be min, mean or min-rank.
Returns:

An object containing the marker statistics for the selection, sorted by the specified effect and summary size from rankEffect. This contains:

  • means: a Float64Array of length equal to the number of genes, containing the mean expression within the selection.
  • detected: a Float64Array of length equal to the number of genes, containing the proportion of cells with detected expression inside the selection.
  • lfc: a Float64Array of length equal to the number of genes, containing the log-fold changes for the comparison between cells inside and outside the selection.
  • delta_detected: a Float64Array of length equal to the number of genes, containing the difference in the detected proportions between cells inside and outside the selection.

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, path, optionsopt) → {Array}

Description:

  • Save the per-gene analysis results into ArtifactDB data frames. 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

Path to a subdirectory inside the project directory in which to save all results. If null, this is treated as the root of the project directory.
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.
forceBuffer boolean <optional>
 true

Whether to force all files to be loaded into memory as Uint8Array buffers.
directory directory <optional>
<nullable>
 null

Project directory in which to save the file components of the SingleCellExperiment. Only used for Node.js; if supplied, it overrides any setting of forceBuffer.
Returns:

Array of objects where each object corresponds to a data frame of per-gene statistics. These data frames are grouped by analysis step, i.e., marker_detection, custom_selections and feature_selection. See saveSingleCellExperiment for more details on the contents of each object inside the returned array.

Type
Array

saveSingleCellExperiment(state, name, optionsopt) → {Array}

Description:

  • Save the analysis results into an ArtifactDB representation of a SingleCellExperiment. 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 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.
forceBuffer boolean <optional>
 true

Whether to force all files to be loaded into memory as Uint8Array buffers.
directory string <optional>
<nullable>
 null

Project directory in which to save the file components of the SingleCellExperiment. Only used for Node.js; if supplied, it overrides any setting of forceBuffer.
Returns:

Array of objects where each object corresponds to a file in the SingleCellExperiment's representation. Each inner object contains metadata, another object containing the metadata for the corresponding file.

For files that are not purely metadata, the inner object will also contain contents, the contents of the file. The type of contents depends on the context and optional parameters.

  • If forceBuffer = true, contents is a Uint8Array of the file contents. This is probably the most advisable setting for browser environments.
  • If forceBuffer = false, contents may be either a Uint8Array or a string to a temporary file path. In a browser context, the temporary path is located on the scran.js virtual file system, see here to extract its contents and to clean up afterwards.
  • If the function is called from Node.js and directory is supplied, contents is a string to a file path inside directory. This overrides any expectations from the setting of forceBuffer and is the most efficient approach for Node.js.

The SingleCellExperiment itself will be accessible from a top-level object at the path defined by name.

Type
Array

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

zipFiles(files, optionsopt) → {Promise.<Uint8Array>}

Description:

  • Zip a set of files, typically corresponding to the contents of an ArtifactDB project directory.

Source:
Parameters:
Name Type Attributes Default Description
files Array

Array of objects describing files in the project directory. See the output of saveSingleCellExperiment for more details on the expected format.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
extras Array <optional>
 []

Array of extra files to store inside the ZIP file (e.g., READMEs, notes). Each entry should be an object with the path property, containing the relative path of the file in the project directory; and contents, a Uint8Array containin the file contents.
Returns:

Uint8Array with the contents of the ZIP file containing all files.

Type
Promise.<Uint8Array>

Type Definitions

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.