WebNWB

Neurodata without Borders — directly on the browser.

webnwb is a library for reading and writing Neurodata without Borders (NWB) files on the web.

Features

• 🔬 Read data from NWB files based on the included specification.
• ⚡ Lazy-load large files (e.g. from the NIH Brain Initiative’s [Distributed Archives for Neurophysiology Data Integration (DANDI)](https://gui. dandiarchive.org/#/)).
• 📦 Create NWB files from scratch.
• ⚒️ Use helper functions like addAcquisition, getAcquisition, and createAcquisition to quickly write data to new and existing NWB files.

Note: While the read access is stable, write access still experimental and not well-documented. Future version of WebNWB will use the same syntax—but will likely re-implement many of the underlying write functions. Please see the Contributing section for more information.

Getting Started

File Creation Mode

To create a new NWB file, create an NWBFile instance using the API handle interactions:

import nwb from 'webnwb'

const now = Date.now()

// Instantiate the NWB File
const newFile = new nwb.NWBFile({
    sessionDescription: 'demonstrate NWBFile basics',
    identifier: 'NWB123',
    sessionStartTime: now,
    fileCreateDate: now,
})

// Create dummy timeseries data
const timestamps = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
const data = Array.from(timestamps, e => 100 + e * 10)
data.units = 'm'

newFile.addAcquisition('testTimeseries', { data, timestamps })

To save the file, you'll need an NWBHDF5IO instance to handle interactions with the underlying [h5wasm] API:

import nwb from 'webnwb'

const io = new nwb.NWBHDF5IO()

const filename = 'my_file.nwb'
io.save(file, filename)

Loading a Local File

Existing files can be loaded using the io.load method:

const file = io.load(filename)
const timeseries = file.acquisition['testTimeseries']

Changes can be made directly to the file object, and then saved using the io.save method. If a name is not provided, the file will be saved to the original location.

timeseries.data = Array.from(timestamps, e => 200 - e * 10) // NOTE: timeseries.data.units is still maintained as 'm' on the new array
io.save(file)

Streaming Mode

Streaming mode allows you to lazy-load data from a file without loading the entire file into memory. This is useful for large files, like those hosted on DANDI.

const streamed = io.load('http://localhost/my_file.nwb', { useStreaming: true })

These files require you to await properties, as they are not loaded until you request them.

const acquisition = await streamed.acquisition
const timeseries = await acquisition['testTimeseries']

Contributing

The essential features of the WebNWB API are aggregated in the api.ts file, which configures [hdf5-io] to process the underlying HDF5 file in a way that conforms with the NWB Schema.

Anyone who would like to contribute to the acceptance of webnwb as an official NWB API is welcome to messageGarrett Flynn to coordinate work on the following areas (or anything else you think will be useful):

1. Validate writing a dataset using best practices and the schema
2. Allow writing a dataset in place using the File Access API (Chrome)
3. Support Zarr as a backend file format

Derivative Packages

• hdf5-io: Load HDF5 files as JavaScript objects using [h5wasm].
• apify: A way to generate APIs from simple specification languages (e.g. the NWB Schema)
  • [esconform]((https://github.com/garrettmflynn/esconform): A generic library for enforcing schema properties
• dandi: A basic API for making calls to the DANDI REST API.

Known Issues

1. .specloc is not rewritten as an object reference
2. Since there isn't a file mode that allows overwriting existing properties, we have to create an entire new file representation when saving—and attributes are not written with the exact same type as they were at the beginning (e.g. from 64-bit floating-point to 32-bit integer). Is this a problem?
3. Sometimes we get a memory overload error before the file is completely written. This leads to partial rewrites...
4. Links, references, and tables (with references) are not yet supported.
5. Cannot save multidimensional arrays like the data property in a SpatialSeries.
6. Timestamp arrays can't be written (e.g. timestamps in a TimeSeries) because they are trying to convert to a BigInt by h5wasm.

Acknowledgments

Since January 2023, the development of WebNWB has been generously supported by a contract from the Kavli Foundation. The basic API was originally prototyped as part of the 2022 NWB-DANDI Remote Developer Hackathon and refined during the 2022 NWB User Days event by Garrett Flynn from Brains@Play.

h5wasm: https://github.com/usnistgov/h5wasm