Dataset Class

The NetCDF4 class (aliased as Dataset) is the main interface for working with NetCDF files. It provides methods for creating, reading, and writing NetCDF datasets.

Constructor

1

new NetCDF4(filename?: string, mode?: string, options?: DatasetOptions)

Parameters

  • filename (optional): Path to the NetCDF file
  • mode (optional): File access mode. Default: 'r'
    • 'r': Read-only
    • 'w': Write (create new file, overwrite if exists)
    • 'w-': Write (create new file, fail if exists)
    • 'a': Append (read/write existing file)
    • 'r+': Read/write existing file
  • options (optional): Additional options

Options

1
2
3
4
5
6
7

interface DatasetOptions {
    format?: string;           // 'NETCDF4' (default), 'NETCDF3_CLASSIC', etc.
    diskless?: boolean;        // Create diskless (in-memory) file
    persist?: boolean;         // Save diskless file on close
    keepweakref?: boolean;     // Keep weak reference to file
    memory?: ArrayBuffer;      // Initial memory for diskless file
}

Static Factory Methods

Dataset()

1
2
3
4
5

static async Dataset(
    filename: string, 
    mode?: string, 
    options?: DatasetOptions
): Promise<NetCDF4>

Recommended factory method that handles initialization automatically.

1

const dataset = await NetCDF4.Dataset('data.nc', 'r');

fromBlob()

1
2
3
4
5

static async fromBlob(
    blob: Blob,
    mode?: string,
    options?: DatasetOptions
): Promise<NetCDF4>

Create dataset from a Blob object (e.g., from file input).

1
2

const file = event.target.files[0]; // File is a Blob
const dataset = await NetCDF4.fromBlob(file, 'r');

fromArrayBuffer()

1
2
3
4
5

static async fromArrayBuffer(
    buffer: ArrayBuffer,
    mode?: string,
    options?: DatasetOptions
): Promise<NetCDF4>

Create dataset from an ArrayBuffer.

1
2
3

const response = await fetch('data.nc');
const buffer = await response.arrayBuffer();
const dataset = await NetCDF4.fromArrayBuffer(buffer, 'r');

fromMemory()

1
2
3
4
5
6

static async fromMemory(
    data: Uint8Array | ArrayBuffer,
    mode?: string,
    options?: DatasetOptions,
    filename?: string
): Promise<NetCDF4>

Create dataset from memory data with optional custom filename.

1
2

const data = new Uint8Array(1024);
const dataset = await NetCDF4.fromMemory(data, 'w', {}, '/tmp/custom.nc');

Properties

File Information

1
2
3
4

readonly file_format: string        // File format ('NETCDF4', 'NETCDF3_CLASSIC', etc.)
readonly disk_format: string        // Same as file_format
readonly filepath: string           // Path to the file
readonly isopen: boolean            // Whether file is currently open

Collections

1
2
3

readonly dimensions: {[name: string]: Dimension}    // Dictionary of dimensions
readonly variables: {[name: string]: Variable}      // Dictionary of variables
readonly groups: {[name: string]: Group}            // Dictionary of groups

Instance Methods

File Operations

initialize()

1

async initialize(): Promise<void>

Initialize the WASM module. Called automatically by factory methods.

1
2

const dataset = new NetCDF4('file.nc', 'r');
await dataset.initialize(); // Manual initialization required

close()

1

async close(): Promise<void>

Close the dataset and free resources.

1

await dataset.close();

sync()

1

async sync(): Promise<void>

Flush any buffered data to disk.

1

await dataset.sync();

Structure Definition

createDimension()

1

async createDimension(name: string, size: number | null): Promise<Dimension>

Create a new dimension. Use null for unlimited dimensions.

1
2

const timeDim = await dataset.createDimension('time', null); // unlimited
const latDim = await dataset.createDimension('lat', 180);    // fixed size

createVariable()

1
2
3
4
5
6

async createVariable(
    name: string,
    datatype: string,
    dimensions: string[],
    options?: VariableOptions
): Promise<Variable>

Create a new variable.

1
2

const temp = await dataset.createVariable('temperature', 'f8', ['time', 'lat', 'lon']);
const pressure = await dataset.createVariable('pressure', 'f4', ['time', 'level']);

Data Types:

  • 'f4': 32-bit float
  • 'f8': 64-bit float (double)
  • 'i1', 'i2', 'i4': Signed integers
  • 'u1', 'u2', 'u4': Unsigned integers

Variable Options:

1
2
3
4
5
6
7
8

interface VariableOptions {
    zlib?: boolean;         // Enable compression
    complevel?: number;     // Compression level (1-9)
    shuffle?: boolean;      // Enable shuffle filter
    fletcher32?: boolean;   // Enable checksum
    contiguous?: boolean;   // Contiguous storage
    chunksizes?: number[];  // Chunk sizes for each dimension
}

createGroup()

1

createGroup(name: string): Group

Create a hierarchical group (NetCDF4 only).

1
2

const observations = dataset.createGroup('observations');
const forecasts = dataset.createGroup('forecasts');

Attribute Operations

setAttr()

1

setAttr(name: string, value: any): void

Set a global attribute.

1
2
3

dataset.setAttr('title', 'My Dataset');
dataset.setAttr('version', 1.0);
dataset.setAttr('created', new Date().toISOString());

getAttr()

1

getAttr(name: string): any

Get a global attribute value.

1
2

const title = dataset.getAttr('title');
const version = dataset.getAttr('version');

attrs()

1

attrs(): string[]

Get list of all global attribute names.

1
2

const attrs = dataset.attrs();
console.log('Global attributes:', attrs);

Data Export

toArrayBuffer()

1

async toArrayBuffer(): Promise<ArrayBuffer>

Export dataset as ArrayBuffer (for in-memory datasets).

1

const buffer = await dataset.toArrayBuffer();

toBlob()

1

async toBlob(type?: string): Promise<Blob>

Export dataset as Blob for download.

1
2
3
4
5
6
7
8
9

const blob = await dataset.toBlob('application/x-netcdf');

// Create download link
const url = URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = url;
link.download = 'data.nc';
link.click();
URL.revokeObjectURL(url);

Utility Methods

isInitialized()

1

isInitialized(): boolean

Check if the WASM module is initialized.

1
2
3

if (dataset.isInitialized()) {
    // Safe to perform operations
}

toString()

1

toString(): string

Get string representation of the dataset.

1
2

console.log(dataset.toString());
// Output: <netCDF4.Dataset 'file.nc': mode = 'r', file format = 'NETCDF4', open>

Usage Examples

Creating a New Dataset

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

import { NetCDF4 } from 'netcdf4-wasm';

async function createDataset() {
    // Create new file
    const nc = await NetCDF4.Dataset('output.nc', 'w', { format: 'NETCDF4' });
    
    try {
        // Set global attributes
        nc.setAttr('Conventions', 'CF-1.8');
        nc.setAttr('title', 'Sample Dataset');
        nc.setAttr('institution', 'Example University');
        
        // Create dimensions
        const time = await nc.createDimension('time', null);  // unlimited
        const lat = await nc.createDimension('lat', 180);
        const lon = await nc.createDimension('lon', 360);
        
        // Create coordinate variables
        const timeVar = await nc.createVariable('time', 'f8', ['time']);
        timeVar.units = 'days since 2000-01-01';
        timeVar.calendar = 'gregorian';
        
        const latVar = await nc.createVariable('latitude', 'f4', ['lat']);
        latVar.units = 'degrees_north';
        latVar.standard_name = 'latitude';
        
        const lonVar = await nc.createVariable('longitude', 'f4', ['lon']);
        lonVar.units = 'degrees_east';
        lonVar.standard_name = 'longitude';
        
        // Create data variable
        const temp = await nc.createVariable('temperature', 'f4', ['time', 'lat', 'lon'], {
            zlib: true,
            complevel: 6
        });
        temp.units = 'K';
        temp.standard_name = 'air_temperature';
        temp._FillValue = -9999.0;
        
        // Write coordinate data
        const latData = new Float32Array(180);
        for (let i = 0; i < 180; i++) {
            latData[i] = -89.5 + i; // -89.5 to 89.5
        }
        await latVar.setValue(latData);
        
        const lonData = new Float32Array(360);
        for (let i = 0; i < 360; i++) {
            lonData[i] = -179.5 + i; // -179.5 to 179.5
        }
        await lonVar.setValue(lonData);
        
        // Write some temperature data
        const tempData = new Float32Array(180 * 360);
        for (let i = 0; i < tempData.length; i++) {
            tempData[i] = 273.15 + Math.random() * 30; // Random temperature
        }
        await temp.setValue(tempData);
        
    } finally {
        await nc.close();
    }
}

Reading an Existing Dataset

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

async function readDataset() {
    const nc = await NetCDF4.Dataset('data.nc', 'r');
    
    try {
        // Print file information
        console.log('File format:', nc.file_format);
        console.log('Dimensions:', Object.keys(nc.dimensions));
        console.log('Variables:', Object.keys(nc.variables));
        
        // Read global attributes
        const attrs = nc.attrs();
        attrs.forEach(attr => {
            console.log(`${attr}: ${nc.getAttr(attr)}`);
        });
        
        // Access variables
        const temp = nc.variables.temperature;
        if (temp) {
            console.log('Temperature attributes:');
            console.log('  units:', temp.units);
            console.log('  long_name:', temp.long_name);
            console.log('  shape:', temp.dimensions);
            
            // Read data
            const data = await temp.getValue();
            console.log('Temperature data statistics:');
            console.log('  min:', Math.min(...data));
            console.log('  max:', Math.max(...data));
            console.log('  mean:', data.reduce((a, b) => a + b) / data.length);
        }
        
    } finally {
        await nc.close();
    }
}

Working with Memory-based Datasets

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

async function memoryDataset() {
    // Create dataset in memory
    const nc = await NetCDF4.fromMemory(new Uint8Array(0), 'w');
    
    try {
        // Add structure and data
        await nc.createDimension('x', 10);
        const variable = await nc.createVariable('data', 'f8', ['x']);
        await variable.setValue(new Float64Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
        
        // Export to blob for download
        const blob = await nc.toBlob();
        
        // In browser, create download
        if (typeof window !== 'undefined') {
            const url = URL.createObjectURL(blob);
            const link = document.createElement('a');
            link.href = url;
            link.download = 'generated.nc';
            link.click();
            URL.revokeObjectURL(url);
        }
        
    } finally {
        await nc.close();
    }
}