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.gC:> 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 toFile
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. Meansclassic
ornetcdf4
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 totrue
, if file open -
root
: Instance mainGroup
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}`) }
- Examples
-
dataMode()
: Return a promise resolved if file successfully performnc_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 ofVariable
.- Parameters:
-
name
: Variable name -
type
: Variable type -
dimensions
: Array of dimenison names
-
- Parameters:
-
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' }
- Parameters
-
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 }, }
-
- Parameters
-
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 valuelittle
,big
,native
-
setEndianees(value)
: Set endiannes -
getChecksumMode()
: Resolve tofletcher
ornone
-
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 }, }
-
- Parameters
-
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 forwrite
. -
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 toreadSlice()
, 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 instancereadStridedSlice(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)
: Writevalue
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 invaluearray
(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 towriteSlice()
, but it adds a stride parameter to each dimension. So for instancewriteStridedSlice(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(..)
orvariable.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.