netcdf4-async

NodeJS library provided async access to the Network Common Data Form (NetCDF) files.

Build upon version >=4 of libnetcdf and nodejs >=10.x. Inspired by synchronus version netcdf4

Installation

Prerequestment

You will need libnetcdf >= 4.x installed.

On Linux/Unix

• Make sure your system fulfills all the prerequisites of node-gyp

• Install NetCDF4 using your package manager:

  • Ubuntu/Debian:

    sudo apt-get install libnetcdf-dev

  • Alpine based:

    sudo apk add "netcdf-dev"

• Buld from source code. Either download source code from unidata site or from github repository, then follow the build instructions

On Windows

• Make sure your system fulfills all the prerequisites of node-gyp

• Install NetCDF4 from unidata site

• Set environment variable NETCDF_DIR to your netcdf installation, e.g

  C:> SET NETCDF_DIR=C:\Program files\netCDF 4.9.0

On MacOS

• Make sure your system fulfills all the prerequisites of node-gyp

• Install NetCDF via homebrew:

  brew install netcdf

Installation

Install netcdf4-async using npm:

npm install netcdf4-async

Usage

Import

const netcdf4 = require("netcdf4-async");

Supported netcdf types

| type | two-char synonym | one-char synonym | Note | | --- | --- | --- | --- | | byte | i1 | b B | | | char | | | | | short | i2 | h s | | | int | i4 | i l | | | ubyte | u1 | | | | ushort | u2 | | | | uint | u4 | | | | | float | f4 | f | | | double | f8 | d | | | uint64 | u8 | | NodeJS v>=10 | | int64 | i8 | | NodeJS v>=10 | | string | S1 | | |

NB! Not all types support in all file types

Module properties

• version : Contains netcdf4 library version. Properties are:
  • major : Major version (i.e. 4)
  • minor : Minor version (i.e. 8)
  • patch : Patch version (i.e. 1)
  • version : Version string (i.e. "4.8.1")

Example:

    {
    "major" : 4,
    "minor" : 8,
    "patch" : 1,
    "version" : "4.8.1"
    }

Methods

• open(path,mode[,format]): Return a promise resolved to File if file successfully opened, rejected otherwise

  • Parameters

    • path: path to file
    • mode: file open mode

    | mode | Description | | --- | --- | | r | read only | | w | read/write | | c | create if file not exsits, fail otherwise | | c! | create new or overwrite existing |

    • format: File type. Means classic or netcdf4 if omitted

  • Examples

    • Promises

    netcdf4.open('test.nc','r')
        .then(file=>do_process(file))
        .catch(e=>console.log(`Can't open file - ${e.message}`));

    • Async/await

    try{
        const file=await netcdf4.open('test.nc','r');
        await do_process(file);
    } catch (e) {
        console.log(`Can't open file - ${e.message}`)
    }

Classes

File

Represent netcdf file instance

• Properties
  • name: file path
  • format: file format
  • open: Set to true, if file open
  • root: Instance main Group object. Definied only when file opened
• Methods
  • sync(): Return a promise resolved if file successfully synced
  • close(): Return a promise resolved if file successfully closed, rejected otherwise
    • Examples
      • Promises

      file.close()
          .then(()=>console.log('File closed'))
          .catch(e=>console.log(`Error closing file - ${e.message}`));

      • Async/await

      try{
          await file.close();
      } catch (e) {
          console.log(`Error closing file - ${e.message}`)
      }

  • dataMode(): Return a promise resolved if file successfully perform nc_enddef(..)

Group

NetCDF group implementation.

From original documentation:

NetCDF-4 added support for hierarchical groups within netCDF datasets.

Group operations are only permitted on netCDF-4 files. Groups are not compatible with the netCDF classic data model except the root group.

Variable are only visible in the group in which they are defined. The same applies to attributes.

Dimensions are visible in their groups, and all child groups.

• Methods
  • getName() : Resolve promise to group name
  • setName(name): Rename group
  • getPath() : Resolve promise to full name (path in file)
  • getVariables() : Resolve to associative array of variables in group
  • getVariable(name) : Resolve to existing variable
  • addVariable(name,type,dimensions): Added variable to group. Resolves to instance of Variable.
    • Parameters:
      • name: Variable name
      • type: Variable type
      • dimensions: Array of dimenison names
  • getDimensions([unlimited]) : Resolve to associative array of dimensions or unlimited dimensions in group
    • Parameters
      • unlimited: Boolean. If set to true then retrun only unlimited dimensions
    • Resolved as list of objects

    {
        "name of dimension":length or 'unlimited',
        "name of dimension":length or 'unlimited',
        . . .
        "name of dimension":length or 'unlimited'
    }

  • addDimension(name,length): Added new dimension in a group.
  • renameDimension(oldName,newName): Rename dimension
  • getAttributes([asDefined]) : Resolve to associative array of attributes of group
    • Parameters
      • asDefined: Boolean. If set to true then instead value will return type and value
    • Resolved as list of objects
      • asDefined===false

      {
          "attribute_1":value_1,
          "attribute_1":value_1,
          . . .
          "attribute_n":value_n
      }

      • asDefined===true or not set

      {
          "attribute_1":{
              "type":"type of attribute",
              "value":value_1
          },
          "attribute_2":{
              "type":"type of attribute",
              "value":value_2
          },
          . . .
          "attribute_n":{
              "type":"type of attribute",
              "value":value_n
          },
      }

  • setAttribute(name,value,type?): Set value of attribute
  • renameAttribute(oldName,newName): Rename attribute
  • deleteAttribute(name): Delete attribute
  • getSubrgroups(..) : Resolve to associative array of subgroups of group
  • getSubgroup(name) : Resolve to subgroup
  • addSubgroup(name) : Resolve to new created subgroup

Variable

NetCDF variable

From original documentation:

Variables hold multi-dimensional arrays of data.

A netCDF variable has a name, a type, and a shape, which are specified when it is defined. A variable may also have values, which are established later in data mode.

Attributes may be associated with a variable to specify such properties as units.

• Properties

  • type: Variable type
  • name: Variable name.

• Methods

  • getName() : Resolve promise to variable name
  • setName(name): Rename variable
  • getDimensions() : Resolve to associative array of variable dimensions
    • Resolved as list of objects

    {
        "name of dimension":length or 'unlimited',
        "name of dimension":length or 'unlimited',
        . . .
        "name of dimension":length or 'unlimited'
    }

  • getFillMode(): Resolve to defaut fill value or undefined, if variable in no fill mode

  {
      "mode":"fill mode",
      "value":"fill value"
  }

  • setFillMode(value,mode): Set default fill value or switch variable to no fill mode if value is undefined/not provided
  • setFill(value) : Set default fill value
  • getFill() : Resolved to default fill value
  • getChunked(): Resolve to current chunk information

  {
      "mode":"chunk_mode",
      "sizes":[dim1_size,dim2_size,...,dimn_size]
  }

  • setChunked(mode,size?): Update information. size if provided must have same length as dimensions;
  • getDeflateInfo(): Resolve to current shuffle/deflate info

  {
      "shuffle":boolean,
      "deflate":boolean,
      "level":0-9
  }

  • setDeflateInfo(shuffle,deflate,deflateLevel): set shuffle/deflation value

  • getEndiannes(): Resolve to one of three value little,big,native

  • setEndianees(value): Set endiannes

  • getChecksumMode(): Resolve to fletcher or none

  • setChecksumMode(mode): Set checksum mode

  • getAttributes([asDefined]) : Resolve to associative array of attributes of group

    • Parameters
      • asDefined: Boolean. If set to true then instead value will return type and value
    • Resolved as list of objects
      • asDefined===false

      {
          "attribute_1":value_1,
          "attribute_1":value_1,
          . . .
          "attribute_n":value_n
      }

      • asDefined===false or not set

      {
          "attribute_1":{
              "type":"type of attribute",
              "value":value_1
          },
          "attribute_2":{
              "type":"type of attribute",
              "value":value_2
          },
          . . .
          "attribute_n":{
              "type":"type of attribute",
              "value":value_n
          },
      }

  • setAttribute(name,value): Set value of attribute

  • renameAttribute(oldName,newName): Rename attribute

  • deleteAttribute(name): Delete attribute

• Data access methods

  • read(pos....) : Reads and returns a single value at positions given as for write.
  • readSlice(pos, size....) : Reads and returns an array of values (cf. "Specify a Hyperslab") at positions and sizes given for each dimension, readSlice(pos1, size1, pos2, size2, ...) e.g. readSlice(2, 3, 4, 2) gives an array of the values at position 2 for 3 steps along the first dimension and position 4 for 2 steps along the second one.
  • readStridedSlice(pos, size, stride....) : Similar to readSlice(), but it adds a stride (interval between indices) parameter to each dimension. If stride is 4, the function will take 1 value, discard 3, take 1 again, etc. So for instance readStridedSlice(2, 3, 2, 4, 2, 1) gives an array of the values at position 2 for 3 steps with stride 2 (i.e. every other value) along the first dimension and position 4 for 2 steps with stride 1 (i.e. with no dropping) along the second dimension.
  • write(pos..., value) : Write value at positions given, e.g. write(2, 3, "a") writes "a" at position 2 along the first dimension and position 3 along the second one.
  • writeSlice(pos, size..., valuearray) : Write values in valuearray (must be a typed array) at positions and sizes given for each dimension, e.g. writeSlice(2, 3, 4, 2, new Int32Array([0, 1, 2, 3, 4, 5])) writes the array at position 2 for 3 steps along the first dimension and position 4 for 2 step along the second one (cf. "Specify a Hyperslab").
  • writeStridedSlice(pos, size, stride..., valuearray) : Similar to writeSlice(), but it adds a stride parameter to each dimension. So for instance writeStridedSlice(2, 3, 2, 4, 2, 1), new Int32Array([0, 1, 2, 3, 4, 5]) writes the array at position 2 for 3 steps with stride 2 (i.e. every other value) along the first dimension and position 4 for 2 steps with stride 1 (i.e. with no dropping) along the second dimension.

Knowing flaws

• Reading variable.getFill(..) or variable.getFillMode(..) for string type variables causes segfault with netcdf4 version prior to 4.6.1 due to knowing issue nc_inq_var_fill() doesn't work for NC_STRING if a fill value is set - segfault results. So, ubuntu<=18.04 is affected.