Codebase list netcdf4-python / dfec5ef
Update upstream source from tag 'upstream/1.5.6' Update to upstream version '1.5.6' with Debian dir 0d34dd57bc5ae3e18c3127072f3c145f5387810c Bas Couwenberg 3 years ago
33 changed file(s) with 12393 addition(s) and 14638 deletion(s). Raw diff Collapse all Expand all
+0
-57
.appveyor.yml less more
0 environment:
1 PYTHON: "C:\\myminiconda3"
2 matrix:
3 - NPY: 1.17
4 PY: 3.7
5
6 - NPY: 1.17
7 PY: 3.8
8
9 init:
10 - "ECHO %PYTHON_VERSION% %MINICONDA%"
11
12 install:
13 # If there is a newer build queued for the same PR, cancel this one.
14 # The AppVeyor 'rollout builds' option is supposed to serve the same
15 # purpose but it is problematic because it tends to cancel builds pushed
16 # directly to master instead of just PR builds (or the converse).
17 # credits: JuliaLang developers.
18 - ps: if ($env:APPVEYOR_PULL_REQUEST_NUMBER -and $env:APPVEYOR_BUILD_NUMBER -ne ((Invoke-RestMethod `
19 https://ci.appveyor.com/api/projects/$env:APPVEYOR_ACCOUNT_NAME/$env:APPVEYOR_PROJECT_SLUG/history?recordsNumber=50).builds | `
20 Where-Object pullRequestId -eq $env:APPVEYOR_PULL_REQUEST_NUMBER)[0].buildNumber) { `
21 throw "There are newer queued builds for this pull request, failing early." }
22
23 # Add path, activate `conda` and update conda.
24 - set URL="https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe"
25 - curl -fsS -o miniconda3.exe %URL%
26 - start /wait "" miniconda3.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%PYTHON%
27
28 - "set PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%"
29 - call %PYTHON%\Scripts\activate
30
31 - conda config --set always_yes yes --set changeps1 no --set show_channel_urls true
32 - conda config --add channels conda-forge --force
33 - set PYTHONUNBUFFERED=1
34 - conda install conda-build vs2008_express_vc_python_patch
35 - call setup_x64
36
37 - conda create --name TEST python=%PY% numpy=%NPY% cython pip pytest hdf5 libnetcdf cftime
38 - conda activate TEST
39
40 - echo [options] > setup.cfg
41 - echo [directories] >> setup.cfg
42 - echo HDF5_libdir = %CONDA_PREFIX%\Library\lib >> setup.cfg
43 - echo HDF5_incdir = %CONDA_PREFIX%\Library\include >> setup.cfg
44 - echo netCDF4_libdir = %CONDA_PREFIX%\Library\lib >> setup.cfg
45 - echo netCDF4_incdir = %CONDA_PREFIX%\Library\include >> setup.cfg
46
47 - conda info --all
48 - conda list
49
50 # Skip .NET project specific build phase.
51 build: off
52
53 test_script:
54 - python -m pip install . --no-deps --ignore-installed --no-cache-dir -vv
55 - set NO_NET=1
56 - cd test && python run_all.py
0 name: Build and Test Linux
1 on: [push, pull_request]
2 jobs:
3 build-linux:
4 name: Python (${{ matrix.python-version }})
5 runs-on: ubuntu-latest
6 env:
7 PNETCDF_VERSION: 1.12.1
8 NETCDF_VERSION: 4.7.4
9 NETCDF_DIR: ${{ github.workspace }}/..
10 NETCDF_EXTRA_CONFIG: --enable-pnetcdf
11 CC: mpicc.mpich
12 # NO_NET: 1
13 strategy:
14 matrix:
15 python-version: ["3.9"]
16 steps:
17
18 - uses: actions/checkout@v2
19
20 - name: Set up Python ${{ matrix.python-version }}
21 uses: actions/setup-python@v2
22 with:
23 python-version: ${{ matrix.python-version }}
24
25 - name: Install Ubuntu Dependencies
26 run: |
27 sudo apt-get update
28 sudo apt-get install mpich libmpich-dev libhdf5-mpich-dev libcurl4-openssl-dev
29 echo "Download and build PnetCDF version ${PNETCDF_VERSION}"
30 wget https://parallel-netcdf.github.io/Release/pnetcdf-${PNETCDF_VERSION}.tar.gz
31 tar -xzf pnetcdf-${PNETCDF_VERSION}.tar.gz
32 pushd pnetcdf-${PNETCDF_VERSION}
33 ./configure --prefix $NETCDF_DIR --enable-shared --disable-fortran --disable-cxx
34 make -j 2
35 make install
36 popd
37 echo "Download and build netCDF version ${NETCDF_VERSION}"
38 wget ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-c-${NETCDF_VERSION}.tar.gz
39 tar -xzf netcdf-c-${NETCDF_VERSION}.tar.gz
40 pushd netcdf-c-${NETCDF_VERSION}
41 export CPPFLAGS="-I/usr/include/hdf5/mpich -I${NETCDF_DIR}/include"
42 export LDFLAGS="-L${NETCDF_DIR}/lib"
43 export LIBS="-lhdf5_mpich_hl -lhdf5_mpich -lm -lz"
44 ./configure --prefix $NETCDF_DIR --enable-netcdf-4 --enable-shared --enable-dap --enable-parallel4 $NETCDF_EXTRA_CONFIG
45 make -j 2
46 make install
47 popd
48
49 # - name: The job has failed
50 # if: ${{ failure() }}
51 # run: |
52 # cd netcdf-c-${NETCDF_VERSION}
53 # cat config.log
54
55 - name: Install python dependencies via pip
56 run: |
57 python -m pip install --upgrade pip
58 pip install numpy cython cftime pytest twine wheel check-manifest mpi4py
59
60 - name: Install netcdf4-python
61 run: |
62 export PATH=${NETCDF_DIR}/bin:${PATH}
63 python setup.py install
64 - name: Test
65 run: |
66 export PATH=${NETCDF_DIR}/bin:${PATH}
67 python checkversion.py
68 # serial
69 cd test
70 python run_all.py
71 # parallel (hdf5 for netcdf4, pnetcdf for netcdf3)
72 cd ../examples
73 mpirun.mpich -np 4 python mpi_example.py
74 if [ $? -ne 0 ] ; then
75 echo "hdf5 mpi test failed!"
76 exit 1
77 else
78 echo "hdf5 mpi test passed!"
79 fi
80 mpirun.mpich -np 4 python mpi_example.py NETCDF3_64BIT_DATA
81 if [ $? -ne 0 ] ; then
82 echo "pnetcdf mpi test failed!"
83 exit 1
84 else
85 echo "pnetcdf mpi test passed!"
86 fi
87
88 - name: Tarball
89 run: |
90 export PATH=${NETCDF_DIR}/bin:${PATH}
91 python setup.py --version
92 pip wheel . -w dist --no-deps
93 check-manifest --verbose
94 twine check dist/*
0 name: Build and Test
1
2 on:
3 pull_request:
4 push:
5 branches: [master]
6
7 jobs:
8 run-serial:
9 runs-on: ${{ matrix.os }}
10 strategy:
11 matrix:
12 python-version: ["3.6", "3.7", "3.8", "3.9"]
13 os: [windows-latest, ubuntu-latest, macos-latest]
14 platform: [x64, x32]
15 exclude:
16 - os: macos-latest
17 platform: x32
18 steps:
19 - uses: actions/checkout@v2
20
21 - name: Setup Conda
22 uses: s-weigand/setup-conda@v1
23 with:
24 activate-conda: false
25 conda-channels: conda-forge
26
27 - name: Python ${{ matrix.python-version }}
28 shell: bash -l {0}
29 run: |
30 conda create --name TEST python=${{ matrix.python-version }} numpy cython pip pytest hdf5 libnetcdf cftime --strict-channel-priority
31 source activate TEST
32 export PATH="${CONDA_PREFIX}/bin:${CONDA_PREFIX}/Library/bin:$PATH" # so setup.py finds nc-config
33 pip install -e . --no-deps --force-reinstall
34 conda info --all
35 conda list
36
37 - name: Tests
38 shell: bash -l {0}
39 run: |
40 source activate TEST
41 cd test && python run_all.py
42
43 run-mpi:
44 runs-on: ${{ matrix.os }}
45 strategy:
46 matrix:
47 python-version: [ "3.9" ]
48 os: [ubuntu-latest]
49 platform: [x64]
50 steps:
51 - uses: actions/checkout@v2
52
53 - name: Setup Conda
54 uses: s-weigand/setup-conda@v1
55 with:
56 activate-conda: false
57 conda-channels: conda-forge
58
59 - name: Python ${{ matrix.python-version }}
60 shell: bash -l {0}
61 run: |
62 conda create --name TEST python=${{ matrix.python-version }} numpy cython pip pytest mpi4py hdf5=*=mpi* libnetcdf=*=mpi* cftime --strict-channel-priority
63 source activate TEST
64 export PATH="${CONDA_PREFIX}/bin:${CONDA_PREFIX}/Library/bin:$PATH" # so setup.py finds nc-config
65 pip install -e . --no-deps --force-reinstall
66 conda info --all
67 conda list
68
69 - name: Tests
70 shell: bash -l {0}
71 run: |
72 source activate TEST
73 cd test && python run_all.py
74 cd ../examples
75 export PATH="${CONDA_PREFIX}/bin:${CONDA_PREFIX}/Library/bin:$PATH"
76 which mpirun
77 mpirun --version
78 mpirun -np 4 python mpi_example.py
79 if [ $? -ne 0 ] ; then
80 echo "hdf5 mpi test failed!"
81 exit 1
82 else
83 echo "hdf5 mpi test passed!"
84 fi
+0
-101
.travis.yml less more
0 language: python
1 dist: bionic
2 cache: pip
3
4 addons:
5 apt:
6 packages:
7 - libhdf5-serial-dev
8 - netcdf-bin
9 - libnetcdf-dev
10
11 env:
12 global:
13 - DEPENDS="numpy>=1.10.0 cython>=0.21 setuptools>=18.0 cftime"
14 - NO_NET=1
15 - MPI=0
16
17 python:
18 - "3.6"
19 - "3.7"
20 - "3.8"
21
22 matrix:
23 allow_failures:
24 - python: 3.8
25 env:
26 - MPI=1
27 - CC=mpicc.mpich
28 - DEPENDS="numpy>=1.10.0 cython>=0.21 setuptools>=18.0 mpi4py>=1.3.1 cftime"
29 - NETCDF_VERSION=GITMASTER
30 - NETCDF_DIR=$HOME
31 - PATH=${NETCDF_DIR}/bin:${PATH} # pick up nc-config here
32 include:
33 # test MPI with latest released version
34 - python: 3.8
35 env:
36 - MPI=1
37 - CC=mpicc.mpich
38 - DEPENDS="numpy>=1.10.0 cython>=0.21 setuptools>=18.0 mpi4py>=1.3.1 cftime"
39 - NETCDF_VERSION=4.7.3
40 - PNETCDF_VERSION=1.12.1
41 - NETCDF_DIR=$HOME
42 - PATH=${NETCDF_DIR}/bin:${PATH} # pick up nc-config here
43 addons:
44 apt:
45 packages:
46 - mpich
47 - libmpich-dev
48 - libhdf5-mpich-dev
49 # test with netcdf-c from github master
50 - python: 3.8
51 env:
52 - MPI=1
53 - CC=mpicc.mpich
54 - DEPENDS="numpy>=1.10.0 cython>=0.21 setuptools>=18.0 mpi4py>=1.3.1 cftime"
55 - NETCDF_VERSION=GITMASTER
56 - NETCDF_DIR=$HOME
57 - PATH=${NETCDF_DIR}/bin:${PATH} # pick up nc-config here
58 addons:
59 apt:
60 packages:
61 - mpich
62 - libmpich-dev
63 - libhdf5-mpich-dev
64
65 notifications:
66 email: false
67
68 before_install:
69 - pip install $DEPENDS
70
71 install:
72 - if [ $MPI -eq 1 ] ; then ci/travis/build-parallel-netcdf.sh; fi
73 - python setup.py build
74 - python setup.py install
75
76 script:
77 - cd test
78 - python run_all.py
79 - |
80 echo "MPI = ${MPI}"
81 echo "PNETCDF_VERSION = ${PNETCDF_VERSION}"
82 if [ $MPI -eq 1 ] ; then
83 cd ../examples
84 mpirun.mpich -np 4 python mpi_example.py
85 if [ $? -ne 0 ] ; then
86 echo "mpi test failed!"
87 exit 1
88 else
89 echo "mpi test passed!"
90 fi
91 if [ -n "${PNETCDF_VERSION}" ] ; then
92 mpirun.mpich -np 4 python mpi_example.py NETCDF3_64BIT_DATA
93 if [ $? -ne 0 ] ; then
94 echo "PnetCDF mpi test failed!"
95 exit 1
96 else
97 echo "PnetCDF mpi test passed!"
98 fi
99 fi
100 fi
0 version 1.5.6 (tag v1.5.6rel)
1 ==============================
2 * move CI/CD tests from travis/appveyor to Github Actions (PR #1061).
3 * move netCDF4 dir under src so module can be imported in source directory (PR #1062).
4 * change numpy.bool to numpy.bool_ and numpy.float to numpy.float_ (float and
5 bool are deprecated in numpy 1.20, issue #1065)
6 * clean up docstrings so that they work with latest pdoc.
7 * update cython numpy API to remove deprecation warnings.
8 * Add "fromcdl" and "tocdl" Dataset methods for import/export of CDL
9 via ncdump/ncgen called externally via the subprocess module (issue #1078).
10 * remove python 2.7 support.
11 * broadcast data (if possible)to conform to variable shape when writing to a slice
12 (issue #1083).
13
014 version 1.5.5.1 (tag v1.5.5.1rel)
115 ==================================
216 * rebuild binary wheels for linux and OSX to link netcdf-c 4.7.4 and hdf5 1.12.0.
0 recursive-include docs *
0 include docs/index.html
11 recursive-include man *
22 include MANIFEST.in
3 include README.md
4 include COPYING
3 include README.htmldocs
54 include Changelog
6 include appveyor.yml
7 include .travis.yml
85 include setup.cfg
96 include examples/*py
10 include examples/*ipynb
117 include examples/README.md
128 include test/*py
139 include test/*nc
14 include netCDF4/__init__.py
15 include netCDF4/_netCDF4.pyx
16 include netCDF4/utils.py
10 include src/netCDF4/__init__.py
11 include src/netCDF4/_netCDF4.pyx
12 include src/netCDF4/utils.py
1713 include include/netCDF4.pxi
1814 include include/mpi-compat.h
1915 include include/membuf.pyx
16 include *.md
17 include *.py
18 include *.release
19 include *.sh
20 include LICENSE
+0
-15
README.gh-pages less more
0 To update web docs at http://github.unidata.io/netcdf4-python:
1
2 First install fork of pdoc from https://github.com/jswhit/pdoc (requires mako,
3 markdown, pygments and future).
4
5 Then in netcdf4-python github clone directory (after building and
6 installing github master),
7
8 * generate docs (sh create_docs.sh)
9 * copy docs/netCDF4/index.html up one level (cp docs/netCDF4/index.html ..)
10 * git checkout gh-pages
11 * cp ../index.html .
12 * git commit index.html
13 * git push origin gh-pages
14 * git checkout master
0 To update web docs at http://github.unidata.io/netcdf4-python:
1
2 First install pdoc (https://github.com/mitmproxy/pdoc)
3
4 Then in netcdf4-python github clone directory (after building and
5 installing github master),
6
7 * generate docs (sh create_docs.sh)
8 * edit docs/index.html and clean up as needed.
00 # [netcdf4-python](http://unidata.github.io/netcdf4-python)
11 [Python](http://python.org)/[numpy](http://numpy.org) interface to the netCDF [C library](https://github.com/Unidata/netcdf-c).
22
3 [![Linux Build Status](https://travis-ci.org/Unidata/netcdf4-python.svg?branch=master)](https://travis-ci.org/Unidata/netcdf4-python)
4 [![Windows Build Status](https://ci.appveyor.com/api/projects/status/fl9taa9je4e6wi7n/branch/master?svg=true)](https://ci.appveyor.com/project/jswhit/netcdf4-python/branch/master)
3 [![Build status](https://github.com/Unidata/netcdf4-python/workflows/Build%20and%20Test/badge.svg)](https://github.com/Unidata/netcdf4-python/actions)
54 [![PyPI package](https://badge.fury.io/py/netCDF4.svg)](http://python.org/pypi/netCDF4)
65 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/netCDF4/badges/version.svg)](https://anaconda.org/conda-forge/netCDF4)
76 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2592291.svg)](https://doi.org/10.5281/zenodo.2592290)
87
98 ## News
109 For details on the latest updates, see the [Changelog](https://github.com/Unidata/netcdf4-python/blob/master/Changelog).
10
11 2/15/2020: Version [1.5.6](https://pypi.python.org/pypi/netCDF4/1.5.6) released. Added `Dataset.fromcdl` and `Dataset.tocdl`, which require `ncdump` and `ncgen` utilities to be in `$PATH`. Removed python 2.7 support.
1112
1213 12/20/2020: Version [1.5.5.1](https://pypi.python.org/pypi/netCDF4/1.5.5.1) released.
1314 Updated binary wheels for OSX and linux that link latest netcdf-c and hdf5 libs.
+0
-34
ci/travis/build-parallel-netcdf.sh less more
0 #!/bin/bash
1
2 set -e
3
4 pushd /tmp
5 if [ -n "${PNETCDF_VERSION}" ]; then
6 echo "Using downloaded PnetCDF version ${PNETCDF_VERSION}"
7 wget https://parallel-netcdf.github.io/Release/pnetcdf-${PNETCDF_VERSION}.tar.gz
8 tar -xzf pnetcdf-${PNETCDF_VERSION}.tar.gz
9 pushd pnetcdf-${PNETCDF_VERSION}
10 ./configure --prefix $NETCDF_DIR --enable-shared --disable-fortran --disable-cxx
11 NETCDF_EXTRA_CONFIG="--enable-pnetcdf"
12 make -j 2
13 make install
14 popd
15 fi
16 echo "Using downloaded netCDF version ${NETCDF_VERSION} with parallel capabilities enabled"
17 if [ ${NETCDF_VERSION} == "GITMASTER" ]; then
18 git clone http://github.com/Unidata/netcdf-c netcdf-c
19 pushd netcdf-c
20 autoreconf -i
21 else
22 wget ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-c-${NETCDF_VERSION}.tar.gz
23 tar -xzf netcdf-c-${NETCDF_VERSION}.tar.gz
24 pushd netcdf-c-${NETCDF_VERSION}
25 fi
26 # for Ubuntu xenial
27 export CPPFLAGS="-I/usr/include/hdf5/mpich -I${NETCDF_DIR}/include"
28 export LDFLAGS="-L${NETCDF_DIR}/lib"
29 export LIBS="-lhdf5_mpich_hl -lhdf5_mpich -lm -lz"
30 ./configure --prefix $NETCDF_DIR --enable-netcdf-4 --enable-shared --disable-dap --enable-parallel4 $NETCDF_EXTRA_CONFIG
31 make -j 2
32 make install
33 popd
0 # Uses pdoc (https://github.com/BurntSushi/pdoc)
0 # Uses pdoc (https://github.com/mitmproxy/pdoc)
11 # to create html docs from docstrings in Cython source.
2 # Use hacked version at https://github.com/jswhit/pdoc
3 # which extracts cython method docstrings and function signatures.
4 pdoc --html --html-no-source --overwrite --html-dir 'docs' netCDF4
2 /Users/jwhitaker/.local/bin/pdoc -o 'docs' netCDF4
3 # use resulting docs/netCDF4/_netCDF4.html
4 cp docs/netCDF4/_netCDF4.html docs/index.html
5 sed -i -e 's!href="../netCDF4.html!href="./index.html!g' docs/index.html
6 sed -i -e 's!/../netCDF4.html!/index.html!g' docs/index.html
7 sed -i -e 's!._netCDF4 API! API!g' docs/index.html
8 sed -i -e 's!netCDF4</a>._netCDF4</h1>!netCDF4</a></h1>!g' docs/index.html
9
0 <meta http-equiv="refresh" content="0; url=./netCDF4/index.html" />
0 <!doctype html>
1 <html lang="en">
2 <head>
3 <meta charset="utf-8">
4 <meta name="viewport" content="width=device-width, initial-scale=1">
5 <meta name="generator" content="pdoc" />
6 <title>netCDF4 API documentation</title>
7 <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%2264%22%20height%3D%2264%22%20viewBox%3D%2244.5%202.5%2015%2015%22%3E%3Cpath%20d%3D%22M49.351%2021.041c-.233-.721-.546-2.408-.772-4.076-.042-.09-.067-.187-.046-.288-.166-1.347-.277-2.625-.241-3.351-1.378-1.008-2.271-2.586-2.271-4.362%200-.976.272-1.935.788-2.774.057-.094.122-.18.184-.268-.033-.167-.052-.339-.052-.516%200-1.477%201.202-2.679%202.679-2.679.791%200%201.496.352%201.987.9a6.3%206.3%200%200%201%201.001.029c.492-.564%201.207-.929%202.012-.929%201.477%200%202.679%201.202%202.679%202.679a2.65%202.65%200%200%201-.269%201.148c.383.747.595%201.572.595%202.41%200%202.311-1.507%204.29-3.635%205.107.037.699.147%202.27.423%203.294l.137.461c.156%202.136-4.612%205.166-5.199%203.215zm.127-4.919a4.78%204.78%200%200%200%20.775-.584c-.172-.115-.505-.254-.88-.378zm.331%202.302l.828-.502c-.202-.143-.576-.328-.984-.49zm.45%202.157l.701-.403c-.214-.115-.536-.249-.891-.376l.19.779zM49.13%204.141c0%20.152.123.276.276.276s.275-.124.275-.276-.123-.276-.276-.276-.275.124-.275.276zm.735-.389a1.15%201.15%200%200%201%20.314.783%201.16%201.16%200%200%201-1.162%201.162c-.457%200-.842-.27-1.032-.653-.026.117-.042.238-.042.362a1.68%201.68%200%200%200%201.679%201.679%201.68%201.68%200%200%200%201.679-1.679c0-.843-.626-1.535-1.436-1.654zm3.076%201.654a1.68%201.68%200%200%200%201.679%201.679%201.68%201.68%200%200%200%201.679-1.679c0-.037-.009-.072-.011-.109-.21.3-.541.508-.935.508a1.16%201.16%200%200%201-1.162-1.162%201.14%201.14%200%200%201%20.474-.912c-.015%200-.03-.005-.045-.005-.926.001-1.679.754-1.679%201.68zm1.861-1.265c0%20.152.123.276.276.276s.275-.124.275-.276-.123-.276-.276-.276-.275.124-.275.276zm1.823%204.823c0-.52-.103-1.035-.288-1.52-.466.394-1.06.64-1.717.64-1.144%200-2.116-.725-2.499-1.738-.383%201.012-1.355%201.738-2.499%201.738-.867%200-1.631-.421-2.121-1.062-.307.605-.478%201.267-.478%201.942%200%202.486%202.153%204.51%204.801%204.51s4.801-2.023%204.801-4.51zm-3.032%209.156l-.146-.492c-.276-1.02-.395-2.457-.444-3.268a6.11%206.11%200%200%201-1.18.115%206.01%206.01%200%200%201-2.536-.562l.006.175c.802.215%201.848.612%202.021%201.25.079.295-.021.601-.274.837l-.598.501c.667.304%201.243.698%201.311%201.179.02.144.022.507-.393.787l-.564.365c1.285.521%201.361.96%201.381%201.126.018.142.011.496-.427.746l-.854.489c.064-1.19%201.985-2.585%202.697-3.248zM49.34%209.925c0-.667%201-.667%201%200%200%20.653.818%201.205%201.787%201.205s1.787-.552%201.787-1.205c0-.667%201-.667%201%200%200%201.216-1.25%202.205-2.787%202.205s-2.787-.989-2.787-2.205zm-.887-7.633c-.093.077-.205.114-.317.114a.5.5%200%200%201-.318-.886L49.183.397a.5.5%200%200%201%20.703.068.5.5%200%200%201-.069.703zm7.661-.065c-.086%200-.173-.022-.253-.068l-1.523-.893c-.575-.337-.069-1.2.506-.863l1.523.892a.5.5%200%200%201%20.179.685c-.094.158-.261.247-.432.247z%22%20fill%3D%22%233bb300%22/%3E%3C/svg%3E"/>
8
9
10 <style type="text/css">/*! * Bootstrap Reboot v5.0.0-beta1 (https://getbootstrap.com/) * Copyright 2011-2020 The Bootstrap Authors * Copyright 2011-2020 Twitter, Inc. * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE) * Forked from Normalize.css, licensed MIT (https://github.com/necolas/normalize.css/blob/master/LICENSE.md) */*,::after,::before{box-sizing:border-box}@media (prefers-reduced-motion:no-preference){:root{scroll-behavior:smooth}}body{margin:0;font-family:system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans","Liberation Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-size:1rem;font-weight:400;line-height:1.5;color:#212529;background-color:#fff;-webkit-text-size-adjust:100%;-webkit-tap-highlight-color:transparent}[tabindex="-1"]:focus:not(:focus-visible){outline:0!important}hr{margin:1rem 0;color:inherit;background-color:currentColor;border:0;opacity:.25}hr:not([size]){height:1px}h1,h2,h3,h4,h5,h6{margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2}h1{font-size:calc(1.375rem + 1.5vw)}@media (min-width:1200px){h1{font-size:2.5rem}}h2{font-size:calc(1.325rem + .9vw)}@media (min-width:1200px){h2{font-size:2rem}}h3{font-size:calc(1.3rem + .6vw)}@media (min-width:1200px){h3{font-size:1.75rem}}h4{font-size:calc(1.275rem + .3vw)}@media (min-width:1200px){h4{font-size:1.5rem}}h5{font-size:1.25rem}h6{font-size:1rem}p{margin-top:0;margin-bottom:1rem}abbr[data-bs-original-title],abbr[title]{text-decoration:underline;-webkit-text-decoration:underline dotted;text-decoration:underline dotted;cursor:help;-webkit-text-decoration-skip-ink:none;text-decoration-skip-ink:none}address{margin-bottom:1rem;font-style:normal;line-height:inherit}ol,ul{padding-left:2rem}dl,ol,ul{margin-top:0;margin-bottom:1rem}ol ol,ol ul,ul ol,ul ul{margin-bottom:0}dt{font-weight:700}dd{margin-bottom:.5rem;margin-left:0}blockquote{margin:0 0 1rem}b,strong{font-weight:bolder}small{font-size:.875em}mark{padding:.2em;background-color:#fcf8e3}sub,sup{position:relative;font-size:.75em;line-height:0;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}a{color:#0d6efd;text-decoration:underline}a:hover{color:#0a58ca}a:not([href]):not([class]),a:not([href]):not([class]):hover{color:inherit;text-decoration:none}code,kbd,pre,samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:1em;direction:ltr;unicode-bidi:bidi-override}pre{display:block;margin-top:0;margin-bottom:1rem;overflow:auto;font-size:.875em}pre code{font-size:inherit;color:inherit;word-break:normal}code{font-size:.875em;color:#d63384;word-wrap:break-word}a>code{color:inherit}kbd{padding:.2rem .4rem;font-size:.875em;color:#fff;background-color:#212529;border-radius:.2rem}kbd kbd{padding:0;font-size:1em;font-weight:700}figure{margin:0 0 1rem}img,svg{vertical-align:middle}table{caption-side:bottom;border-collapse:collapse}caption{padding-top:.5rem;padding-bottom:.5rem;color:#6c757d;text-align:left}th{text-align:inherit;text-align:-webkit-match-parent}tbody,td,tfoot,th,thead,tr{border-color:inherit;border-style:solid;border-width:0}label{display:inline-block}button{border-radius:0}button:focus{outline:dotted 1px;outline:-webkit-focus-ring-color auto 5px}button,input,optgroup,select,textarea{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,select{text-transform:none}[role=button]{cursor:pointer}select{word-wrap:normal}[list]::-webkit-calendar-picker-indicator{display:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]:not(:disabled),[type=reset]:not(:disabled),[type=submit]:not(:disabled),button:not(:disabled){cursor:pointer}::-moz-focus-inner{padding:0;border-style:none}textarea{resize:vertical}fieldset{min-width:0;padding:0;margin:0;border:0}legend{float:left;width:100%;padding:0;margin-bottom:.5rem;font-size:calc(1.275rem + .3vw);line-height:inherit}@media (min-width:1200px){legend{font-size:1.5rem}}legend+*{clear:left}::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-fields-wrapper,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-minute,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-text,::-webkit-datetime-edit-year-field{padding:0}::-webkit-inner-spin-button{height:auto}[type=search]{outline-offset:-2px;-webkit-appearance:textfield}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-color-swatch-wrapper{padding:0}::file-selector-button{font:inherit}::-webkit-file-upload-button{font:inherit;-webkit-appearance:button}output{display:inline-block}iframe{border:0}summary{display:list-item;cursor:pointer}progress{vertical-align:baseline}[hidden]{display:none!important}</style>
11 <style type="text/css">/*! pygments syntax highlighting */pre{line-height:125%;}td.linenos pre{color:#000000; background-color:#f0f0f0; padding-left:5px; padding-right:5px;}span.linenos{color:#000000; background-color:#f0f0f0; padding-left:5px; padding-right:5px;}td.linenos pre.special{color:#000000; background-color:#ffffc0; padding-left:5px; padding-right:5px;}span.linenos.special{color:#000000; background-color:#ffffc0; padding-left:5px; padding-right:5px;}.pdoc .hll{background-color:#ffffcc}.pdoc{background:#f8f8f8;}.pdoc .c{color:#408080; font-style:italic}.pdoc .err{border:1px solid #FF0000}.pdoc .k{color:#008000; font-weight:bold}.pdoc .o{color:#666666}.pdoc .ch{color:#408080; font-style:italic}.pdoc .cm{color:#408080; font-style:italic}.pdoc .cp{color:#BC7A00}.pdoc .cpf{color:#408080; font-style:italic}.pdoc .c1{color:#408080; font-style:italic}.pdoc .cs{color:#408080; font-style:italic}.pdoc .gd{color:#A00000}.pdoc .ge{font-style:italic}.pdoc .gr{color:#FF0000}.pdoc .gh{color:#000080; font-weight:bold}.pdoc .gi{color:#00A000}.pdoc .go{color:#888888}.pdoc .gp{color:#000080; font-weight:bold}.pdoc .gs{font-weight:bold}.pdoc .gu{color:#800080; font-weight:bold}.pdoc .gt{color:#0044DD}.pdoc .kc{color:#008000; font-weight:bold}.pdoc .kd{color:#008000; font-weight:bold}.pdoc .kn{color:#008000; font-weight:bold}.pdoc .kp{color:#008000}.pdoc .kr{color:#008000; font-weight:bold}.pdoc .kt{color:#B00040}.pdoc .m{color:#666666}.pdoc .s{color:#BA2121}.pdoc .na{color:#7D9029}.pdoc .nb{color:#008000}.pdoc .nc{color:#0000FF; font-weight:bold}.pdoc .no{color:#880000}.pdoc .nd{color:#AA22FF}.pdoc .ni{color:#999999; font-weight:bold}.pdoc .ne{color:#D2413A; font-weight:bold}.pdoc .nf{color:#0000FF}.pdoc .nl{color:#A0A000}.pdoc .nn{color:#0000FF; font-weight:bold}.pdoc .nt{color:#008000; font-weight:bold}.pdoc .nv{color:#19177C}.pdoc .ow{color:#AA22FF; font-weight:bold}.pdoc .w{color:#bbbbbb}.pdoc .mb{color:#666666}.pdoc .mf{color:#666666}.pdoc .mh{color:#666666}.pdoc .mi{color:#666666}.pdoc .mo{color:#666666}.pdoc .sa{color:#BA2121}.pdoc .sb{color:#BA2121}.pdoc .sc{color:#BA2121}.pdoc .dl{color:#BA2121}.pdoc .sd{color:#BA2121; font-style:italic}.pdoc .s2{color:#BA2121}.pdoc .se{color:#BB6622; font-weight:bold}.pdoc .sh{color:#BA2121}.pdoc .si{color:#BB6688; font-weight:bold}.pdoc .sx{color:#008000}.pdoc .sr{color:#BB6688}.pdoc .s1{color:#BA2121}.pdoc .ss{color:#19177C}.pdoc .bp{color:#008000}.pdoc .fm{color:#0000FF}.pdoc .vc{color:#19177C}.pdoc .vg{color:#19177C}.pdoc .vi{color:#19177C}.pdoc .vm{color:#19177C}.pdoc .il{color:#666666}</style>
12 <style type="text/css">/*! pdoc */:root{--pdoc-background:#fff;}.pdoc{--text:#212529;--muted:#6c757d;--link:#3660a5;--link-hover:#1659c5;--code:#f7f7f7;--active:#fff598;--accent:#eee;--accent2:#c1c1c1;--nav-hover:rgba(255, 255, 255, 0.5);--name:#0066BB;--def:#008800;--annotation:#007020;}body{background-color:var(--pdoc-background);}html, body{width:100%;height:100%;}@media (max-width:769px){#navtoggle{cursor:pointer;position:absolute;width:50px;height:40px;top:1rem;right:1rem;border-color:var(--text);color:var(--text);display:flex;opacity:0.8;}#navtoggle:hover{opacity:1;}#togglestate + div{display:none;}#togglestate:checked + div{display:inherit;}main{padding:2rem 3vw;}.git-button{display:none !important;}}@media (min-width:770px){:root{--sidebar-width:clamp(12.5rem, 28vw, 22rem);}nav{position:fixed;overflow:auto;height:100vh;width:var(--sidebar-width);}main{padding:3rem 2rem 3rem calc(var(--sidebar-width) + 3rem);width:calc(54rem + var(--sidebar-width));max-width:100%;}#navtoggle{display:none;}}#togglestate{display:none;}nav.pdoc{--pad:1.75rem;--indent:1.5rem;background-color:var(--accent);border-right:1px solid var(--accent2);box-shadow:0 0 20px rgba(50, 50, 50, .2) inset;padding:0 0 0 var(--pad);overflow-wrap:anywhere;scrollbar-width:thin; scrollbar-color:var(--accent2) transparent }nav.pdoc::-webkit-scrollbar{width:.4rem; }nav.pdoc::-webkit-scrollbar-thumb{background-color:var(--accent2); }nav.pdoc > div{padding:var(--pad) 0;}nav.pdoc .module-list-button{display:inline-flex;align-items:center;color:var(--text);border-color:var(--muted);margin-bottom:1rem;}nav.pdoc .module-list-button:hover{border-color:var(--text);}nav.pdoc ul{list-style:none;padding-left:0;}nav.pdoc li{display:block;margin:0;padding:.2rem 0 .2rem var(--indent);transition:all 100ms;}nav.pdoc > div > ul > li{padding-left:0;}nav.pdoc li:hover{background-color:var(--nav-hover);}nav.pdoc a, nav.pdoc a:hover{color:var(--text);}nav.pdoc a{display:block;}nav.pdoc > h2:first-of-type{margin-top:1.5rem;}nav.pdoc .class:before{content:"class ";color:var(--muted);}nav.pdoc .function:after{content:"()";color:var(--muted);}html, main{scroll-behavior:smooth;}.pdoc{color:var(--text);box-sizing:border-box;line-height:1.5;background:none;}.pdoc .pdoc-button{display:inline-block;border:solid black 1px;border-radius:2px;font-size:.75rem;padding:calc(0.5em - 1px) 1em;transition:100ms all;}.pdoc h1, .pdoc h2, .pdoc h3, .pdoc h4{font-weight:300;margin:.3em 0;padding:.2em 0;}.pdoc a{text-decoration:none;color:var(--link);}.pdoc a:hover{color:var(--link-hover);}.pdoc blockquote{margin-left:2rem;}.pdoc pre{background-color:var(--code);border-top:1px solid var(--accent2);border-bottom:1px solid var(--accent2);margin-bottom:1em;padding:.5rem 0 .5rem .5rem;overflow-x:auto;}.pdoc code{color:var(--text);padding:.2em .4em;margin:0;font-size:85%;background-color:var(--code);border-radius:6px;}.pdoc a > code{color:inherit;}.pdoc pre > code{display:inline-block;font-size:inherit;background:none;border:none;padding:0;}.pdoc .modulename{margin-top:0;font-weight:bold;}.pdoc .modulename a{color:var(--link);transition:100ms all;}.pdoc .git-button{float:right;border:solid var(--link) 1px;}.pdoc .git-button:hover{background-color:var(--link);color:var(--pdoc-background);}.pdoc details{--shift:-40px;text-align:right;margin-top:var(--shift);margin-bottom:calc(0px - var(--shift));clear:both;filter:opacity(1);}.pdoc details:not([open]){height:0;overflow:visible;}.pdoc details > summary{font-size:.75rem;cursor:pointer;color:var(--muted);border-width:0;padding:0 .7em;display:inline-block;display:inline list-item;user-select:none;}.pdoc details > summary:focus{outline:0;}.pdoc details > div{margin-top:calc(0px - var(--shift) / 2);text-align:left;}.pdoc .docstring{margin-bottom:1.5rem;}.pdoc > section:first-of-type > .docstring{margin-bottom:3rem;}.pdoc .docstring pre{margin-left:1em;margin-right:1em;}.pdoc h1:target,.pdoc h2:target,.pdoc h3:target,.pdoc h4:target,.pdoc h5:target,.pdoc h6:target{background-color:var(--active);box-shadow:-1rem 0 0 0 var(--active);}.pdoc div:target > .attr,.pdoc section:target > .attr,.pdoc dd:target > a{background-color:var(--active);}.pdoc .attr:hover{filter:contrast(0.95);}.pdoc .headerlink{position:absolute;width:0;margin-left:-1.5rem;line-height:1.4rem;font-size:1.5rem;font-weight:normal;transition:all 100ms ease-in-out;opacity:0;}.pdoc .attr > .headerlink{margin-left:-2.5rem;}.pdoc *:hover > .headerlink,.pdoc *:target > .attr > .headerlink{opacity:1;}.pdoc .attr{color:var(--text);margin:1rem 0 .5rem;padding:.4rem 5rem .4rem 1rem;background-color:var(--accent);}.pdoc .classattr{margin-left:2rem;}.pdoc .name{color:var(--name);font-weight:bold;}.pdoc .def{color:var(--def);font-weight:bold;}.pdoc .signature{white-space:pre-wrap;}.pdoc .annotation{color:var(--annotation);}.pdoc .inherited{margin-left:2rem;}.pdoc .inherited dt{font-weight:700;}.pdoc .inherited dt, .pdoc .inherited dd{display:inline;margin-left:0;margin-bottom:.5rem;}.pdoc .inherited dd:not(:last-child):after{content:", ";}.pdoc .inherited .class:before{content:"class ";}.pdoc .inherited .function a:after{content:"()";}.pdoc .attribution{margin-top:2rem;display:block;opacity:0.5;transition:all 200ms;filter:grayscale(100%);}.pdoc .attribution:hover{opacity:1;filter:grayscale(0%);}.pdoc .attribution img{margin-left:5px;height:35px;vertical-align:middle;width:70px;transition:all 200ms;}</style>
13 </head>
14 <body> <nav class="pdoc">
15 <label id="navtoggle" for="togglestate" class="pdoc-button"><svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'><path stroke-linecap='round' stroke="currentColor" stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/></svg></label>
16 <input id="togglestate" type="checkbox">
17 <div>
18 <a class="pdoc-button module-list-button" href="./index.html">
19 <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-box-arrow-in-left" viewBox="0 0 16 16">
20 <path fill-rule="evenodd" d="M10 3.5a.5.5 0 0 0-.5-.5h-8a.5.5 0 0 0-.5.5v9a.5.5 0 0 0 .5.5h8a.5.5 0 0 0 .5-.5v-2a.5.5 0 0 1 1 0v2A1.5 1.5 0 0 1 9.5 14h-8A1.5 1.5 0 0 1 0 12.5v-9A1.5 1.5 0 0 1 1.5 2h8A1.5 1.5 0 0 1 11 3.5v2a.5.5 0 0 1-1 0v-2z"/>
21 <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
22 </svg> &nbsp;netCDF4</a>
23
24
25 <h2>Contents</h2>
26 <ul>
27 <li><a href="#version-156">Version 1.5.6</a></li>
28 </ul></li>
29 <li><a href="#introduction">Introduction</a>
30 <ul>
31 <li><a href="#download">Download</a></li>
32 <li><a href="#requires">Requires</a></li>
33 <li><a href="#install">Install</a></li>
34 </ul></li>
35 <li><a href="#tutorial">Tutorial</a>
36 <ul>
37 <li><a href="#creatingopeningclosing-a-netcdf-file">Creating/Opening/Closing a netCDF file</a></li>
38 <li><a href="#groups-in-a-netcdf-file">Groups in a netCDF file</a></li>
39 <li><a href="#dimensions-in-a-netcdf-file">Dimensions in a netCDF file</a></li>
40 <li><a href="#variables-in-a-netcdf-file">Variables in a netCDF file</a></li>
41 <li><a href="#attributes-in-a-netcdf-file">Attributes in a netCDF file</a></li>
42 <li><a href="#writing-data-to-and-retrieving-data-from-a-netcdf-variable">Writing data to and retrieving data from a netCDF variable</a></li>
43 <li><a href="#dealing-with-time-coordinates">Dealing with time coordinates</a></li>
44 <li><a href="#reading-data-from-a-multi-file-netcdf-dataset">Reading data from a multi-file netCDF dataset</a></li>
45 <li><a href="#efficient-compression-of-netcdf-variables">Efficient compression of netCDF variables</a></li>
46 <li><a href="#beyond-homogeneous-arrays-of-a-fixed-type-compound-data-types">Beyond homogeneous arrays of a fixed type - compound data types</a></li>
47 <li><a href="#variable-length-vlen-data-types">Variable-length (vlen) data types</a></li>
48 <li><a href="#enum-data-type">Enum data type</a></li>
49 <li><a href="#parallel-io">Parallel IO</a></li>
50 <li><a href="#dealing-with-strings">Dealing with strings</a></li>
51 <li><a href="#in-memory-diskless-datasets">In-memory (diskless) Datasets</a></li>
52 </ul>
53
54
55
56 <h2>API Documentation</h2>
57 <ul class="memberlist">
58 <li>
59 <a class="class" href="#Dataset">Dataset</a>
60 <ul class="memberlist">
61 <li>
62 <a class="function" href="#Dataset.__init__">Dataset</a>
63 </li>
64 <li>
65 <a class="function" href="#Dataset.filepath">filepath</a>
66 </li>
67 <li>
68 <a class="function" href="#Dataset.close">close</a>
69 </li>
70 <li>
71 <a class="function" href="#Dataset.isopen">isopen</a>
72 </li>
73 <li>
74 <a class="function" href="#Dataset.sync">sync</a>
75 </li>
76 <li>
77 <a class="function" href="#Dataset.set_fill_on">set_fill_on</a>
78 </li>
79 <li>
80 <a class="function" href="#Dataset.set_fill_off">set_fill_off</a>
81 </li>
82 <li>
83 <a class="function" href="#Dataset.createDimension">createDimension</a>
84 </li>
85 <li>
86 <a class="function" href="#Dataset.renameDimension">renameDimension</a>
87 </li>
88 <li>
89 <a class="function" href="#Dataset.createCompoundType">createCompoundType</a>
90 </li>
91 <li>
92 <a class="function" href="#Dataset.createVLType">createVLType</a>
93 </li>
94 <li>
95 <a class="function" href="#Dataset.createEnumType">createEnumType</a>
96 </li>
97 <li>
98 <a class="function" href="#Dataset.createVariable">createVariable</a>
99 </li>
100 <li>
101 <a class="function" href="#Dataset.renameVariable">renameVariable</a>
102 </li>
103 <li>
104 <a class="function" href="#Dataset.createGroup">createGroup</a>
105 </li>
106 <li>
107 <a class="function" href="#Dataset.ncattrs">ncattrs</a>
108 </li>
109 <li>
110 <a class="function" href="#Dataset.setncattr">setncattr</a>
111 </li>
112 <li>
113 <a class="function" href="#Dataset.setncattr_string">setncattr_string</a>
114 </li>
115 <li>
116 <a class="function" href="#Dataset.setncatts">setncatts</a>
117 </li>
118 <li>
119 <a class="function" href="#Dataset.getncattr">getncattr</a>
120 </li>
121 <li>
122 <a class="function" href="#Dataset.delncattr">delncattr</a>
123 </li>
124 <li>
125 <a class="function" href="#Dataset.renameAttribute">renameAttribute</a>
126 </li>
127 <li>
128 <a class="function" href="#Dataset.renameGroup">renameGroup</a>
129 </li>
130 <li>
131 <a class="function" href="#Dataset.set_auto_chartostring">set_auto_chartostring</a>
132 </li>
133 <li>
134 <a class="function" href="#Dataset.set_auto_maskandscale">set_auto_maskandscale</a>
135 </li>
136 <li>
137 <a class="function" href="#Dataset.set_auto_mask">set_auto_mask</a>
138 </li>
139 <li>
140 <a class="function" href="#Dataset.set_auto_scale">set_auto_scale</a>
141 </li>
142 <li>
143 <a class="function" href="#Dataset.set_always_mask">set_always_mask</a>
144 </li>
145 <li>
146 <a class="function" href="#Dataset.set_ncstring_attrs">set_ncstring_attrs</a>
147 </li>
148 <li>
149 <a class="function" href="#Dataset.get_variables_by_attributes">get_variables_by_attributes</a>
150 </li>
151 <li>
152 <a class="function" href="#Dataset.fromcdl">fromcdl</a>
153 </li>
154 <li>
155 <a class="function" href="#Dataset.tocdl">tocdl</a>
156 </li>
157 <li>
158 <a class="variable" href="#Dataset.name">name</a>
159 </li>
160 <li>
161 <a class="variable" href="#Dataset.groups">groups</a>
162 </li>
163 <li>
164 <a class="variable" href="#Dataset.dimensions">dimensions</a>
165 </li>
166 <li>
167 <a class="variable" href="#Dataset.variables">variables</a>
168 </li>
169 <li>
170 <a class="variable" href="#Dataset.disk_format">disk_format</a>
171 </li>
172 <li>
173 <a class="variable" href="#Dataset.path">path</a>
174 </li>
175 <li>
176 <a class="variable" href="#Dataset.parent">parent</a>
177 </li>
178 <li>
179 <a class="variable" href="#Dataset.file_format">file_format</a>
180 </li>
181 <li>
182 <a class="variable" href="#Dataset.data_model">data_model</a>
183 </li>
184 <li>
185 <a class="variable" href="#Dataset.cmptypes">cmptypes</a>
186 </li>
187 <li>
188 <a class="variable" href="#Dataset.vltypes">vltypes</a>
189 </li>
190 <li>
191 <a class="variable" href="#Dataset.enumtypes">enumtypes</a>
192 </li>
193 <li>
194 <a class="variable" href="#Dataset.keepweakref">keepweakref</a>
195 </li>
196 </ul>
197
198 </li>
199 <li>
200 <a class="class" href="#Group">Group</a>
201 <ul class="memberlist">
202 <li>
203 <a class="function" href="#Group.__init__">Group</a>
204 </li>
205 <li>
206 <a class="function" href="#Group.close">close</a>
207 </li>
208 </ul>
209
210 </li>
211 <li>
212 <a class="class" href="#Dimension">Dimension</a>
213 <ul class="memberlist">
214 <li>
215 <a class="function" href="#Dimension.__init__">Dimension</a>
216 </li>
217 <li>
218 <a class="function" href="#Dimension.group">group</a>
219 </li>
220 <li>
221 <a class="function" href="#Dimension.isunlimited">isunlimited</a>
222 </li>
223 <li>
224 <a class="variable" href="#Dimension.name">name</a>
225 </li>
226 <li>
227 <a class="variable" href="#Dimension.size">size</a>
228 </li>
229 </ul>
230
231 </li>
232 <li>
233 <a class="class" href="#Variable">Variable</a>
234 <ul class="memberlist">
235 <li>
236 <a class="function" href="#Variable.__init__">Variable</a>
237 </li>
238 <li>
239 <a class="function" href="#Variable.group">group</a>
240 </li>
241 <li>
242 <a class="function" href="#Variable.ncattrs">ncattrs</a>
243 </li>
244 <li>
245 <a class="function" href="#Variable.setncattr">setncattr</a>
246 </li>
247 <li>
248 <a class="function" href="#Variable.setncattr_string">setncattr_string</a>
249 </li>
250 <li>
251 <a class="function" href="#Variable.setncatts">setncatts</a>
252 </li>
253 <li>
254 <a class="function" href="#Variable.getncattr">getncattr</a>
255 </li>
256 <li>
257 <a class="function" href="#Variable.delncattr">delncattr</a>
258 </li>
259 <li>
260 <a class="function" href="#Variable.filters">filters</a>
261 </li>
262 <li>
263 <a class="function" href="#Variable.endian">endian</a>
264 </li>
265 <li>
266 <a class="function" href="#Variable.chunking">chunking</a>
267 </li>
268 <li>
269 <a class="function" href="#Variable.get_var_chunk_cache">get_var_chunk_cache</a>
270 </li>
271 <li>
272 <a class="function" href="#Variable.set_var_chunk_cache">set_var_chunk_cache</a>
273 </li>
274 <li>
275 <a class="function" href="#Variable.renameAttribute">renameAttribute</a>
276 </li>
277 <li>
278 <a class="function" href="#Variable.assignValue">assignValue</a>
279 </li>
280 <li>
281 <a class="function" href="#Variable.getValue">getValue</a>
282 </li>
283 <li>
284 <a class="function" href="#Variable.set_auto_chartostring">set_auto_chartostring</a>
285 </li>
286 <li>
287 <a class="function" href="#Variable.use_nc_get_vars">use_nc_get_vars</a>
288 </li>
289 <li>
290 <a class="function" href="#Variable.set_auto_maskandscale">set_auto_maskandscale</a>
291 </li>
292 <li>
293 <a class="function" href="#Variable.set_auto_scale">set_auto_scale</a>
294 </li>
295 <li>
296 <a class="function" href="#Variable.set_auto_mask">set_auto_mask</a>
297 </li>
298 <li>
299 <a class="function" href="#Variable.set_always_mask">set_always_mask</a>
300 </li>
301 <li>
302 <a class="function" href="#Variable.set_ncstring_attrs">set_ncstring_attrs</a>
303 </li>
304 <li>
305 <a class="function" href="#Variable.set_collective">set_collective</a>
306 </li>
307 <li>
308 <a class="function" href="#Variable.get_dims">get_dims</a>
309 </li>
310 <li>
311 <a class="variable" href="#Variable.name">name</a>
312 </li>
313 <li>
314 <a class="variable" href="#Variable.datatype">datatype</a>
315 </li>
316 <li>
317 <a class="variable" href="#Variable.shape">shape</a>
318 </li>
319 <li>
320 <a class="variable" href="#Variable.size">size</a>
321 </li>
322 <li>
323 <a class="variable" href="#Variable.dimensions">dimensions</a>
324 </li>
325 <li>
326 <a class="variable" href="#Variable.ndim">ndim</a>
327 </li>
328 <li>
329 <a class="variable" href="#Variable.dtype">dtype</a>
330 </li>
331 <li>
332 <a class="variable" href="#Variable.mask">mask</a>
333 </li>
334 <li>
335 <a class="variable" href="#Variable.scale">scale</a>
336 </li>
337 <li>
338 <a class="variable" href="#Variable.always_mask">always_mask</a>
339 </li>
340 <li>
341 <a class="variable" href="#Variable.chartostring">chartostring</a>
342 </li>
343 </ul>
344
345 </li>
346 <li>
347 <a class="class" href="#CompoundType">CompoundType</a>
348 <ul class="memberlist">
349 <li>
350 <a class="function" href="#CompoundType.__init__">CompoundType</a>
351 </li>
352 <li>
353 <a class="variable" href="#CompoundType.dtype">dtype</a>
354 </li>
355 <li>
356 <a class="variable" href="#CompoundType.dtype_view">dtype_view</a>
357 </li>
358 <li>
359 <a class="variable" href="#CompoundType.name">name</a>
360 </li>
361 </ul>
362
363 </li>
364 <li>
365 <a class="class" href="#VLType">VLType</a>
366 <ul class="memberlist">
367 <li>
368 <a class="function" href="#VLType.__init__">VLType</a>
369 </li>
370 <li>
371 <a class="variable" href="#VLType.dtype">dtype</a>
372 </li>
373 <li>
374 <a class="variable" href="#VLType.name">name</a>
375 </li>
376 </ul>
377
378 </li>
379 <li>
380 <a class="class" href="#EnumType">EnumType</a>
381 <ul class="memberlist">
382 <li>
383 <a class="function" href="#EnumType.__init__">EnumType</a>
384 </li>
385 <li>
386 <a class="variable" href="#EnumType.dtype">dtype</a>
387 </li>
388 <li>
389 <a class="variable" href="#EnumType.name">name</a>
390 </li>
391 <li>
392 <a class="variable" href="#EnumType.enum_dict">enum_dict</a>
393 </li>
394 </ul>
395
396 </li>
397 <li>
398 <a class="function" href="#getlibversion">getlibversion</a>
399 </li>
400 <li>
401 <a class="function" href="#get_chunk_cache">get_chunk_cache</a>
402 </li>
403 <li>
404 <a class="function" href="#set_chunk_cache">set_chunk_cache</a>
405 </li>
406 <li>
407 <a class="function" href="#stringtoarr">stringtoarr</a>
408 </li>
409 <li>
410 <a class="function" href="#stringtochar">stringtochar</a>
411 </li>
412 <li>
413 <a class="function" href="#chartostring">chartostring</a>
414 </li>
415 <li>
416 <a class="class" href="#MFDataset">MFDataset</a>
417 <ul class="memberlist">
418 <li>
419 <a class="function" href="#MFDataset.__init__">MFDataset</a>
420 </li>
421 <li>
422 <a class="function" href="#MFDataset.ncattrs">ncattrs</a>
423 </li>
424 <li>
425 <a class="function" href="#MFDataset.close">close</a>
426 </li>
427 </ul>
428
429 </li>
430 <li>
431 <a class="class" href="#MFTime">MFTime</a>
432 <ul class="memberlist">
433 <li>
434 <a class="function" href="#MFTime.__init__">MFTime</a>
435 </li>
436 </ul>
437
438 </li>
439 </ul>
440
441
442 <a class="attribution" title="pdoc: Python API documentation generator" href="https://pdoc.dev">
443 built with <img
444 alt="pdoc"
445 src="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20role%3D%22img%22%20aria-label%3D%22pdoc%20logo%22%20width%3D%22300%22%20height%3D%22150%22%20viewBox%3D%22-1%200%2060%2030%22%3E%3Ctitle%3Epdoc%3C/title%3E%3Cpath%20d%3D%22M29.621%2021.293c-.011-.273-.214-.475-.511-.481a.5.5%200%200%200-.489.503l-.044%201.393c-.097.551-.695%201.215-1.566%201.704-.577.428-1.306.486-2.193.182-1.426-.617-2.467-1.654-3.304-2.487l-.173-.172a3.43%203.43%200%200%200-.365-.306.49.49%200%200%200-.286-.196c-1.718-1.06-4.931-1.47-7.353.191l-.219.15c-1.707%201.187-3.413%202.131-4.328%201.03-.02-.027-.49-.685-.141-1.763.233-.721.546-2.408.772-4.076.042-.09.067-.187.046-.288.166-1.347.277-2.625.241-3.351%201.378-1.008%202.271-2.586%202.271-4.362%200-.976-.272-1.935-.788-2.774-.057-.094-.122-.18-.184-.268.033-.167.052-.339.052-.516%200-1.477-1.202-2.679-2.679-2.679-.791%200-1.496.352-1.987.9a6.3%206.3%200%200%200-1.001.029c-.492-.564-1.207-.929-2.012-.929-1.477%200-2.679%201.202-2.679%202.679A2.65%202.65%200%200%200%20.97%206.554c-.383.747-.595%201.572-.595%202.41%200%202.311%201.507%204.29%203.635%205.107-.037.699-.147%202.27-.423%203.294l-.137.461c-.622%202.042-2.515%208.257%201.727%2010.643%201.614.908%203.06%201.248%204.317%201.248%202.665%200%204.492-1.524%205.322-2.401%201.476-1.559%202.886-1.854%206.491.82%201.877%201.393%203.514%201.753%204.861%201.068%202.223-1.713%202.811-3.867%203.399-6.374.077-.846.056-1.469.054-1.537zm-4.835%204.313c-.054.305-.156.586-.242.629-.034-.007-.131-.022-.307-.157-.145-.111-.314-.478-.456-.908.221.121.432.25.675.355.115.039.219.051.33.081zm-2.251-1.238c-.05.33-.158.648-.252.694-.022.001-.125-.018-.307-.157-.217-.166-.488-.906-.639-1.573.358.344.754.693%201.198%201.036zm-3.887-2.337c-.006-.116-.018-.231-.041-.342.635.145%201.189.368%201.599.625.097.231.166.481.174.642-.03.049-.055.101-.067.158-.046.013-.128.026-.298.004-.278-.037-.901-.57-1.367-1.087zm-1.127-.497c.116.306.176.625.12.71-.019.014-.117.045-.345.016-.206-.027-.604-.332-.986-.695.41-.051.816-.056%201.211-.031zm-4.535%201.535c.209.22.379.47.358.598-.006.041-.088.138-.351.234-.144.055-.539-.063-.979-.259a11.66%2011.66%200%200%200%20.972-.573zm.983-.664c.359-.237.738-.418%201.126-.554.25.237.479.548.457.694-.006.042-.087.138-.351.235-.174.064-.694-.105-1.232-.375zm-3.381%201.794c-.022.145-.061.29-.149.401-.133.166-.358.248-.69.251h-.002c-.133%200-.306-.26-.45-.621.417.091.854.07%201.291-.031zm-2.066-8.077a4.78%204.78%200%200%201-.775-.584c.172-.115.505-.254.88-.378l-.105.962zm-.331%202.302a10.32%2010.32%200%200%201-.828-.502c.202-.143.576-.328.984-.49l-.156.992zm-.45%202.157l-.701-.403c.214-.115.536-.249.891-.376a11.57%2011.57%200%200%201-.19.779zm-.181%201.716c.064.398.194.702.298.893-.194-.051-.435-.162-.736-.398.061-.119.224-.3.438-.495zM8.87%204.141c0%20.152-.123.276-.276.276s-.275-.124-.275-.276.123-.276.276-.276.275.124.275.276zm-.735-.389a1.15%201.15%200%200%200-.314.783%201.16%201.16%200%200%200%201.162%201.162c.457%200%20.842-.27%201.032-.653.026.117.042.238.042.362a1.68%201.68%200%200%201-1.679%201.679%201.68%201.68%200%200%201-1.679-1.679c0-.843.626-1.535%201.436-1.654zM5.059%205.406A1.68%201.68%200%200%201%203.38%207.085a1.68%201.68%200%200%201-1.679-1.679c0-.037.009-.072.011-.109.21.3.541.508.935.508a1.16%201.16%200%200%200%201.162-1.162%201.14%201.14%200%200%200-.474-.912c.015%200%20.03-.005.045-.005.926.001%201.679.754%201.679%201.68zM3.198%204.141c0%20.152-.123.276-.276.276s-.275-.124-.275-.276.123-.276.276-.276.275.124.275.276zM1.375%208.964c0-.52.103-1.035.288-1.52.466.394%201.06.64%201.717.64%201.144%200%202.116-.725%202.499-1.738.383%201.012%201.355%201.738%202.499%201.738.867%200%201.631-.421%202.121-1.062.307.605.478%201.267.478%201.942%200%202.486-2.153%204.51-4.801%204.51s-4.801-2.023-4.801-4.51zm24.342%2019.349c-.985.498-2.267.168-3.813-.979-3.073-2.281-5.453-3.199-7.813-.705-1.315%201.391-4.163%203.365-8.423.97-3.174-1.786-2.239-6.266-1.261-9.479l.146-.492c.276-1.02.395-2.457.444-3.268a6.11%206.11%200%200%200%201.18.115%206.01%206.01%200%200%200%202.536-.562l-.006.175c-.802.215-1.848.612-2.021%201.25-.079.295.021.601.274.837.219.203.415.364.598.501-.667.304-1.243.698-1.311%201.179-.02.144-.022.507.393.787.213.144.395.26.564.365-1.285.521-1.361.96-1.381%201.126-.018.142-.011.496.427.746l.854.489c-.473.389-.971.914-.999%201.429-.018.278.095.532.316.713.675.556%201.231.721%201.653.721.059%200%20.104-.014.158-.02.207.707.641%201.64%201.513%201.64h.013c.8-.008%201.236-.345%201.462-.626.173-.216.268-.457.325-.692.424.195.93.374%201.372.374.151%200%20.294-.021.423-.068.732-.27.944-.704.993-1.021.009-.061.003-.119.002-.179.266.086.538.147.789.147.15%200%20.294-.021.423-.069.542-.2.797-.489.914-.754.237.147.478.258.704.288.106.014.205.021.296.021.356%200%20.595-.101.767-.229.438.435%201.094.992%201.656%201.067.106.014.205.021.296.021a1.56%201.56%200%200%200%20.323-.035c.17.575.453%201.289.866%201.605.358.273.665.362.914.362a.99.99%200%200%200%20.421-.093%201.03%201.03%200%200%200%20.245-.164c.168.428.39.846.68%201.068.358.273.665.362.913.362a.99.99%200%200%200%20.421-.093c.317-.148.512-.448.639-.762.251.157.495.257.726.257.127%200%20.25-.024.37-.071.427-.17.706-.617.841-1.314.022-.015.047-.022.068-.038.067-.051.133-.104.196-.159-.443%201.486-1.107%202.761-2.086%203.257zM8.66%209.925a.5.5%200%201%200-1%200c0%20.653-.818%201.205-1.787%201.205s-1.787-.552-1.787-1.205a.5.5%200%201%200-1%200c0%201.216%201.25%202.205%202.787%202.205s2.787-.989%202.787-2.205zm4.4%2015.965l-.208.097c-2.661%201.258-4.708%201.436-6.086.527-1.542-1.017-1.88-3.19-1.844-4.198a.4.4%200%200%200-.385-.414c-.242-.029-.406.164-.414.385-.046%201.249.367%203.686%202.202%204.896.708.467%201.547.7%202.51.7%201.248%200%202.706-.392%204.362-1.174l.185-.086a.4.4%200%200%200%20.205-.527c-.089-.204-.326-.291-.527-.206zM9.547%202.292c.093.077.205.114.317.114a.5.5%200%200%200%20.318-.886L8.817.397a.5.5%200%200%200-.703.068.5.5%200%200%200%20.069.703l1.364%201.124zm-7.661-.065c.086%200%20.173-.022.253-.068l1.523-.893a.5.5%200%200%200-.506-.863l-1.523.892a.5.5%200%200%200-.179.685c.094.158.261.247.432.247z%22%20transform%3D%22matrix%28-1%200%200%201%2058%200%29%22%20fill%3D%22%233bb300%22/%3E%3Cpath%20d%3D%22M.3%2021.86V10.18q0-.46.02-.68.04-.22.18-.5.28-.54%201.34-.54%201.06%200%201.42.28.38.26.44.78.76-1.04%202.38-1.04%201.64%200%203.1%201.54%201.46%201.54%201.46%203.58%200%202.04-1.46%203.58-1.44%201.54-3.08%201.54-1.64%200-2.38-.92v4.04q0%20.46-.04.68-.02.22-.18.5-.14.3-.5.42-.36.12-.98.12-.62%200-1-.12-.36-.12-.52-.4-.14-.28-.18-.5-.02-.22-.02-.68zm3.96-9.42q-.46.54-.46%201.18%200%20.64.46%201.18.48.52%201.2.52.74%200%201.24-.52.52-.52.52-1.18%200-.66-.48-1.18-.48-.54-1.26-.54-.76%200-1.22.54zm14.741-8.36q.16-.3.54-.42.38-.12%201-.12.64%200%201.02.12.38.12.52.42.16.3.18.54.04.22.04.68v11.94q0%20.46-.04.7-.02.22-.18.5-.3.54-1.7.54-1.38%200-1.54-.98-.84.96-2.34.96-1.8%200-3.28-1.56-1.48-1.58-1.48-3.66%200-2.1%201.48-3.68%201.5-1.58%203.28-1.58%201.48%200%202.3%201v-4.2q0-.46.02-.68.04-.24.18-.52zm-3.24%2010.86q.52.54%201.26.54.74%200%201.22-.54.5-.54.5-1.18%200-.66-.48-1.22-.46-.56-1.26-.56-.8%200-1.28.56-.48.54-.48%201.2%200%20.66.52%201.2zm7.833-1.2q0-2.4%201.68-3.96%201.68-1.56%203.84-1.56%202.16%200%203.82%201.56%201.66%201.54%201.66%203.94%200%201.66-.86%202.96-.86%201.28-2.1%201.9-1.22.6-2.54.6-1.32%200-2.56-.64-1.24-.66-2.1-1.92-.84-1.28-.84-2.88zm4.18%201.44q.64.48%201.3.48.66%200%201.32-.5.66-.5.66-1.48%200-.98-.62-1.46-.62-.48-1.34-.48-.72%200-1.34.5-.62.5-.62%201.48%200%20.96.64%201.46zm11.412-1.44q0%20.84.56%201.32.56.46%201.18.46.64%200%201.18-.36.56-.38.9-.38.6%200%201.46%201.06.46.58.46%201.04%200%20.76-1.1%201.42-1.14.8-2.8.8-1.86%200-3.58-1.34-.82-.64-1.34-1.7-.52-1.08-.52-2.36%200-1.3.52-2.34.52-1.06%201.34-1.7%201.66-1.32%203.54-1.32.76%200%201.48.22.72.2%201.06.4l.32.2q.36.24.56.38.52.4.52.92%200%20.5-.42%201.14-.72%201.1-1.38%201.1-.38%200-1.08-.44-.36-.34-1.04-.34-.66%200-1.24.48-.58.48-.58%201.34z%22%20fill%3D%22green%22/%3E%3C/svg%3E"/>
446 </a>
447 </div>
448 </nav>
449 <main class="pdoc">
450 <section>
451 <h1 class="modulename">
452 <a href="./index.html">netCDF4</a>._netCDF4 </h1>
453
454 <div class="docstring"><h2 id="version-156">Version 1.5.6</h2>
455
456 <h1 id="introduction">Introduction</h1>
457
458 <p>netcdf4-python is a Python interface to the netCDF C library.</p>
459
460 <p><a href="http://www.unidata.ucar.edu/software/netcdf/">netCDF</a> version 4 has many features
461 not found in earlier versions of the library and is implemented on top of
462 <a href="http://www.hdfgroup.org/HDF5">HDF5</a>. This module can read and write
463 files in both the new netCDF 4 and the old netCDF 3 format, and can create
464 files that are readable by HDF5 clients. The API modelled after
465 <a href="http://dirac.cnrs-orleans.fr/ScientificPython/">Scientific.IO.NetCDF</a>,
466 and should be familiar to users of that module.</p>
467
468 <p>Most new features of netCDF 4 are implemented, such as multiple
469 unlimited dimensions, groups and zlib data compression. All the new
470 numeric data types (such as 64 bit and unsigned integer types) are
471 implemented. Compound (struct), variable length (vlen) and
472 enumerated (enum) data types are supported, but not the opaque data type.
473 Mixtures of compound, vlen and enum data types (such as
474 compound types containing enums, or vlens containing compound
475 types) are not supported.</p>
476
477 <h2 id="download">Download</h2>
478
479 <ul>
480 <li>Latest bleeding-edge code from the
481 <a href="http://github.com/Unidata/netcdf4-python">github repository</a>.</li>
482 <li>Latest <a href="https://pypi.python.org/pypi/netCDF4">releases</a>
483 (source code and binary installers).</li>
484 </ul>
485
486 <h2 id="requires">Requires</h2>
487
488 <ul>
489 <li>Python 3.6 or later.</li>
490 <li><a href="http://numpy.scipy.org">numpy array module</a>, version 1.10.0 or later.</li>
491 <li><a href="http://cython.org">Cython</a>, version 0.21 or later.</li>
492 <li><a href="https://pypi.python.org/pypi/setuptools">setuptools</a>, version 18.0 or
493 later.</li>
494 <li>The HDF5 C library version 1.8.4-patch1 or higher
495 from <a href="ftp://ftp.hdfgroup.org/HDF5/current/src"></a>.
496 <strong><em>netCDF version 4.4.1 or higher is recommended if using HDF5 1.10.x -
497 otherwise resulting files may be unreadable by clients using earlier
498 versions of HDF5. For netCDF &lt; 4.4.1, HDF5 version 1.8.x is recommended.</em></strong>
499 Be sure to build with <code>--enable-hl --enable-shared</code>.</li>
500 <li><a href="http://curl.haxx.se/libcurl">Libcurl</a>, if you want
501 <a href="http://opendap.org">OPeNDAP</a> support.</li>
502 <li><a href="http://www.hdfgroup.org/products/hdf4">HDF4</a>, if you want
503 to be able to read HDF4 "Scientific Dataset" (SD) files.</li>
504 <li>The netCDF-4 C library from the <a href="https://github.com/Unidata/netcdf-c/releases">github releases
505 page</a>.
506 Version 4.1.1 or higher is required (4.2 or higher recommended).
507 Be sure to build with <code>--enable-netcdf-4 --enable-shared</code>, and set
508 <code>CPPFLAGS="-I $HDF5_DIR/include"</code> and <code>LDFLAGS="-L $HDF5_DIR/lib"</code>,
509 where <code>$HDF5_DIR</code> is the directory where HDF5 was installed.
510 If you want <a href="http://opendap.org">OPeNDAP</a> support, add <code>--enable-dap</code>.
511 If you want HDF4 SD support, add <code>--enable-hdf4</code> and add
512 the location of the HDF4 headers and library to <code>$CPPFLAGS</code> and <code>$LDFLAGS</code>.</li>
513 <li>for MPI parallel IO support, an MPI-enabled versions of the netcdf library
514 is required, as is the <a href="http://mpi4py.scipy.org">mpi4py</a> python module.
515 Parallel IO further depends on the existence of MPI-enabled HDF5 or the
516 <a href="https://parallel-netcdf.github.io/">PnetCDF</a> library.</li>
517 <li><a href="https://github.com/Unidata/cftime">cftime</a> for
518 time and date handling utility functions.</li>
519 </ul>
520
521 <h2 id="install">Install</h2>
522
523 <ul>
524 <li>install the requisite python modules and C libraries (see above). It's
525 easiest if all the C libs are built as shared libraries.</li>
526 <li>By default, the utility <code>nc-config</code>, installed with netcdf 4.1.2 or higher,
527 will be run used to determine where all the dependencies live.</li>
528 <li>If <code>nc-config</code> is not in your default <code>PATH</code>, you can set the <code>NETCDF4_DIR</code>
529 environment variable and <code>setup.py</code> will look in <code>$NETCDF4_DIR/bin</code>.
530 You can also use the file <code>setup.cfg</code> to set the path to <code>nc-config</code>, or
531 enter the paths to the libraries and include files manually. Just edit the <code>setup.cfg</code> file
532 in a text editor and follow the instructions in the comments.
533 To disable the use of <code>nc-config</code>, set the env var <code>USE_NCCONFIG</code> to 0.
534 To disable the use of <code>setup.cfg</code>, set <code>USE_SETUPCFG</code> to 0.
535 As a last resort, the library and include paths can be set via environment variables.
536 If you go this route, set <code>USE_NCCONFIG</code> and <code>USE_SETUPCFG</code> to 0, and specify
537 <code>NETCDF4_LIBDIR</code>, <code>NETCDF4_INCDIR</code>, <code>HDF5_LIBDIR</code> and <code>HDF5_INCDIR</code>.
538 Similarly, environment variables
539 (all capitalized) can be used to set the include and library paths for
540 <code>hdf4</code>, <code>szip</code>, <code>jpeg</code>, <code>curl</code> and <code>zlib</code>. If the dependencies are not found
541 in any of the paths specified by environment variables, then standard locations
542 (such as <code>/usr</code> and <code>/usr/local</code>) are searched.</li>
543 <li>run <code>python setup.py build</code>, then <code>python setup.py install</code> (as root if
544 necessary). <code>pip install</code> can be used to install pre-compiled binary wheels from
545 <a href="https://pypi.org/project/netCDF4">pypi</a>.</li>
546 <li>run the tests in the 'test' directory by running <code>python run_all.py</code>.</li>
547 </ul>
548
549 <h1 id="tutorial">Tutorial</h1>
550
551 <ul>
552 <li><a href="#creatingopeningclosing-a-netcdf-file">Creating/Opening/Closing a netCDF file</a></li>
553 <li><a href="#groups-in-a-netcdf-file">Groups in a netCDF file</a></li>
554 <li><a href="#dimensions-in-a-netcdf-file">Dimensions in a netCDF file</a></li>
555 <li><a href="#variables-in-a-netcdf-file">Variables in a netCDF file</a></li>
556 <li><a href="#attributes-in-a-netcdf-file">Attributes in a netCDF file</a></li>
557 <li><a href="#dealing-with-time-coordinates">Dealing with time coordinates</a></li>
558 <li><a href="#writing-data-to-and-retrieving-data-from-a-netcdf-variable">Writing data to and retrieving data from a netCDF variable</a></li>
559 <li><a href="#reading-data-from-a-multi-file-netcdf-dataset">Reading data from a multi-file netCDF dataset</a></li>
560 <li><a href="#efficient-compression-of-netcdf-variables">Efficient compression of netCDF variables</a></li>
561 <li><a href="#beyond-homogeneous-arrays-of-a-fixed-type-compound-data-types">Beyond homogeneous arrays of a fixed type - compound data types</a></li>
562 <li><a href="#variable-length-vlen-data-types">Variable-length (vlen) data types</a></li>
563 <li><a href="#enum-data-type">Enum data type</a></li>
564 <li><a href="#parallel-io">Parallel IO</a></li>
565 <li><a href="#dealing-with-strings">Dealing with strings</a></li>
566 <li><a href="#in-memory-diskless-datasets">In-memory (diskless) Datasets</a></li>
567 </ul>
568
569 <h2 id="creatingopeningclosing-a-netcdf-file">Creating/Opening/Closing a netCDF file</h2>
570
571 <p>To create a netCDF file from python, you simply call the <a href="#Dataset">Dataset</a>
572 constructor. This is also the method used to open an existing netCDF
573 file. If the file is open for write access (<code>mode='w', 'r+'</code> or <code>'a'</code>), you may
574 write any type of data including new dimensions, groups, variables and
575 attributes. netCDF files come in five flavors (<code>NETCDF3_CLASSIC,
576 NETCDF3_64BIT_OFFSET, NETCDF3_64BIT_DATA, NETCDF4_CLASSIC</code>, and <code>NETCDF4</code>).
577 <code>NETCDF3_CLASSIC</code> was the original netcdf binary format, and was limited
578 to file sizes less than 2 Gb. <code>NETCDF3_64BIT_OFFSET</code> was introduced
579 in version 3.6.0 of the library, and extended the original binary format
580 to allow for file sizes greater than 2 Gb.
581 <code>NETCDF3_64BIT_DATA</code> is a new format that requires version 4.4.0 of
582 the C library - it extends the <code>NETCDF3_64BIT_OFFSET</code> binary format to
583 allow for unsigned/64 bit integer data types and 64-bit dimension sizes.
584 <code>NETCDF3_64BIT</code> is an alias for <code>NETCDF3_64BIT_OFFSET</code>.
585 <code>NETCDF4_CLASSIC</code> files use the version 4 disk format (HDF5), but omits features
586 not found in the version 3 API. They can be read by netCDF 3 clients
587 only if they have been relinked against the netCDF 4 library. They can
588 also be read by HDF5 clients. <code>NETCDF4</code> files use the version 4 disk
589 format (HDF5) and use the new features of the version 4 API. The
590 netCDF4 module can read and write files in any of these formats. When
591 creating a new file, the format may be specified using the <code>format</code>
592 keyword in the <code><a href="#Dataset">Dataset</a></code> constructor. The default format is
593 <code>NETCDF4</code>. To see how a given file is formatted, you can examine the
594 <code>data_model</code> attribute. Closing the netCDF file is
595 accomplished via the <a href="#<a href="#Dataset.close">Dataset.close</a>"><a href="#Dataset.close">Dataset.close</a></a> method of the <a href="#Dataset">Dataset</a>
596 instance.</p>
597
598 <p>Here's an example:</p>
599
600 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">Dataset</span>
601 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;test.nc&quot;</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s2">&quot;NETCDF4&quot;</span><span class="p">)</span>
602 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">data_model</span><span class="p">)</span>
603 <span class="n">NETCDF4</span>
604 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
605 </code></pre></div>
606
607 <p>Remote <a href="http://opendap.org">OPeNDAP</a>-hosted datasets can be accessed for
608 reading over http if a URL is provided to the <a href="#Dataset">Dataset</a> constructor instead of a
609 filename. However, this requires that the netCDF library be built with
610 OPenDAP support, via the <code>--enable-dap</code> configure option (added in
611 version 4.0.1).</p>
612
613 <h2 id="groups-in-a-netcdf-file">Groups in a netCDF file</h2>
614
615 <p>netCDF version 4 added support for organizing data in hierarchical
616 groups, which are analogous to directories in a filesystem. Groups serve
617 as containers for variables, dimensions and attributes, as well as other
618 groups. A <a href="#Dataset">Dataset</a> creates a special group, called
619 the 'root group', which is similar to the root directory in a unix
620 filesystem. To create <a href="#Group">Group</a> instances, use the
621 <a href="#<a href="#Dataset.createGroup">Dataset.createGroup</a>"><a href="#Dataset.createGroup">Dataset.createGroup</a></a> method of a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a>
622 instance. <a href="#<a href="#Dataset.createGroup">Dataset.createGroup</a>"><a href="#Dataset.createGroup">Dataset.createGroup</a></a> takes a single argument, a
623 python string containing the name of the new group. The new <a href="#Group">Group</a>
624 instances contained within the root group can be accessed by name using
625 the <code>groups</code> dictionary attribute of the <a href="#Dataset">Dataset</a> instance. Only
626 <code>NETCDF4</code> formatted files support Groups, if you try to create a Group
627 in a netCDF 3 file you will get an error message.</p>
628
629 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;test.nc&quot;</span><span class="p">,</span> <span class="s2">&quot;a&quot;</span><span class="p">)</span>
630 <span class="o">&gt;&gt;&gt;</span> <span class="n">fcstgrp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createGroup</span><span class="p">(</span><span class="s2">&quot;forecasts&quot;</span><span class="p">)</span>
631 <span class="o">&gt;&gt;&gt;</span> <span class="n">analgrp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createGroup</span><span class="p">(</span><span class="s2">&quot;analyses&quot;</span><span class="p">)</span>
632 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">groups</span><span class="p">)</span>
633 <span class="p">{</span><span class="s1">&#39;forecasts&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
634 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="p">:</span>
635 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
636 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
637 <span class="n">groups</span><span class="p">:</span> <span class="p">,</span> <span class="s1">&#39;analyses&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
638 <span class="n">group</span> <span class="o">/</span><span class="n">analyses</span><span class="p">:</span>
639 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
640 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
641 <span class="n">groups</span><span class="p">:</span> <span class="p">}</span>
642 <span class="o">&gt;&gt;&gt;</span>
643 </code></pre></div>
644
645 <p>Groups can exist within groups in a <a href="#Dataset">Dataset</a>, just as directories
646 exist within directories in a unix filesystem. Each <a href="#Group">Group</a> instance
647 has a <code>groups</code> attribute dictionary containing all of the group
648 instances contained within that group. Each <a href="#Group">Group</a> instance also has a
649 <code>path</code> attribute that contains a simulated unix directory path to
650 that group. To simplify the creation of nested groups, you can
651 use a unix-like path as an argument to <a href="#<a href="#Dataset.createGroup">Dataset.createGroup</a>"><a href="#Dataset.createGroup">Dataset.createGroup</a></a>.</p>
652
653 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">fcstgrp1</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createGroup</span><span class="p">(</span><span class="s2">&quot;/forecasts/model1&quot;</span><span class="p">)</span>
654 <span class="o">&gt;&gt;&gt;</span> <span class="n">fcstgrp2</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createGroup</span><span class="p">(</span><span class="s2">&quot;/forecasts/model2&quot;</span><span class="p">)</span>
655 </code></pre></div>
656
657 <p>If any of the intermediate elements of the path do not exist, they are created,
658 just as with the unix command <code>'mkdir -p'</code>. If you try to create a group
659 that already exists, no error will be raised, and the existing group will be
660 returned.</p>
661
662 <p>Here's an example that shows how to navigate all the groups in a
663 <a href="#Dataset">Dataset</a>. The function <code>walktree</code> is a Python generator that is used
664 to walk the directory tree. Note that printing the <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a>
665 object yields summary information about it's contents.</p>
666
667 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="k">def</span> <span class="nf">walktree</span><span class="p">(</span><span class="n">top</span><span class="p">):</span>
668 <span class="o">...</span> <span class="n">values</span> <span class="o">=</span> <span class="n">top</span><span class="o">.</span><span class="n">groups</span><span class="o">.</span><span class="n">values</span><span class="p">()</span>
669 <span class="o">...</span> <span class="k">yield</span> <span class="n">values</span>
670 <span class="o">...</span> <span class="k">for</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">top</span><span class="o">.</span><span class="n">groups</span><span class="o">.</span><span class="n">values</span><span class="p">():</span>
671 <span class="o">...</span> <span class="k">for</span> <span class="n">children</span> <span class="ow">in</span> <span class="n">walktree</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
672 <span class="o">...</span> <span class="k">yield</span> <span class="n">children</span>
673 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">)</span>
674 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
675 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
676 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
677 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
678 <span class="n">groups</span><span class="p">:</span> <span class="n">forecasts</span><span class="p">,</span> <span class="n">analyses</span>
679 <span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">children</span> <span class="ow">in</span> <span class="n">walktree</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">):</span>
680 <span class="o">...</span> <span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">children</span><span class="p">:</span>
681 <span class="o">...</span> <span class="nb">print</span><span class="p">(</span><span class="n">child</span><span class="p">)</span>
682 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
683 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="p">:</span>
684 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
685 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
686 <span class="n">groups</span><span class="p">:</span> <span class="n">model1</span><span class="p">,</span> <span class="n">model2</span>
687 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
688 <span class="n">group</span> <span class="o">/</span><span class="n">analyses</span><span class="p">:</span>
689 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
690 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
691 <span class="n">groups</span><span class="p">:</span>
692 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
693 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="o">/</span><span class="n">model1</span><span class="p">:</span>
694 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
695 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
696 <span class="n">groups</span><span class="p">:</span>
697 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
698 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="o">/</span><span class="n">model2</span><span class="p">:</span>
699 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
700 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
701 <span class="n">groups</span><span class="p">:</span>
702 </code></pre></div>
703
704 <h2 id="dimensions-in-a-netcdf-file">Dimensions in a netCDF file</h2>
705
706 <p>netCDF defines the sizes of all variables in terms of dimensions, so
707 before any variables can be created the dimensions they use must be
708 created first. A special case, not often used in practice, is that of a
709 scalar variable, which has no dimensions. A dimension is created using
710 the <a href="#<a href="#Dataset.createDimension">Dataset.createDimension</a>"><a href="#Dataset.createDimension">Dataset.createDimension</a></a> method of a <a href="#Dataset">Dataset</a>
711 or <a href="#Group">Group</a> instance. A Python string is used to set the name of the
712 dimension, and an integer value is used to set the size. To create an
713 unlimited dimension (a dimension that can be appended to), the size
714 value is set to <code>None</code> or 0. In this example, there both the <code>time</code> and
715 <code>level</code> dimensions are unlimited. Having more than one unlimited
716 dimension is a new netCDF 4 feature, in netCDF 3 files there may be only
717 one, and it must be the first (leftmost) dimension of the variable.</p>
718
719 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">level</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;level&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
720 <span class="o">&gt;&gt;&gt;</span> <span class="n">time</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
721 <span class="o">&gt;&gt;&gt;</span> <span class="n">lat</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span> <span class="mi">73</span><span class="p">)</span>
722 <span class="o">&gt;&gt;&gt;</span> <span class="n">lon</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;lon&quot;</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
723 </code></pre></div>
724
725 <p>All of the <a href="#Dimension">Dimension</a> instances are stored in a python dictionary.</p>
726
727 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">dimensions</span><span class="p">)</span>
728 <span class="p">{</span><span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt; (unlimited): name = &#39;</span><span class="n">level</span><span class="s1">&#39;, size = 0, &#39;</span><span class="n">time</span><span class="s1">&#39;: &lt;class &#39;</span><span class="n">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt; (unlimited): name = &#39;</span><span class="n">time</span><span class="s1">&#39;, size = 0, &#39;</span><span class="n">lat</span><span class="s1">&#39;: &lt;class &#39;</span><span class="n">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">lat</span><span class="s1">&#39;, size = 73, &#39;</span><span class="n">lon</span><span class="s1">&#39;: &lt;class &#39;</span><span class="n">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">lon</span><span class="s1">&#39;, size = 144}</span>
729 </code></pre></div>
730
731 <p>Using the python <code>len</code> function with a <a href="#Dimension">Dimension</a> instance returns
732 current size of that dimension.
733 <a href="#<a href="#Dimension.isunlimited">Dimension.isunlimited</a>"><a href="#Dimension.isunlimited">Dimension.isunlimited</a></a> method of a <a href="#Dimension">Dimension</a> instance
734 be used to determine if the dimensions is unlimited, or appendable.</p>
735
736 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">lon</span><span class="p">))</span>
737 <span class="mi">144</span>
738 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">lon</span><span class="o">.</span><span class="n">isunlimited</span><span class="p">())</span>
739 <span class="kc">False</span>
740 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">isunlimited</span><span class="p">())</span>
741 <span class="kc">True</span>
742 </code></pre></div>
743
744 <p>Printing the <a href="#Dimension">Dimension</a> object
745 provides useful summary info, including the name and length of the dimension,
746 and whether it is unlimited.</p>
747
748 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">dimobj</span> <span class="ow">in</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">dimensions</span><span class="o">.</span><span class="n">values</span><span class="p">():</span>
749 <span class="o">...</span> <span class="nb">print</span><span class="p">(</span><span class="n">dimobj</span><span class="p">)</span>
750 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt; (unlimited): name = &#39;</span><span class="n">level</span><span class="s1">&#39;, size = 0</span>
751 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt; (unlimited): name = &#39;</span><span class="n">time</span><span class="s1">&#39;, size = 0</span>
752 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">lat</span><span class="s1">&#39;, size = 73</span>
753 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">lon</span><span class="s1">&#39;, size = 144</span>
754 </code></pre></div>
755
756 <p><a href="#Dimension">Dimension</a> names can be changed using the
757 <a href="#Datatset.renameDimension">Datatset.renameDimension</a> method of a <a href="#Dataset">Dataset</a> or
758 <a href="#Group">Group</a> instance.</p>
759
760 <h2 id="variables-in-a-netcdf-file">Variables in a netCDF file</h2>
761
762 <p>netCDF variables behave much like python multidimensional array objects
763 supplied by the <a href="http://numpy.scipy.org">numpy module</a>. However,
764 unlike numpy arrays, netCDF4 variables can be appended to along one or
765 more 'unlimited' dimensions. To create a netCDF variable, use the
766 <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> method of a <a href="#Dataset">Dataset</a> or
767 <a href="#Group">Group</a> instance. The <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> method
768 has two mandatory arguments, the variable name (a Python string), and
769 the variable datatype. The variable's dimensions are given by a tuple
770 containing the dimension names (defined previously with
771 <a href="#<a href="#Dataset.createDimension">Dataset.createDimension</a>"><a href="#Dataset.createDimension">Dataset.createDimension</a></a>). To create a scalar
772 variable, simply leave out the dimensions keyword. The variable
773 primitive datatypes correspond to the dtype attribute of a numpy array.
774 You can specify the datatype as a numpy dtype object, or anything that
775 can be converted to a numpy dtype object. Valid datatype specifiers
776 include: <code>'f4'</code> (32-bit floating point), <code>'f8'</code> (64-bit floating
777 point), <code>'i4'</code> (32-bit signed integer), <code>'i2'</code> (16-bit signed
778 integer), <code>'i8'</code> (64-bit signed integer), <code>'i1'</code> (8-bit signed
779 integer), <code>'u1'</code> (8-bit unsigned integer), <code>'u2'</code> (16-bit unsigned
780 integer), <code>'u4'</code> (32-bit unsigned integer), <code>'u8'</code> (64-bit unsigned
781 integer), or <code>'S1'</code> (single-character string). The old Numeric
782 single-character typecodes (<code>'f'</code>,<code>'d'</code>,<code>'h'</code>,
783 <code>'s'</code>,<code>'b'</code>,<code>'B'</code>,<code>'c'</code>,<code>'i'</code>,<code>'l'</code>), corresponding to
784 (<code>'f4'</code>,<code>'f8'</code>,<code>'i2'</code>,<code>'i2'</code>,<code>'i1'</code>,<code>'i1'</code>,<code>'S1'</code>,<code>'i4'</code>,<code>'i4'</code>),
785 will also work. The unsigned integer types and the 64-bit integer type
786 can only be used if the file format is <code>NETCDF4</code>.</p>
787
788 <p>The dimensions themselves are usually also defined as variables, called
789 coordinate variables. The <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a>
790 method returns an instance of the <a href="#Variable">Variable</a> class whose methods can be
791 used later to access and set variable data and attributes.</p>
792
793 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">times</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;f8&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,))</span>
794 <span class="o">&gt;&gt;&gt;</span> <span class="n">levels</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;i4&quot;</span><span class="p">,(</span><span class="s2">&quot;level&quot;</span><span class="p">,))</span>
795 <span class="o">&gt;&gt;&gt;</span> <span class="n">latitudes</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;lat&quot;</span><span class="p">,))</span>
796 <span class="o">&gt;&gt;&gt;</span> <span class="n">longitudes</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;lon&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;lon&quot;</span><span class="p">,))</span>
797 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># two dimensions unlimited</span>
798 <span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,))</span>
799 <span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;K&quot;</span>
800 </code></pre></div>
801
802 <p>To get summary info on a <a href="#Variable">Variable</a> instance in an interactive session,
803 just print it.</p>
804
805 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">temp</span><span class="p">)</span>
806 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
807 <span class="n">float32</span> <span class="n">temp</span><span class="p">(</span><span class="n">time</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">lat</span><span class="p">,</span> <span class="n">lon</span><span class="p">)</span>
808 <span class="n">units</span><span class="p">:</span> <span class="n">K</span>
809 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span><span class="p">,</span> <span class="n">level</span>
810 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
811 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span>
812 </code></pre></div>
813
814 <p>You can use a path to create a Variable inside a hierarchy of groups.</p>
815
816 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">ftemp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;/forecasts/model1/temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,))</span>
817 </code></pre></div>
818
819 <p>If the intermediate groups do not yet exist, they will be created.</p>
820
821 <p>You can also query a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance directly to obtain <a href="#Group">Group</a> or
822 <a href="#Variable">Variable</a> instances using paths.</p>
823
824 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">[</span><span class="s2">&quot;/forecasts/model1&quot;</span><span class="p">])</span> <span class="c1"># a Group instance</span>
825 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
826 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="o">/</span><span class="n">model1</span><span class="p">:</span>
827 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
828 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">float32</span> <span class="n">temp</span><span class="p">(</span><span class="n">time</span><span class="p">,</span><span class="n">level</span><span class="p">,</span><span class="n">lat</span><span class="p">,</span><span class="n">lon</span><span class="p">)</span>
829 <span class="n">groups</span><span class="p">:</span>
830 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">[</span><span class="s2">&quot;/forecasts/model1/temp&quot;</span><span class="p">])</span> <span class="c1"># a Variable instance</span>
831 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
832 <span class="n">float32</span> <span class="n">temp</span><span class="p">(</span><span class="n">time</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">lat</span><span class="p">,</span> <span class="n">lon</span><span class="p">)</span>
833 <span class="n">path</span> <span class="o">=</span> <span class="o">/</span><span class="n">forecasts</span><span class="o">/</span><span class="n">model1</span>
834 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span><span class="p">,</span> <span class="n">level</span>
835 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
836 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span>
837 </code></pre></div>
838
839 <p>All of the variables in the <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> are stored in a
840 Python dictionary, in the same way as the dimensions:</p>
841
842 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">variables</span><span class="p">)</span>
843 <span class="p">{</span><span class="s1">&#39;time&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
844 <span class="n">float64</span> <span class="n">time</span><span class="p">(</span><span class="n">time</span><span class="p">)</span>
845 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span>
846 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,)</span>
847 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span><span class="p">,</span> <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
848 <span class="n">int32</span> <span class="n">level</span><span class="p">(</span><span class="n">level</span><span class="p">)</span>
849 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">level</span>
850 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,)</span>
851 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="o">-</span><span class="mi">2147483647</span> <span class="n">used</span><span class="p">,</span> <span class="s1">&#39;lat&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
852 <span class="n">float32</span> <span class="n">lat</span><span class="p">(</span><span class="n">lat</span><span class="p">)</span>
853 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span>
854 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">73</span><span class="p">,)</span>
855 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span><span class="p">,</span> <span class="s1">&#39;lon&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
856 <span class="n">float32</span> <span class="n">lon</span><span class="p">(</span><span class="n">lon</span><span class="p">)</span>
857 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span>
858 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">144</span><span class="p">,)</span>
859 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span><span class="p">,</span> <span class="s1">&#39;temp&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
860 <span class="n">float32</span> <span class="n">temp</span><span class="p">(</span><span class="n">time</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">lat</span><span class="p">,</span> <span class="n">lon</span><span class="p">)</span>
861 <span class="n">units</span><span class="p">:</span> <span class="n">K</span>
862 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span><span class="p">,</span> <span class="n">level</span>
863 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
864 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span><span class="p">}</span>
865 </code></pre></div>
866
867 <p><a href="#Variable">Variable</a> names can be changed using the
868 <a href="#<a href="#Dataset.renameVariable">Dataset.renameVariable</a>"><a href="#Dataset.renameVariable">Dataset.renameVariable</a></a> method of a <a href="#Dataset">Dataset</a>
869 instance.</p>
870
871 <p>Variables can be sliced similar to numpy arrays, but there are some differences. See
872 <a href="#writing-data-to-and-retrieving-data-from-a-netcdf-variable">Writing data to and retrieving data from a netCDF variable</a> for more details.</p>
873
874 <h2 id="attributes-in-a-netcdf-file">Attributes in a netCDF file</h2>
875
876 <p>There are two types of attributes in a netCDF file, global and variable.
877 Global attributes provide information about a group, or the entire
878 dataset, as a whole. <a href="#Variable">Variable</a> attributes provide information about
879 one of the variables in a group. Global attributes are set by assigning
880 values to <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance variables. <a href="#Variable">Variable</a>
881 attributes are set by assigning values to <a href="#Variable">Variable</a> instances
882 variables. Attributes can be strings, numbers or sequences. Returning to
883 our example,</p>
884
885 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">time</span>
886 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">description</span> <span class="o">=</span> <span class="s2">&quot;bogus example script&quot;</span>
887 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">history</span> <span class="o">=</span> <span class="s2">&quot;Created &quot;</span> <span class="o">+</span> <span class="n">time</span><span class="o">.</span><span class="n">ctime</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">())</span>
888 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">source</span> <span class="o">=</span> <span class="s2">&quot;netCDF4 python module tutorial&quot;</span>
889 <span class="o">&gt;&gt;&gt;</span> <span class="n">latitudes</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;degrees north&quot;</span>
890 <span class="o">&gt;&gt;&gt;</span> <span class="n">longitudes</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;degrees east&quot;</span>
891 <span class="o">&gt;&gt;&gt;</span> <span class="n">levels</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;hPa&quot;</span>
892 <span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;K&quot;</span>
893 <span class="o">&gt;&gt;&gt;</span> <span class="n">times</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;hours since 0001-01-01 00:00:00.0&quot;</span>
894 <span class="o">&gt;&gt;&gt;</span> <span class="n">times</span><span class="o">.</span><span class="n">calendar</span> <span class="o">=</span> <span class="s2">&quot;gregorian&quot;</span>
895 </code></pre></div>
896
897 <p>The <a href="#<a href="#Dataset.ncattrs">Dataset.ncattrs</a>"><a href="#Dataset.ncattrs">Dataset.ncattrs</a></a> method of a <a href="#Dataset">Dataset</a>, <a href="#Group">Group</a> or
898 <a href="#Variable">Variable</a> instance can be used to retrieve the names of all the netCDF
899 attributes. This method is provided as a convenience, since using the
900 built-in <code>dir</code> Python function will return a bunch of private methods
901 and attributes that cannot (or should not) be modified by the user.</p>
902
903 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">ncattrs</span><span class="p">():</span>
904 <span class="o">...</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Global attr </span><span class="si">{}</span><span class="s2"> = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">,</span> <span class="n">name</span><span class="p">)))</span>
905 <span class="n">Global</span> <span class="n">attr</span> <span class="n">description</span> <span class="o">=</span> <span class="n">bogus</span> <span class="n">example</span> <span class="n">script</span>
906 <span class="n">Global</span> <span class="n">attr</span> <span class="n">history</span> <span class="o">=</span> <span class="n">Created</span> <span class="n">Mon</span> <span class="n">Jul</span> <span class="mi">8</span> <span class="mi">14</span><span class="p">:</span><span class="mi">19</span><span class="p">:</span><span class="mi">41</span> <span class="mi">2019</span>
907 <span class="n">Global</span> <span class="n">attr</span> <span class="n">source</span> <span class="o">=</span> <span class="n">netCDF4</span> <span class="n">python</span> <span class="n">module</span> <span class="n">tutorial</span>
908 </code></pre></div>
909
910 <p>The <code>__dict__</code> attribute of a <a href="#Dataset">Dataset</a>, <a href="#Group">Group</a> or <a href="#Variable">Variable</a>
911 instance provides all the netCDF attribute name/value pairs in a python
912 dictionary:</p>
913
914 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">)</span>
915 <span class="p">{</span><span class="s1">&#39;description&#39;</span><span class="p">:</span> <span class="s1">&#39;bogus example script&#39;</span><span class="p">,</span> <span class="s1">&#39;history&#39;</span><span class="p">:</span> <span class="s1">&#39;Created Mon Jul 8 14:19:41 2019&#39;</span><span class="p">,</span> <span class="s1">&#39;source&#39;</span><span class="p">:</span> <span class="s1">&#39;netCDF4 python module tutorial&#39;</span><span class="p">}</span>
916 </code></pre></div>
917
918 <p>Attributes can be deleted from a netCDF <a href="#Dataset">Dataset</a>, <a href="#Group">Group</a> or
919 <a href="#Variable">Variable</a> using the python <code>del</code> statement (i.e. <code>del grp.foo</code>
920 removes the attribute <code>foo</code> the the group <code>grp</code>).</p>
921
922 <h2 id="writing-data-to-and-retrieving-data-from-a-netcdf-variable">Writing data to and retrieving data from a netCDF variable</h2>
923
924 <p>Now that you have a netCDF <a href="#Variable">Variable</a> instance, how do you put data
925 into it? You can just treat it like an array and assign data to a slice.</p>
926
927 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">numpy</span>
928 <span class="o">&gt;&gt;&gt;</span> <span class="n">lats</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="o">-</span><span class="mi">90</span><span class="p">,</span><span class="mi">91</span><span class="p">,</span><span class="mf">2.5</span><span class="p">)</span>
929 <span class="o">&gt;&gt;&gt;</span> <span class="n">lons</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="o">-</span><span class="mi">180</span><span class="p">,</span><span class="mi">180</span><span class="p">,</span><span class="mf">2.5</span><span class="p">)</span>
930 <span class="o">&gt;&gt;&gt;</span> <span class="n">latitudes</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">lats</span>
931 <span class="o">&gt;&gt;&gt;</span> <span class="n">longitudes</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">lons</span>
932 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;latitudes =</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">latitudes</span><span class="p">[:]))</span>
933 <span class="n">latitudes</span> <span class="o">=</span>
934 <span class="p">[</span><span class="o">-</span><span class="mf">90.</span> <span class="o">-</span><span class="mf">87.5</span> <span class="o">-</span><span class="mf">85.</span> <span class="o">-</span><span class="mf">82.5</span> <span class="o">-</span><span class="mf">80.</span> <span class="o">-</span><span class="mf">77.5</span> <span class="o">-</span><span class="mf">75.</span> <span class="o">-</span><span class="mf">72.5</span> <span class="o">-</span><span class="mf">70.</span> <span class="o">-</span><span class="mf">67.5</span> <span class="o">-</span><span class="mf">65.</span> <span class="o">-</span><span class="mf">62.5</span>
935 <span class="o">-</span><span class="mf">60.</span> <span class="o">-</span><span class="mf">57.5</span> <span class="o">-</span><span class="mf">55.</span> <span class="o">-</span><span class="mf">52.5</span> <span class="o">-</span><span class="mf">50.</span> <span class="o">-</span><span class="mf">47.5</span> <span class="o">-</span><span class="mf">45.</span> <span class="o">-</span><span class="mf">42.5</span> <span class="o">-</span><span class="mf">40.</span> <span class="o">-</span><span class="mf">37.5</span> <span class="o">-</span><span class="mf">35.</span> <span class="o">-</span><span class="mf">32.5</span>
936 <span class="o">-</span><span class="mf">30.</span> <span class="o">-</span><span class="mf">27.5</span> <span class="o">-</span><span class="mf">25.</span> <span class="o">-</span><span class="mf">22.5</span> <span class="o">-</span><span class="mf">20.</span> <span class="o">-</span><span class="mf">17.5</span> <span class="o">-</span><span class="mf">15.</span> <span class="o">-</span><span class="mf">12.5</span> <span class="o">-</span><span class="mf">10.</span> <span class="o">-</span><span class="mf">7.5</span> <span class="o">-</span><span class="mf">5.</span> <span class="o">-</span><span class="mf">2.5</span>
937 <span class="mf">0.</span> <span class="mf">2.5</span> <span class="mf">5.</span> <span class="mf">7.5</span> <span class="mf">10.</span> <span class="mf">12.5</span> <span class="mf">15.</span> <span class="mf">17.5</span> <span class="mf">20.</span> <span class="mf">22.5</span> <span class="mf">25.</span> <span class="mf">27.5</span>
938 <span class="mf">30.</span> <span class="mf">32.5</span> <span class="mf">35.</span> <span class="mf">37.5</span> <span class="mf">40.</span> <span class="mf">42.5</span> <span class="mf">45.</span> <span class="mf">47.5</span> <span class="mf">50.</span> <span class="mf">52.5</span> <span class="mf">55.</span> <span class="mf">57.5</span>
939 <span class="mf">60.</span> <span class="mf">62.5</span> <span class="mf">65.</span> <span class="mf">67.5</span> <span class="mf">70.</span> <span class="mf">72.5</span> <span class="mf">75.</span> <span class="mf">77.5</span> <span class="mf">80.</span> <span class="mf">82.5</span> <span class="mf">85.</span> <span class="mf">87.5</span>
940 <span class="mf">90.</span> <span class="p">]</span>
941 </code></pre></div>
942
943 <p>Unlike NumPy's array objects, netCDF <a href="#Variable">Variable</a>
944 objects with unlimited dimensions will grow along those dimensions if you
945 assign data outside the currently defined range of indices.</p>
946
947 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># append along two unlimited dimensions by assigning to slice.</span>
948 <span class="o">&gt;&gt;&gt;</span> <span class="n">nlats</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">dimensions</span><span class="p">[</span><span class="s2">&quot;lat&quot;</span><span class="p">])</span>
949 <span class="o">&gt;&gt;&gt;</span> <span class="n">nlons</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">dimensions</span><span class="p">[</span><span class="s2">&quot;lon&quot;</span><span class="p">])</span>
950 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;temp shape before adding data = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">temp</span><span class="o">.</span><span class="n">shape</span><span class="p">))</span>
951 <span class="n">temp</span> <span class="n">shape</span> <span class="n">before</span> <span class="n">adding</span> <span class="n">data</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
952 <span class="o">&gt;&gt;&gt;</span>
953 <span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">numpy.random</span> <span class="kn">import</span> <span class="n">uniform</span>
954 <span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">,</span> <span class="p">:,</span> <span class="p">:]</span> <span class="o">=</span> <span class="n">uniform</span><span class="p">(</span><span class="n">size</span><span class="o">=</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="n">nlats</span><span class="p">,</span> <span class="n">nlons</span><span class="p">))</span>
955 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;temp shape after adding data = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">temp</span><span class="o">.</span><span class="n">shape</span><span class="p">))</span>
956 <span class="n">temp</span> <span class="n">shape</span> <span class="n">after</span> <span class="n">adding</span> <span class="n">data</span> <span class="o">=</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
957 <span class="o">&gt;&gt;&gt;</span>
958 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># levels have grown, but no values yet assigned.</span>
959 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;levels shape after adding pressure data = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">levels</span><span class="o">.</span><span class="n">shape</span><span class="p">))</span>
960 <span class="n">levels</span> <span class="n">shape</span> <span class="n">after</span> <span class="n">adding</span> <span class="n">pressure</span> <span class="n">data</span> <span class="o">=</span> <span class="p">(</span><span class="mi">10</span><span class="p">,)</span>
961 </code></pre></div>
962
963 <p>Note that the size of the levels variable grows when data is appended
964 along the <code>level</code> dimension of the variable <code>temp</code>, even though no
965 data has yet been assigned to levels.</p>
966
967 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># now, assign data to levels dimension variable.</span>
968 <span class="o">&gt;&gt;&gt;</span> <span class="n">levels</span><span class="p">[:]</span> <span class="o">=</span> <span class="p">[</span><span class="mf">1000.</span><span class="p">,</span><span class="mf">850.</span><span class="p">,</span><span class="mf">700.</span><span class="p">,</span><span class="mf">500.</span><span class="p">,</span><span class="mf">300.</span><span class="p">,</span><span class="mf">250.</span><span class="p">,</span><span class="mf">200.</span><span class="p">,</span><span class="mf">150.</span><span class="p">,</span><span class="mf">100.</span><span class="p">,</span><span class="mf">50.</span><span class="p">]</span>
969 </code></pre></div>
970
971 <p>However, that there are some differences between NumPy and netCDF
972 variable slicing rules. Slices behave as usual, being specified as a
973 <code>start:stop:step</code> triplet. Using a scalar integer index <code>i</code> takes the ith
974 element and reduces the rank of the output array by one. Boolean array and
975 integer sequence indexing behaves differently for netCDF variables
976 than for numpy arrays. Only 1-d boolean arrays and integer sequences are
977 allowed, and these indices work independently along each dimension (similar
978 to the way vector subscripts work in fortran). This means that</p>
979
980 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">]]</span><span class="o">.</span><span class="n">shape</span>
981 <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span>
982 </code></pre></div>
983
984 <p>returns an array of shape (4,4) when slicing a netCDF variable, but for a
985 numpy array it returns an array of shape (4,).
986 Similarly, a netCDF variable of shape <code>(2,3,4,5)</code> indexed
987 with <code>[0, array([True, False, True]), array([False, True, True, True]), :]</code>
988 would return a <code>(2, 3, 5)</code> array. In NumPy, this would raise an error since
989 it would be equivalent to <code>[0, [0,1], [1,2,3], :]</code>. When slicing with integer
990 sequences, the indices <strong><em>need not be sorted</em></strong> and <strong><em>may contain
991 duplicates</em></strong> (both of these are new features in version 1.2.1).
992 While this behaviour may cause some confusion for those used to NumPy's 'fancy indexing' rules,
993 it provides a very powerful way to extract data from multidimensional netCDF
994 variables by using logical operations on the dimension arrays to create slices.</p>
995
996 <p>For example,</p>
997
998 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">tempdat</span> <span class="o">=</span> <span class="n">temp</span><span class="p">[::</span><span class="mi">2</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">6</span><span class="p">],</span> <span class="n">lats</span><span class="o">&gt;</span><span class="mi">0</span><span class="p">,</span> <span class="n">lons</span><span class="o">&gt;</span><span class="mi">0</span><span class="p">]</span>
999 </code></pre></div>
1000
1001 <p>will extract time indices 0,2 and 4, pressure levels
1002 850, 500 and 200 hPa, all Northern Hemisphere latitudes and Eastern
1003 Hemisphere longitudes, resulting in a numpy array of shape (3, 3, 36, 71).</p>
1004
1005 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;shape of fancy temp slice = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">tempdat</span><span class="o">.</span><span class="n">shape</span><span class="p">))</span>
1006 <span class="n">shape</span> <span class="n">of</span> <span class="n">fancy</span> <span class="n">temp</span> <span class="nb">slice</span> <span class="o">=</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">36</span><span class="p">,</span> <span class="mi">71</span><span class="p">)</span>
1007 </code></pre></div>
1008
1009 <p><strong><em>Special note for scalar variables</em></strong>: To extract data from a scalar variable
1010 <code>v</code> with no associated dimensions, use <code>numpy.asarray(v)</code> or <code>v[...]</code>.
1011 The result will be a numpy scalar array.</p>
1012
1013 <p>By default, netcdf4-python returns numpy masked arrays with values equal to the
1014 <code>missing_value</code> or <code>_FillValue</code> variable attributes masked. The
1015 <a href="#<a href="#Dataset.set_auto_mask">Dataset.set_auto_mask</a>"><a href="#Dataset.set_auto_mask">Dataset.set_auto_mask</a></a> <a href="#Dataset">Dataset</a> and <a href="#Variable">Variable</a> methods
1016 can be used to disable this feature so that
1017 numpy arrays are always returned, with the missing values included. Prior to
1018 version 1.4.0 the default behavior was to only return masked arrays when the
1019 requested slice contained missing values. This behavior can be recovered
1020 using the <a href="#<a href="#Dataset.set_always_mask">Dataset.set_always_mask</a>"><a href="#Dataset.set_always_mask">Dataset.set_always_mask</a></a> method. If a masked array is
1021 written to a netCDF variable, the masked elements are filled with the
1022 value specified by the <code>missing_value</code> attribute. If the variable has
1023 no <code>missing_value</code>, the <code>_FillValue</code> is used instead.</p>
1024
1025 <h2 id="dealing-with-time-coordinates">Dealing with time coordinates</h2>
1026
1027 <p>Time coordinate values pose a special challenge to netCDF users. Most
1028 metadata standards (such as CF) specify that time should be
1029 measure relative to a fixed date using a certain calendar, with units
1030 specified like <code>hours since YY-MM-DD hh:mm:ss</code>. These units can be
1031 awkward to deal with, without a utility to convert the values to and
1032 from calendar dates. The functions <a href="https://unidata.github.io/cftime/api.html">num2date</a>
1033 and <a href="https://unidata.github.io/cftime/api.html">date2num</a> are
1034 provided by <a href="https://unidata.github.io/cftime">cftime</a> to do just that.
1035 Here's an example of how they can be used:</p>
1036
1037 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># fill in times.</span>
1038 <span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">timedelta</span>
1039 <span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">cftime</span> <span class="kn">import</span> <span class="n">num2date</span><span class="p">,</span> <span class="n">date2num</span>
1040 <span class="o">&gt;&gt;&gt;</span> <span class="n">dates</span> <span class="o">=</span> <span class="p">[</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span><span class="o">+</span><span class="n">n</span><span class="o">*</span><span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">12</span><span class="p">)</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">temp</span><span class="o">.</span><span class="n">shape</span><span class="p">[</span><span class="mi">0</span><span class="p">])]</span>
1041 <span class="o">&gt;&gt;&gt;</span> <span class="n">times</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">date2num</span><span class="p">(</span><span class="n">dates</span><span class="p">,</span><span class="n">units</span><span class="o">=</span><span class="n">times</span><span class="o">.</span><span class="n">units</span><span class="p">,</span><span class="n">calendar</span><span class="o">=</span><span class="n">times</span><span class="o">.</span><span class="n">calendar</span><span class="p">)</span>
1042 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;time values (in units </span><span class="si">{}</span><span class="s2">):</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">times</span><span class="o">.</span><span class="n">units</span><span class="p">,</span> <span class="n">times</span><span class="p">[:]))</span>
1043 <span class="n">time</span> <span class="n">values</span> <span class="p">(</span><span class="ow">in</span> <span class="n">units</span> <span class="n">hours</span> <span class="n">since</span> <span class="mi">0001</span><span class="o">-</span><span class="mi">01</span><span class="o">-</span><span class="mi">01</span> <span class="mi">00</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mf">00.0</span><span class="p">):</span>
1044 <span class="p">[</span><span class="mf">17533104.</span> <span class="mf">17533116.</span> <span class="mf">17533128.</span> <span class="mf">17533140.</span> <span class="mf">17533152.</span><span class="p">]</span>
1045 <span class="o">&gt;&gt;&gt;</span> <span class="n">dates</span> <span class="o">=</span> <span class="n">num2date</span><span class="p">(</span><span class="n">times</span><span class="p">[:],</span><span class="n">units</span><span class="o">=</span><span class="n">times</span><span class="o">.</span><span class="n">units</span><span class="p">,</span><span class="n">calendar</span><span class="o">=</span><span class="n">times</span><span class="o">.</span><span class="n">calendar</span><span class="p">)</span>
1046 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;dates corresponding to time values:</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">dates</span><span class="p">))</span>
1047 <span class="n">dates</span> <span class="n">corresponding</span> <span class="n">to</span> <span class="n">time</span> <span class="n">values</span><span class="p">:</span>
1048 <span class="p">[</span><span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
1049 <span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
1050 <span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)]</span>
1051 </code></pre></div>
1052
1053 <p><code>num2date</code> converts numeric values of time in the specified <code>units</code>
1054 and <code>calendar</code> to datetime objects, and <code>date2num</code> does the reverse.
1055 All the calendars currently defined in the
1056 <a href="http://cfconventions.org">CF metadata convention</a> are supported.
1057 A function called <code>date2index</code> is also provided which returns the indices
1058 of a netCDF time variable corresponding to a sequence of datetime instances.</p>
1059
1060 <h2 id="reading-data-from-a-multi-file-netcdf-dataset">Reading data from a multi-file netCDF dataset</h2>
1061
1062 <p>If you want to read data from a variable that spans multiple netCDF files,
1063 you can use the <a href="#MFDataset">MFDataset</a> class to read the data as if it were
1064 contained in a single file. Instead of using a single filename to create
1065 a <a href="#Dataset">Dataset</a> instance, create a <a href="#MFDataset">MFDataset</a> instance with either a list
1066 of filenames, or a string with a wildcard (which is then converted to
1067 a sorted list of files using the python glob module).
1068 Variables in the list of files that share the same unlimited
1069 dimension are aggregated together, and can be sliced across multiple
1070 files. To illustrate this, let's first create a bunch of netCDF files with
1071 the same variable (with the same unlimited dimension). The files
1072 must in be in <code>NETCDF3_64BIT_OFFSET</code>, <code>NETCDF3_64BIT_DATA</code>, <code>NETCDF3_CLASSIC</code> or
1073 <code>NETCDF4_CLASSIC</code> format (<code>NETCDF4</code> formatted multi-file
1074 datasets are not supported).</p>
1075
1076 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">nf</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
1077 <span class="o">...</span> <span class="k">with</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;mftest</span><span class="si">%s</span><span class="s2">.nc&quot;</span> <span class="o">%</span> <span class="n">nf</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s2">&quot;NETCDF4_CLASSIC&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
1078 <span class="o">...</span> <span class="n">_</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1079 <span class="o">...</span> <span class="n">x</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="s2">&quot;i&quot;</span><span class="p">,(</span><span class="s2">&quot;x&quot;</span><span class="p">,))</span>
1080 <span class="o">...</span> <span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">nf</span><span class="o">*</span><span class="mi">10</span><span class="p">,</span><span class="mi">10</span><span class="o">*</span><span class="p">(</span><span class="n">nf</span><span class="o">+</span><span class="mi">1</span><span class="p">))</span>
1081 </code></pre></div>
1082
1083 <p>Now read all the files back in at once with <a href="#MFDataset">MFDataset</a></p>
1084
1085 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">MFDataset</span>
1086 <span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">MFDataset</span><span class="p">(</span><span class="s2">&quot;mftest*nc&quot;</span><span class="p">)</span>
1087 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;x&quot;</span><span class="p">][:])</span>
1088 <span class="p">[</span> <span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span> <span class="mi">5</span> <span class="mi">6</span> <span class="mi">7</span> <span class="mi">8</span> <span class="mi">9</span> <span class="mi">10</span> <span class="mi">11</span> <span class="mi">12</span> <span class="mi">13</span> <span class="mi">14</span> <span class="mi">15</span> <span class="mi">16</span> <span class="mi">17</span> <span class="mi">18</span> <span class="mi">19</span> <span class="mi">20</span> <span class="mi">21</span> <span class="mi">22</span> <span class="mi">23</span>
1089 <span class="mi">24</span> <span class="mi">25</span> <span class="mi">26</span> <span class="mi">27</span> <span class="mi">28</span> <span class="mi">29</span> <span class="mi">30</span> <span class="mi">31</span> <span class="mi">32</span> <span class="mi">33</span> <span class="mi">34</span> <span class="mi">35</span> <span class="mi">36</span> <span class="mi">37</span> <span class="mi">38</span> <span class="mi">39</span> <span class="mi">40</span> <span class="mi">41</span> <span class="mi">42</span> <span class="mi">43</span> <span class="mi">44</span> <span class="mi">45</span> <span class="mi">46</span> <span class="mi">47</span>
1090 <span class="mi">48</span> <span class="mi">49</span> <span class="mi">50</span> <span class="mi">51</span> <span class="mi">52</span> <span class="mi">53</span> <span class="mi">54</span> <span class="mi">55</span> <span class="mi">56</span> <span class="mi">57</span> <span class="mi">58</span> <span class="mi">59</span> <span class="mi">60</span> <span class="mi">61</span> <span class="mi">62</span> <span class="mi">63</span> <span class="mi">64</span> <span class="mi">65</span> <span class="mi">66</span> <span class="mi">67</span> <span class="mi">68</span> <span class="mi">69</span> <span class="mi">70</span> <span class="mi">71</span>
1091 <span class="mi">72</span> <span class="mi">73</span> <span class="mi">74</span> <span class="mi">75</span> <span class="mi">76</span> <span class="mi">77</span> <span class="mi">78</span> <span class="mi">79</span> <span class="mi">80</span> <span class="mi">81</span> <span class="mi">82</span> <span class="mi">83</span> <span class="mi">84</span> <span class="mi">85</span> <span class="mi">86</span> <span class="mi">87</span> <span class="mi">88</span> <span class="mi">89</span> <span class="mi">90</span> <span class="mi">91</span> <span class="mi">92</span> <span class="mi">93</span> <span class="mi">94</span> <span class="mi">95</span>
1092 <span class="mi">96</span> <span class="mi">97</span> <span class="mi">98</span> <span class="mi">99</span><span class="p">]</span>
1093 </code></pre></div>
1094
1095 <p>Note that <a href="#MFDataset">MFDataset</a> can only be used to read, not write, multi-file
1096 datasets.</p>
1097
1098 <h2 id="efficient-compression-of-netcdf-variables">Efficient compression of netCDF variables</h2>
1099
1100 <p>Data stored in netCDF 4 <a href="#Variable">Variable</a> objects can be compressed and
1101 decompressed on the fly. The parameters for the compression are
1102 determined by the <code>zlib</code>, <code>complevel</code> and <code>shuffle</code> keyword arguments
1103 to the <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> method. To turn on
1104 compression, set <code>zlib=True</code>. The <code>complevel</code> keyword regulates the
1105 speed and efficiency of the compression (1 being fastest, but lowest
1106 compression ratio, 9 being slowest but best compression ratio). The
1107 default value of <code>complevel</code> is 4. Setting <code>shuffle=False</code> will turn
1108 off the HDF5 shuffle filter, which de-interlaces a block of data before
1109 compression by reordering the bytes. The shuffle filter can
1110 significantly improve compression ratios, and is on by default. Setting
1111 <code>fletcher32</code> keyword argument to
1112 <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> to <code>True</code> (it's <code>False</code> by
1113 default) enables the Fletcher32 checksum algorithm for error detection.
1114 It's also possible to set the HDF5 chunking parameters and endian-ness
1115 of the binary data stored in the HDF5 file with the <code>chunksizes</code>
1116 and <code>endian</code> keyword arguments to
1117 <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a>. These keyword arguments only
1118 are relevant for <code>NETCDF4</code> and <code>NETCDF4_CLASSIC</code> files (where the
1119 underlying file format is HDF5) and are silently ignored if the file
1120 format is <code>NETCDF3_CLASSIC</code>, <code>NETCDF3_64BIT_OFFSET</code> or <code>NETCDF3_64BIT_DATA</code>.</p>
1121
1122 <p>If your data only has a certain number of digits of precision (say for
1123 example, it is temperature data that was measured with a precision of
1124 0.1 degrees), you can dramatically improve zlib compression by
1125 quantizing (or truncating) the data using the <code>least_significant_digit</code>
1126 keyword argument to <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a>. The least
1127 significant digit is the power of ten of the smallest decimal place in
1128 the data that is a reliable value. For example if the data has a
1129 precision of 0.1, then setting <code>least_significant_digit=1</code> will cause
1130 data the data to be quantized using <code>numpy.around(scale*data)/scale</code>, where
1131 scale = 2**bits, and bits is determined so that a precision of 0.1 is
1132 retained (in this case bits=4). Effectively, this makes the compression
1133 'lossy' instead of 'lossless', that is some precision in the data is
1134 sacrificed for the sake of disk space.</p>
1135
1136 <p>In our example, try replacing the line</p>
1137
1138 <pre><code>```python
1139 &gt;&gt;&gt; temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",))
1140 </code></pre>
1141
1142 <p>with</p>
1143
1144 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,),</span><span class="n">zlib</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
1145 </code></pre></div>
1146
1147 <p>and then</p>
1148
1149 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,),</span><span class="n">zlib</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span><span class="n">least_significant_digit</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
1150 </code></pre></div>
1151
1152 <p>and see how much smaller the resulting files are.</p>
1153
1154 <h2 id="beyond-homogeneous-arrays-of-a-fixed-type-compound-data-types">Beyond homogeneous arrays of a fixed type - compound data types</h2>
1155
1156 <p>Compound data types map directly to numpy structured (a.k.a 'record')
1157 arrays. Structured arrays are akin to C structs, or derived types
1158 in Fortran. They allow for the construction of table-like structures
1159 composed of combinations of other data types, including other
1160 compound types. Compound types might be useful for representing multiple
1161 parameter values at each point on a grid, or at each time and space
1162 location for scattered (point) data. You can then access all the
1163 information for a point by reading one variable, instead of reading
1164 different parameters from different variables. Compound data types
1165 are created from the corresponding numpy data type using the
1166 <a href="#<a href="#Dataset.createCompoundType">Dataset.createCompoundType</a>"><a href="#Dataset.createCompoundType">Dataset.createCompoundType</a></a> method of a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance.
1167 Since there is no native complex data type in netcdf, compound types are handy
1168 for storing numpy complex arrays. Here's an example:</p>
1169
1170 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;complex.nc&quot;</span><span class="p">,</span><span class="s2">&quot;w&quot;</span><span class="p">)</span>
1171 <span class="o">&gt;&gt;&gt;</span> <span class="n">size</span> <span class="o">=</span> <span class="mi">3</span> <span class="c1"># length of 1-d complex array</span>
1172 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create sample complex data.</span>
1173 <span class="o">&gt;&gt;&gt;</span> <span class="n">datac</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">exp</span><span class="p">(</span><span class="mi">1</span><span class="n">j</span><span class="o">*</span><span class="p">(</span><span class="mf">1.</span><span class="o">+</span><span class="n">numpy</span><span class="o">.</span><span class="n">linspace</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">numpy</span><span class="o">.</span><span class="n">pi</span><span class="p">,</span> <span class="n">size</span><span class="p">)))</span>
1174 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create complex128 compound data type.</span>
1175 <span class="o">&gt;&gt;&gt;</span> <span class="n">complex128</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">dtype</span><span class="p">([(</span><span class="s2">&quot;real&quot;</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">float_64</span><span class="p">),(</span><span class="s2">&quot;imag&quot;</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">float_64</span><span class="p">)])</span>
1176 <span class="o">&gt;&gt;&gt;</span> <span class="n">complex128_t</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createCompoundType</span><span class="p">(</span><span class="n">complex128</span><span class="p">,</span><span class="s2">&quot;complex128&quot;</span><span class="p">)</span>
1177 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a variable with this data type, write some data to it.</span>
1178 <span class="o">&gt;&gt;&gt;</span> <span class="n">x_dim</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;x_dim&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1179 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;cmplx_var&quot;</span><span class="p">,</span><span class="n">complex128_t</span><span class="p">,</span><span class="s2">&quot;x_dim&quot;</span><span class="p">)</span>
1180 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="n">size</span><span class="p">,</span><span class="n">complex128</span><span class="p">)</span> <span class="c1"># numpy structured array</span>
1181 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span><span class="p">[</span><span class="s2">&quot;real&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datac</span><span class="o">.</span><span class="n">real</span><span class="p">;</span> <span class="n">data</span><span class="p">[</span><span class="s2">&quot;imag&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datac</span><span class="o">.</span><span class="n">imag</span>
1182 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span> <span class="c1"># write numpy structured array to netcdf compound var</span>
1183 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># close and reopen the file, check the contents.</span>
1184 <span class="o">&gt;&gt;&gt;</span> <span class="n">f</span><span class="o">.</span><span class="n">close</span><span class="p">();</span> <span class="n">f</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;complex.nc&quot;</span><span class="p">)</span>
1185 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;cmplx_var&quot;</span><span class="p">]</span>
1186 <span class="o">&gt;&gt;&gt;</span> <span class="n">datain</span> <span class="o">=</span> <span class="n">v</span><span class="p">[:]</span> <span class="c1"># read in all the data into a numpy structured array</span>
1187 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create an empty numpy complex array</span>
1188 <span class="o">&gt;&gt;&gt;</span> <span class="n">datac2</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="n">datain</span><span class="o">.</span><span class="n">shape</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">complex128</span><span class="p">)</span>
1189 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># .. fill it with contents of structured array.</span>
1190 <span class="o">&gt;&gt;&gt;</span> <span class="n">datac2</span><span class="o">.</span><span class="n">real</span> <span class="o">=</span> <span class="n">datain</span><span class="p">[</span><span class="s2">&quot;real&quot;</span><span class="p">];</span> <span class="n">datac2</span><span class="o">.</span><span class="n">imag</span> <span class="o">=</span> <span class="n">datain</span><span class="p">[</span><span class="s2">&quot;imag&quot;</span><span class="p">]</span>
1191 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">{}</span><span class="s1">: </span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">datac</span><span class="o">.</span><span class="n">dtype</span><span class="p">,</span> <span class="n">datac</span><span class="p">))</span> <span class="c1"># original data</span>
1192 <span class="n">complex128</span><span class="p">:</span> <span class="p">[</span> <span class="mf">0.54030231</span><span class="o">+</span><span class="mf">0.84147098</span><span class="n">j</span> <span class="o">-</span><span class="mf">0.84147098</span><span class="o">+</span><span class="mf">0.54030231</span><span class="n">j</span> <span class="o">-</span><span class="mf">0.54030231</span><span class="o">-</span><span class="mf">0.84147098</span><span class="n">j</span><span class="p">]</span>
1193 <span class="o">&gt;&gt;&gt;</span>
1194 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">{}</span><span class="s1">: </span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">datac2</span><span class="o">.</span><span class="n">dtype</span><span class="p">,</span> <span class="n">datac2</span><span class="p">))</span> <span class="c1"># data from file</span>
1195 <span class="n">complex128</span><span class="p">:</span> <span class="p">[</span> <span class="mf">0.54030231</span><span class="o">+</span><span class="mf">0.84147098</span><span class="n">j</span> <span class="o">-</span><span class="mf">0.84147098</span><span class="o">+</span><span class="mf">0.54030231</span><span class="n">j</span> <span class="o">-</span><span class="mf">0.54030231</span><span class="o">-</span><span class="mf">0.84147098</span><span class="n">j</span><span class="p">]</span>
1196 </code></pre></div>
1197
1198 <p>Compound types can be nested, but you must create the 'inner'
1199 ones first. All possible numpy structured arrays cannot be
1200 represented as Compound variables - an error message will be
1201 raise if you try to create one that is not supported.
1202 All of the compound types defined for a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> are stored
1203 in a Python dictionary, just like variables and dimensions. As always, printing
1204 objects gives useful summary information in an interactive session:</p>
1205
1206 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
1207 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
1208 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
1209 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x_dim</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
1210 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="p">{</span><span class="s1">&#39;names&#39;</span><span class="p">:[</span><span class="s1">&#39;real&#39;</span><span class="p">,</span><span class="s1">&#39;imag&#39;</span><span class="p">],</span> <span class="s1">&#39;formats&#39;</span><span class="p">:[</span><span class="s1">&#39;&lt;f8&#39;</span><span class="p">,</span><span class="s1">&#39;&lt;f8&#39;</span><span class="p">],</span> <span class="s1">&#39;offsets&#39;</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">8</span><span class="p">],</span> <span class="s1">&#39;itemsize&#39;</span><span class="p">:</span><span class="mi">16</span><span class="p">,</span> <span class="s1">&#39;aligned&#39;</span><span class="p">:</span><span class="kc">True</span><span class="p">}</span> <span class="n">cmplx_var</span><span class="p">(</span><span class="n">x_dim</span><span class="p">)</span>
1211 <span class="n">groups</span><span class="p">:</span>
1212 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;cmplx_var&quot;</span><span class="p">])</span>
1213 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1214 <span class="n">compound</span> <span class="n">cmplx_var</span><span class="p">(</span><span class="n">x_dim</span><span class="p">)</span>
1215 <span class="n">compound</span> <span class="n">data</span> <span class="nb">type</span><span class="p">:</span> <span class="p">{</span><span class="s1">&#39;names&#39;</span><span class="p">:[</span><span class="s1">&#39;real&#39;</span><span class="p">,</span><span class="s1">&#39;imag&#39;</span><span class="p">],</span> <span class="s1">&#39;formats&#39;</span><span class="p">:[</span><span class="s1">&#39;&lt;f8&#39;</span><span class="p">,</span><span class="s1">&#39;&lt;f8&#39;</span><span class="p">],</span> <span class="s1">&#39;offsets&#39;</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">8</span><span class="p">],</span> <span class="s1">&#39;itemsize&#39;</span><span class="p">:</span><span class="mi">16</span><span class="p">,</span> <span class="s1">&#39;aligned&#39;</span><span class="p">:</span><span class="kc">True</span><span class="p">}</span>
1216 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">x_dim</span>
1217 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">3</span><span class="p">,)</span>
1218 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">cmptypes</span><span class="p">)</span>
1219 <span class="p">{</span><span class="s1">&#39;complex128&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">CompoundType</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">complex128</span><span class="s1">&#39;, numpy dtype = {&#39;</span><span class="n">names</span><span class="s1">&#39;:[&#39;</span><span class="n">real</span><span class="s1">&#39;,&#39;</span><span class="n">imag</span><span class="s1">&#39;], &#39;</span><span class="n">formats</span><span class="s1">&#39;:[&#39;</span><span class="o">&lt;</span><span class="n">f8</span><span class="s1">&#39;,&#39;</span><span class="o">&lt;</span><span class="n">f8</span><span class="s1">&#39;], &#39;</span><span class="n">offsets</span><span class="s1">&#39;:[0,8], &#39;</span><span class="n">itemsize</span><span class="s1">&#39;:16, &#39;</span><span class="n">aligned</span><span class="s1">&#39;:True}}</span>
1220 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">cmptypes</span><span class="p">[</span><span class="s2">&quot;complex128&quot;</span><span class="p">])</span>
1221 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">CompoundType</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">complex128</span><span class="s1">&#39;, numpy dtype = {&#39;</span><span class="n">names</span><span class="s1">&#39;:[&#39;</span><span class="n">real</span><span class="s1">&#39;,&#39;</span><span class="n">imag</span><span class="s1">&#39;], &#39;</span><span class="n">formats</span><span class="s1">&#39;:[&#39;</span><span class="o">&lt;</span><span class="n">f8</span><span class="s1">&#39;,&#39;</span><span class="o">&lt;</span><span class="n">f8</span><span class="s1">&#39;], &#39;</span><span class="n">offsets</span><span class="s1">&#39;:[0,8], &#39;</span><span class="n">itemsize</span><span class="s1">&#39;:16, &#39;</span><span class="n">aligned</span><span class="s1">&#39;:True}</span>
1222 </code></pre></div>
1223
1224 <h2 id="variable-length-vlen-data-types">Variable-length (vlen) data types</h2>
1225
1226 <p>NetCDF 4 has support for variable-length or "ragged" arrays. These are arrays
1227 of variable length sequences having the same type. To create a variable-length
1228 data type, use the <a href="#<a href="#Dataset.createVLType">Dataset.createVLType</a>"><a href="#Dataset.createVLType">Dataset.createVLType</a></a> method
1229 method of a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance.</p>
1230
1231 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;tst_vlen.nc&quot;</span><span class="p">,</span><span class="s2">&quot;w&quot;</span><span class="p">)</span>
1232 <span class="o">&gt;&gt;&gt;</span> <span class="n">vlen_t</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVLType</span><span class="p">(</span><span class="n">numpy</span><span class="o">.</span><span class="n">int32</span><span class="p">,</span> <span class="s2">&quot;phony_vlen&quot;</span><span class="p">)</span>
1233 </code></pre></div>
1234
1235 <p>The numpy datatype of the variable-length sequences and the name of the
1236 new datatype must be specified. Any of the primitive datatypes can be
1237 used (signed and unsigned integers, 32 and 64 bit floats, and characters),
1238 but compound data types cannot.
1239 A new variable can then be created using this datatype.</p>
1240
1241 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">x</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span>
1242 <span class="o">&gt;&gt;&gt;</span> <span class="n">y</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;y&quot;</span><span class="p">,</span><span class="mi">4</span><span class="p">)</span>
1243 <span class="o">&gt;&gt;&gt;</span> <span class="n">vlvar</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;phony_vlen_var&quot;</span><span class="p">,</span> <span class="n">vlen_t</span><span class="p">,</span> <span class="p">(</span><span class="s2">&quot;y&quot;</span><span class="p">,</span><span class="s2">&quot;x&quot;</span><span class="p">))</span>
1244 </code></pre></div>
1245
1246 <p>Since there is no native vlen datatype in numpy, vlen arrays are represented
1247 in python as object arrays (arrays of dtype <code>object</code>). These are arrays whose
1248 elements are Python object pointers, and can contain any type of python object.
1249 For this application, they must contain 1-D numpy arrays all of the same type
1250 but of varying length.
1251 In this case, they contain 1-D numpy <code>int32</code> arrays of random length between
1252 1 and 10.</p>
1253
1254 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">random</span>
1255 <span class="o">&gt;&gt;&gt;</span> <span class="n">random</span><span class="o">.</span><span class="n">seed</span><span class="p">(</span><span class="mi">54321</span><span class="p">)</span>
1256 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">y</span><span class="p">)</span><span class="o">*</span><span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">),</span><span class="nb">object</span><span class="p">)</span>
1257 <span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">y</span><span class="p">)</span><span class="o">*</span><span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">)):</span>
1258 <span class="o">...</span> <span class="n">data</span><span class="p">[</span><span class="n">n</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">10</span><span class="p">),</span><span class="n">dtype</span><span class="o">=</span><span class="s2">&quot;int32&quot;</span><span class="p">)</span><span class="o">+</span><span class="mi">1</span>
1259 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">reshape</span><span class="p">(</span><span class="n">data</span><span class="p">,(</span><span class="nb">len</span><span class="p">(</span><span class="n">y</span><span class="p">),</span><span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">)))</span>
1260 <span class="o">&gt;&gt;&gt;</span> <span class="n">vlvar</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span>
1261 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;vlen variable =</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">vlvar</span><span class="p">[:]))</span>
1262 <span class="n">vlen</span> <span class="n">variable</span> <span class="o">=</span>
1263 <span class="p">[[</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span> <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
1264 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)]</span>
1265 <span class="p">[</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
1266 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
1267 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)]</span>
1268 <span class="p">[</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span> <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
1269 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)]</span>
1270 <span class="p">[</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
1271 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span> <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)]]</span>
1272 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
1273 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
1274 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
1275 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="n">y</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>
1276 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">phony_vlen_var</span><span class="p">(</span><span class="n">y</span><span class="p">,</span><span class="n">x</span><span class="p">)</span>
1277 <span class="n">groups</span><span class="p">:</span>
1278 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;phony_vlen_var&quot;</span><span class="p">])</span>
1279 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1280 <span class="n">vlen</span> <span class="n">phony_vlen_var</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span>
1281 <span class="n">vlen</span> <span class="n">data</span> <span class="nb">type</span><span class="p">:</span> <span class="n">int32</span>
1282 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span>
1283 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
1284 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">vltypes</span><span class="p">[</span><span class="s2">&quot;phony_vlen&quot;</span><span class="p">])</span>
1285 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">VLType</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">phony_vlen</span><span class="s1">&#39;, numpy dtype = int32</span>
1286 </code></pre></div>
1287
1288 <p>Numpy object arrays containing python strings can also be written as vlen
1289 variables, For vlen strings, you don't need to create a vlen data type.
1290 Instead, simply use the python <code>str</code> builtin (or a numpy string datatype
1291 with fixed length greater than 1) when calling the
1292 <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> method.</p>
1293
1294 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">z</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;z&quot;</span><span class="p">,</span><span class="mi">10</span><span class="p">)</span>
1295 <span class="o">&gt;&gt;&gt;</span> <span class="n">strvar</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;strvar&quot;</span><span class="p">,</span> <span class="nb">str</span><span class="p">,</span> <span class="s2">&quot;z&quot;</span><span class="p">)</span>
1296 </code></pre></div>
1297
1298 <p>In this example, an object array is filled with random python strings with
1299 random lengths between 2 and 12 characters, and the data in the object
1300 array is assigned to the vlen string variable.</p>
1301
1302 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">chars</span> <span class="o">=</span> <span class="s2">&quot;1234567890aabcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ&quot;</span>
1303 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="s2">&quot;O&quot;</span><span class="p">)</span>
1304 <span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
1305 <span class="o">...</span> <span class="n">stringlen</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">12</span><span class="p">)</span>
1306 <span class="o">...</span> <span class="n">data</span><span class="p">[</span><span class="n">n</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">chars</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">stringlen</span><span class="p">)])</span>
1307 <span class="o">&gt;&gt;&gt;</span> <span class="n">strvar</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span>
1308 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;variable-length string variable:</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">strvar</span><span class="p">[:]))</span>
1309 <span class="n">variable</span><span class="o">-</span><span class="n">length</span> <span class="n">string</span> <span class="n">variable</span><span class="p">:</span>
1310 <span class="p">[</span><span class="s1">&#39;Lh&#39;</span> <span class="s1">&#39;25F8wBbMI&#39;</span> <span class="s1">&#39;53rmM&#39;</span> <span class="s1">&#39;vvjnb3t63ao&#39;</span> <span class="s1">&#39;qjRBQk6w&#39;</span> <span class="s1">&#39;aJh&#39;</span> <span class="s1">&#39;QF&#39;</span>
1311 <span class="s1">&#39;jtIJbJACaQk4&#39;</span> <span class="s1">&#39;3Z5&#39;</span> <span class="s1">&#39;bftIIq&#39;</span><span class="p">]</span>
1312 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
1313 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
1314 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
1315 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="n">y</span><span class="p">(</span><span class="mi">4</span><span class="p">),</span> <span class="n">z</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
1316 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">phony_vlen_var</span><span class="p">(</span><span class="n">y</span><span class="p">,</span><span class="n">x</span><span class="p">),</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">str</span><span class="s1">&#39;&gt; strvar(z)</span>
1317 <span class="n">groups</span><span class="p">:</span>
1318 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;strvar&quot;</span><span class="p">])</span>
1319 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1320 <span class="n">vlen</span> <span class="n">strvar</span><span class="p">(</span><span class="n">z</span><span class="p">)</span>
1321 <span class="n">vlen</span> <span class="n">data</span> <span class="nb">type</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">str</span><span class="s1">&#39;&gt;</span>
1322 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span>
1323 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">10</span><span class="p">,)</span>
1324 </code></pre></div>
1325
1326 <p>It is also possible to set contents of vlen string variables with numpy arrays
1327 of any string or unicode data type. Note, however, that accessing the contents
1328 of such variables will always return numpy arrays with dtype <code>object</code>.</p>
1329
1330 <h2 id="enum-data-type">Enum data type</h2>
1331
1332 <p>netCDF4 has an enumerated data type, which is an integer datatype that is
1333 restricted to certain named values. Since Enums don't map directly to
1334 a numpy data type, they are read and written as integer arrays.</p>
1335
1336 <p>Here's an example of using an Enum type to hold cloud type data.
1337 The base integer data type and a python dictionary describing the allowed
1338 values and their names are used to define an Enum data type using
1339 <a href="#<a href="#Dataset.createEnumType">Dataset.createEnumType</a>"><a href="#Dataset.createEnumType">Dataset.createEnumType</a></a>.</p>
1340
1341 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;clouds.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">)</span>
1342 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># python dict with allowed values and their names.</span>
1343 <span class="o">&gt;&gt;&gt;</span> <span class="n">enum_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;Altocumulus&#39;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span> <span class="s1">&#39;Missing&#39;</span><span class="p">:</span> <span class="mi">255</span><span class="p">,</span>
1344 <span class="o">...</span> <span class="s1">&#39;Stratus&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;Clear&#39;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
1345 <span class="o">...</span> <span class="s1">&#39;Nimbostratus&#39;</span><span class="p">:</span> <span class="mi">6</span><span class="p">,</span> <span class="s1">&#39;Cumulus&#39;</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span> <span class="s1">&#39;Altostratus&#39;</span><span class="p">:</span> <span class="mi">5</span><span class="p">,</span>
1346 <span class="o">...</span> <span class="s1">&#39;Cumulonimbus&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;Stratocumulus&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">}</span>
1347 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create the Enum type called &#39;cloud_t&#39;.</span>
1348 <span class="o">&gt;&gt;&gt;</span> <span class="n">cloud_type</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createEnumType</span><span class="p">(</span><span class="n">numpy</span><span class="o">.</span><span class="n">uint8</span><span class="p">,</span><span class="s1">&#39;cloud_t&#39;</span><span class="p">,</span><span class="n">enum_dict</span><span class="p">)</span>
1349 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">cloud_type</span><span class="p">)</span>
1350 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">EnumType</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">cloud_t</span><span class="s1">&#39;, numpy dtype = uint8, fields/values ={&#39;</span><span class="n">Altocumulus</span><span class="s1">&#39;: 7, &#39;</span><span class="n">Missing</span><span class="s1">&#39;: 255, &#39;</span><span class="n">Stratus</span><span class="s1">&#39;: 2, &#39;</span><span class="n">Clear</span><span class="s1">&#39;: 0, &#39;</span><span class="n">Nimbostratus</span><span class="s1">&#39;: 6, &#39;</span><span class="n">Cumulus</span><span class="s1">&#39;: 4, &#39;</span><span class="n">Altostratus</span><span class="s1">&#39;: 5, &#39;</span><span class="n">Cumulonimbus</span><span class="s1">&#39;: 1, &#39;</span><span class="n">Stratocumulus</span><span class="s1">&#39;: 3}</span>
1351 </code></pre></div>
1352
1353 <p>A new variable can be created in the usual way using this data type.
1354 Integer data is written to the variable that represents the named
1355 cloud types in enum_dict. A <code>ValueError</code> will be raised if an attempt
1356 is made to write an integer value not associated with one of the
1357 specified names.</p>
1358
1359 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">time</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;time&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1360 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a 1d variable of type &#39;cloud_type&#39;.</span>
1361 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># The fill_value is set to the &#39;Missing&#39; named value.</span>
1362 <span class="o">&gt;&gt;&gt;</span> <span class="n">cloud_var</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;primary_cloud&#39;</span><span class="p">,</span><span class="n">cloud_type</span><span class="p">,</span><span class="s1">&#39;time&#39;</span><span class="p">,</span>
1363 <span class="o">...</span> <span class="n">fill_value</span><span class="o">=</span><span class="n">enum_dict</span><span class="p">[</span><span class="s1">&#39;Missing&#39;</span><span class="p">])</span>
1364 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># write some data to the variable.</span>
1365 <span class="o">&gt;&gt;&gt;</span> <span class="n">cloud_var</span><span class="p">[:]</span> <span class="o">=</span> <span class="p">[</span><span class="n">enum_dict</span><span class="p">[</span><span class="n">k</span><span class="p">]</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">&#39;Clear&#39;</span><span class="p">,</span> <span class="s1">&#39;Stratus&#39;</span><span class="p">,</span> <span class="s1">&#39;Cumulus&#39;</span><span class="p">,</span>
1366 <span class="o">...</span> <span class="s1">&#39;Missing&#39;</span><span class="p">,</span> <span class="s1">&#39;Cumulonimbus&#39;</span><span class="p">]]</span>
1367 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
1368 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># reopen the file, read the data.</span>
1369 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;clouds.nc&#39;</span><span class="p">)</span>
1370 <span class="o">&gt;&gt;&gt;</span> <span class="n">cloud_var</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s1">&#39;primary_cloud&#39;</span><span class="p">]</span>
1371 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">cloud_var</span><span class="p">)</span>
1372 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1373 <span class="n">enum</span> <span class="n">primary_cloud</span><span class="p">(</span><span class="n">time</span><span class="p">)</span>
1374 <span class="n">_FillValue</span><span class="p">:</span> <span class="mi">255</span>
1375 <span class="n">enum</span> <span class="n">data</span> <span class="nb">type</span><span class="p">:</span> <span class="n">uint8</span>
1376 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span>
1377 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">5</span><span class="p">,)</span>
1378 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">cloud_var</span><span class="o">.</span><span class="n">datatype</span><span class="o">.</span><span class="n">enum_dict</span><span class="p">)</span>
1379 <span class="p">{</span><span class="s1">&#39;Altocumulus&#39;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span> <span class="s1">&#39;Missing&#39;</span><span class="p">:</span> <span class="mi">255</span><span class="p">,</span> <span class="s1">&#39;Stratus&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;Clear&#39;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s1">&#39;Nimbostratus&#39;</span><span class="p">:</span> <span class="mi">6</span><span class="p">,</span> <span class="s1">&#39;Cumulus&#39;</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span> <span class="s1">&#39;Altostratus&#39;</span><span class="p">:</span> <span class="mi">5</span><span class="p">,</span> <span class="s1">&#39;Cumulonimbus&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;Stratocumulus&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">}</span>
1380 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">cloud_var</span><span class="p">[:])</span>
1381 <span class="p">[</span><span class="mi">0</span> <span class="mi">2</span> <span class="mi">4</span> <span class="o">--</span> <span class="mi">1</span><span class="p">]</span>
1382 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
1383 </code></pre></div>
1384
1385 <h2 id="parallel-io">Parallel IO</h2>
1386
1387 <p>If MPI parallel enabled versions of netcdf and hdf5 or pnetcdf are detected,
1388 and <a href="https://mpi4py.scipy.org">mpi4py</a> is installed, netcdf4-python will
1389 be built with parallel IO capabilities enabled. Parallel IO of NETCDF4 or
1390 NETCDF4_CLASSIC formatted files is only available if the MPI parallel HDF5
1391 library is available. Parallel IO of classic netcdf-3 file formats is only
1392 available if the <a href="https://parallel-netcdf.github.io/">PnetCDF</a> library is
1393 available. To use parallel IO, your program must be running in an MPI
1394 environment using <a href="https://mpi4py.scipy.org">mpi4py</a>.</p>
1395
1396 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">mpi4py</span> <span class="kn">import</span> <span class="n">MPI</span>
1397 <span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
1398 <span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">Dataset</span>
1399 <span class="o">&gt;&gt;&gt;</span> <span class="n">rank</span> <span class="o">=</span> <span class="n">MPI</span><span class="o">.</span><span class="n">COMM_WORLD</span><span class="o">.</span><span class="n">rank</span> <span class="c1"># The process ID (integer 0-3 for 4-process run)</span>
1400 </code></pre></div>
1401
1402 <p>To run an MPI-based parallel program like this, you must use <code>mpiexec</code> to launch several
1403 parallel instances of Python (for example, using <code>mpiexec -np 4 python mpi_example.py</code>).
1404 The parallel features of netcdf4-python are mostly transparent -
1405 when a new dataset is created or an existing dataset is opened,
1406 use the <code>parallel</code> keyword to enable parallel access.</p>
1407
1408 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;parallel_test.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">,</span><span class="n">parallel</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
1409 </code></pre></div>
1410
1411 <p>The optional <code>comm</code> keyword may be used to specify a particular
1412 MPI communicator (<code>MPI_COMM_WORLD</code> is used by default). Each process (or rank)
1413 can now write to the file indepedently. In this example the process rank is
1414 written to a different variable index on each task</p>
1415
1416 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">d</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;dim&#39;</span><span class="p">,</span><span class="mi">4</span><span class="p">)</span>
1417 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;var&#39;</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">int</span><span class="p">,</span> <span class="s1">&#39;dim&#39;</span><span class="p">)</span>
1418 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[</span><span class="n">rank</span><span class="p">]</span> <span class="o">=</span> <span class="n">rank</span>
1419 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
1420
1421 <span class="o">%</span> <span class="n">ncdump</span> <span class="n">parallel_test</span><span class="o">.</span><span class="n">nc</span>
1422 <span class="n">netcdf</span> <span class="n">parallel_test</span> <span class="p">{</span>
1423 <span class="n">dimensions</span><span class="p">:</span>
1424 <span class="n">dim</span> <span class="o">=</span> <span class="mi">4</span> <span class="p">;</span>
1425 <span class="n">variables</span><span class="p">:</span>
1426 <span class="n">int64</span> <span class="n">var</span><span class="p">(</span><span class="n">dim</span><span class="p">)</span> <span class="p">;</span>
1427 <span class="n">data</span><span class="p">:</span>
1428
1429 <span class="n">var</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span> <span class="p">;</span>
1430 <span class="p">}</span>
1431 </code></pre></div>
1432
1433 <p>There are two types of parallel IO, independent (the default) and collective.
1434 Independent IO means that each process can do IO independently. It should not
1435 depend on or be affected by other processes. Collective IO is a way of doing
1436 IO defined in the MPI-IO standard; unlike independent IO, all processes must
1437 participate in doing IO. To toggle back and forth between
1438 the two types of IO, use the <a href="#<a href="#Variable.set_collective">Variable.set_collective</a>"><a href="#Variable.set_collective">Variable.set_collective</a></a>
1439 <a href="#Variable">Variable</a> method. All metadata
1440 operations (such as creation of groups, types, variables, dimensions, or attributes)
1441 are collective. There are a couple of important limitations of parallel IO:</p>
1442
1443 <ul>
1444 <li>parallel IO for NETCDF4 or NETCDF4_CLASSIC formatted files is only available
1445 if the netcdf library was compiled with MPI enabled HDF5.</li>
1446 <li>parallel IO for all classic netcdf-3 file formats is only available if the
1447 netcdf library was compiled with <a href="https://parallel-netcdf.github.io">PnetCDF</a>.</li>
1448 <li>If a variable has an unlimited dimension, appending data must be done in collective mode.
1449 If the write is done in independent mode, the operation will fail with a
1450 a generic "HDF Error".</li>
1451 <li>You can write compressed data in parallel only with netcdf-c &gt;= 4.7.4
1452 and hdf5 &gt;= 1.10.3 (although you can read in parallel with earlier versions).</li>
1453 <li>You cannot use variable-length (VLEN) data types.</li>
1454 </ul>
1455
1456 <h2 id="dealing-with-strings">Dealing with strings</h2>
1457
1458 <p>The most flexible way to store arrays of strings is with the
1459 <a href="#variable-length-vlen-data-type">Variable-length (vlen) string data type</a>. However, this requires
1460 the use of the NETCDF4 data model, and the vlen type does not map very well
1461 numpy arrays (you have to use numpy arrays of dtype=<code>object</code>, which are arrays of
1462 arbitrary python objects). numpy does have a fixed-width string array
1463 data type, but unfortunately the netCDF data model does not.
1464 Instead fixed-width byte strings are typically stored as <a href="https://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.html#bp_Strings-and-Variables-of-type-char">arrays of 8-bit
1465 characters</a>.
1466 To perform the conversion to and from character arrays to fixed-width numpy string arrays, the
1467 following convention is followed by the python interface.
1468 If the <code>_Encoding</code> special attribute is set for a character array
1469 (dtype <code>S1</code>) variable, the <a href="#chartostring">chartostring</a> utility function is used to convert the array of
1470 characters to an array of strings with one less dimension (the last dimension is
1471 interpreted as the length of each string) when reading the data. The character
1472 set (usually ascii) is specified by the <code>_Encoding</code> attribute. If <code>_Encoding</code>
1473 is 'none' or 'bytes', then the character array is converted to a numpy
1474 fixed-width byte string array (dtype <code>S#</code>), otherwise a numpy unicode (dtype
1475 <code>U#</code>) array is created. When writing the data,
1476 <a href="#stringtochar">stringtochar</a> is used to convert the numpy string array to an array of
1477 characters with one more dimension. For example,</p>
1478
1479 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">stringtochar</span>
1480 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;stringtest.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">,</span><span class="nb">format</span><span class="o">=</span><span class="s1">&#39;NETCDF4_CLASSIC&#39;</span><span class="p">)</span>
1481 <span class="o">&gt;&gt;&gt;</span> <span class="n">_</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;nchars&#39;</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span>
1482 <span class="o">&gt;&gt;&gt;</span> <span class="n">_</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;nstrings&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1483 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;strings&#39;</span><span class="p">,</span><span class="s1">&#39;S1&#39;</span><span class="p">,(</span><span class="s1">&#39;nstrings&#39;</span><span class="p">,</span><span class="s1">&#39;nchars&#39;</span><span class="p">))</span>
1484 <span class="o">&gt;&gt;&gt;</span> <span class="n">datain</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span><span class="s1">&#39;bar&#39;</span><span class="p">],</span><span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;S3&#39;</span><span class="p">)</span>
1485 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">stringtochar</span><span class="p">(</span><span class="n">datain</span><span class="p">)</span> <span class="c1"># manual conversion to char array</span>
1486 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">v</span><span class="p">[:])</span> <span class="c1"># data returned as char array</span>
1487 <span class="p">[[</span><span class="sa">b</span><span class="s1">&#39;f&#39;</span> <span class="sa">b</span><span class="s1">&#39;o&#39;</span> <span class="sa">b</span><span class="s1">&#39;o&#39;</span><span class="p">]</span>
1488 <span class="p">[</span><span class="sa">b</span><span class="s1">&#39;b&#39;</span> <span class="sa">b</span><span class="s1">&#39;a&#39;</span> <span class="sa">b</span><span class="s1">&#39;r&#39;</span><span class="p">]]</span>
1489 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="o">.</span><span class="n">_Encoding</span> <span class="o">=</span> <span class="s1">&#39;ascii&#39;</span> <span class="c1"># this enables automatic conversion</span>
1490 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">datain</span> <span class="c1"># conversion to char array done internally</span>
1491 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">v</span><span class="p">[:])</span> <span class="c1"># data returned in numpy string array</span>
1492 <span class="p">[</span><span class="s1">&#39;foo&#39;</span> <span class="s1">&#39;bar&#39;</span><span class="p">]</span>
1493 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
1494 </code></pre></div>
1495
1496 <p>Even if the <code>_Encoding</code> attribute is set, the automatic conversion of char
1497 arrays to/from string arrays can be disabled with
1498 <a href="#<a href="#Variable.set_auto_chartostring">Variable.set_auto_chartostring</a>"><a href="#Variable.set_auto_chartostring">Variable.set_auto_chartostring</a></a>.</p>
1499
1500 <p>A similar situation is often encountered with numpy structured arrays with subdtypes
1501 containing fixed-wdith byte strings (dtype=<code>S#</code>). Since there is no native fixed-length string
1502 netCDF datatype, these numpy structure arrays are mapped onto netCDF compound
1503 types with character array elements. In this case the string &lt;-> char array
1504 conversion is handled automatically (without the need to set the <code>_Encoding</code>
1505 attribute) using <a href="https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.view.html">numpy
1506 views</a>.
1507 The structured array dtype (including the string elements) can even be used to
1508 define the compound data type - the string dtype will be converted to
1509 character array dtype under the hood when creating the netcdf compound type.
1510 Here's an example:</p>
1511
1512 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;compoundstring_example.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">)</span>
1513 <span class="o">&gt;&gt;&gt;</span> <span class="n">dtype</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">dtype</span><span class="p">([(</span><span class="s1">&#39;observation&#39;</span><span class="p">,</span> <span class="s1">&#39;f4&#39;</span><span class="p">),</span>
1514 <span class="o">...</span> <span class="p">(</span><span class="s1">&#39;station_name&#39;</span><span class="p">,</span><span class="s1">&#39;S10&#39;</span><span class="p">)])</span>
1515 <span class="o">&gt;&gt;&gt;</span> <span class="n">station_data_t</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createCompoundType</span><span class="p">(</span><span class="n">dtype</span><span class="p">,</span><span class="s1">&#39;station_data&#39;</span><span class="p">)</span>
1516 <span class="o">&gt;&gt;&gt;</span> <span class="n">_</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;station&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1517 <span class="o">&gt;&gt;&gt;</span> <span class="n">statdat</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;station_obs&#39;</span><span class="p">,</span> <span class="n">station_data_t</span><span class="p">,</span> <span class="p">(</span><span class="s1">&#39;station&#39;</span><span class="p">,))</span>
1518 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="n">dtype</span><span class="p">)</span>
1519 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span><span class="p">[</span><span class="s1">&#39;observation&#39;</span><span class="p">][:]</span> <span class="o">=</span> <span class="p">(</span><span class="mf">123.</span><span class="p">,</span><span class="mf">3.14</span><span class="p">)</span>
1520 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span><span class="p">[</span><span class="s1">&#39;station_name&#39;</span><span class="p">][:]</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;Boulder&#39;</span><span class="p">,</span><span class="s1">&#39;New York&#39;</span><span class="p">)</span>
1521 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">statdat</span><span class="o">.</span><span class="n">dtype</span><span class="p">)</span> <span class="c1"># strings actually stored as character arrays</span>
1522 <span class="p">{</span><span class="s1">&#39;names&#39;</span><span class="p">:[</span><span class="s1">&#39;observation&#39;</span><span class="p">,</span><span class="s1">&#39;station_name&#39;</span><span class="p">],</span> <span class="s1">&#39;formats&#39;</span><span class="p">:[</span><span class="s1">&#39;&lt;f4&#39;</span><span class="p">,(</span><span class="s1">&#39;S1&#39;</span><span class="p">,</span> <span class="p">(</span><span class="mi">10</span><span class="p">,))],</span> <span class="s1">&#39;offsets&#39;</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">],</span> <span class="s1">&#39;itemsize&#39;</span><span class="p">:</span><span class="mi">16</span><span class="p">,</span> <span class="s1">&#39;aligned&#39;</span><span class="p">:</span><span class="kc">True</span><span class="p">}</span>
1523 <span class="o">&gt;&gt;&gt;</span> <span class="n">statdat</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span> <span class="c1"># strings converted to character arrays internally</span>
1524 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">statdat</span><span class="p">[:])</span> <span class="c1"># character arrays converted back to strings</span>
1525 <span class="p">[(</span><span class="mf">123.</span> <span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;Boulder&#39;</span><span class="p">)</span> <span class="p">(</span> <span class="mf">3.14</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;New York&#39;</span><span class="p">)]</span>
1526 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">statdat</span><span class="p">[:]</span><span class="o">.</span><span class="n">dtype</span><span class="p">)</span>
1527 <span class="p">{</span><span class="s1">&#39;names&#39;</span><span class="p">:[</span><span class="s1">&#39;observation&#39;</span><span class="p">,</span><span class="s1">&#39;station_name&#39;</span><span class="p">],</span> <span class="s1">&#39;formats&#39;</span><span class="p">:[</span><span class="s1">&#39;&lt;f4&#39;</span><span class="p">,</span><span class="s1">&#39;S10&#39;</span><span class="p">],</span> <span class="s1">&#39;offsets&#39;</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">],</span> <span class="s1">&#39;itemsize&#39;</span><span class="p">:</span><span class="mi">16</span><span class="p">,</span> <span class="s1">&#39;aligned&#39;</span><span class="p">:</span><span class="kc">True</span><span class="p">}</span>
1528 <span class="o">&gt;&gt;&gt;</span> <span class="n">statdat</span><span class="o">.</span><span class="n">set_auto_chartostring</span><span class="p">(</span><span class="kc">False</span><span class="p">)</span> <span class="c1"># turn off auto-conversion</span>
1529 <span class="o">&gt;&gt;&gt;</span> <span class="n">statdat</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">view</span><span class="p">(</span><span class="n">dtype</span><span class="o">=</span><span class="p">[(</span><span class="s1">&#39;observation&#39;</span><span class="p">,</span> <span class="s1">&#39;f4&#39;</span><span class="p">),(</span><span class="s1">&#39;station_name&#39;</span><span class="p">,</span><span class="s1">&#39;S1&#39;</span><span class="p">,</span><span class="mi">10</span><span class="p">)])</span>
1530 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">statdat</span><span class="p">[:])</span> <span class="c1"># now structured array with char array subtype is returned</span>
1531 <span class="p">[(</span><span class="mf">123.</span> <span class="p">,</span> <span class="p">[</span><span class="sa">b</span><span class="s1">&#39;B&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;o&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;u&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;l&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;d&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;e&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;r&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">])</span>
1532 <span class="p">(</span> <span class="mf">3.14</span><span class="p">,</span> <span class="p">[</span><span class="sa">b</span><span class="s1">&#39;N&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;e&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39; &#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;Y&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;o&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;r&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;k&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">])]</span>
1533 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
1534 </code></pre></div>
1535
1536 <p>Note that there is currently no support for mapping numpy structured arrays with
1537 unicode elements (dtype <code>U#</code>) onto netCDF compound types, nor is there support
1538 for netCDF compound types with vlen string components.</p>
1539
1540 <h2 id="in-memory-diskless-datasets">In-memory (diskless) Datasets</h2>
1541
1542 <p>You can create netCDF Datasets whose content is held in memory
1543 instead of in a disk file. There are two ways to do this. If you
1544 don't need access to the memory buffer containing the Dataset from
1545 within python, the best way is to use the <code>diskless=True</code> keyword
1546 argument when creating the Dataset. If you want to save the Dataset
1547 to disk when you close it, also set <code>persist=True</code>. If you want to
1548 create a new read-only Dataset from an existing python memory buffer, use the
1549 <code>memory</code> keyword argument to pass the memory buffer when creating the Dataset.
1550 If you want to create a new in-memory Dataset, and then access the memory buffer
1551 directly from Python, use the <code>memory</code> keyword argument to specify the
1552 estimated size of the Dataset in bytes when creating the Dataset with
1553 <code>mode='w'</code>. Then, the <code><a href="#Dataset.close">Dataset.close</a></code> method will return a python memoryview
1554 object representing the Dataset. Below are examples illustrating both
1555 approaches.</p>
1556
1557 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a diskless (in-memory) Dataset,</span>
1558 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># and persist the file to disk when it is closed.</span>
1559 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;diskless_example.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">,</span><span class="n">diskless</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span><span class="n">persist</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
1560 <span class="o">&gt;&gt;&gt;</span> <span class="n">d</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;x&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1561 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;v&#39;</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">int32</span><span class="p">,</span><span class="s1">&#39;x&#39;</span><span class="p">)</span>
1562 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
1563 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">)</span>
1564 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
1565 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
1566 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
1567 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">v</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
1568 <span class="n">groups</span><span class="p">:</span>
1569 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">[</span><span class="s1">&#39;v&#39;</span><span class="p">][:])</span>
1570 <span class="p">[</span><span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">]</span>
1571 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="c1"># file saved to disk</span>
1572 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create an in-memory dataset from an existing python</span>
1573 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># python memory buffer.</span>
1574 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># read the newly created netcdf file into a python</span>
1575 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># bytes object.</span>
1576 <span class="o">&gt;&gt;&gt;</span> <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;diskless_example.nc&#39;</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
1577 <span class="o">...</span> <span class="n">nc_bytes</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
1578 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a netCDF in-memory dataset from the bytes object.</span>
1579 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;inmemory.nc&#39;</span><span class="p">,</span> <span class="n">memory</span><span class="o">=</span><span class="n">nc_bytes</span><span class="p">)</span>
1580 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">)</span>
1581 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
1582 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
1583 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
1584 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">v</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
1585 <span class="n">groups</span><span class="p">:</span>
1586 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">[</span><span class="s1">&#39;v&#39;</span><span class="p">][:])</span>
1587 <span class="p">[</span><span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">]</span>
1588 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
1589 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create an in-memory Dataset and retrieve memory buffer</span>
1590 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># estimated size is 1028 bytes - this is actually only</span>
1591 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># used if format is NETCDF3</span>
1592 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># (ignored for NETCDF4/HDF5 files).</span>
1593 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;inmemory.nc&#39;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;w&#39;</span><span class="p">,</span><span class="n">memory</span><span class="o">=</span><span class="mi">1028</span><span class="p">)</span>
1594 <span class="o">&gt;&gt;&gt;</span> <span class="n">d</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;x&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1595 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;v&#39;</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">int32</span><span class="p">,</span><span class="s1">&#39;x&#39;</span><span class="p">)</span>
1596 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
1597 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc_buf</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="c1"># close returns memoryview</span>
1598 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">nc_buf</span><span class="p">))</span>
1599 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">memoryview</span><span class="s1">&#39;&gt;</span>
1600 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># save nc_buf to disk, read it back in and check.</span>
1601 <span class="o">&gt;&gt;&gt;</span> <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;inmemory.nc&#39;</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
1602 <span class="o">...</span> <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">nc_buf</span><span class="p">)</span>
1603 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;inmemory.nc&#39;</span><span class="p">)</span>
1604 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">)</span>
1605 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
1606 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
1607 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
1608 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">v</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
1609 <span class="n">groups</span><span class="p">:</span>
1610 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">[</span><span class="s1">&#39;v&#39;</span><span class="p">][:])</span>
1611 <span class="p">[</span><span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">]</span>
1612 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
1613 </code></pre></div>
1614
1615 <p>All of the code in this tutorial is available in <code>examples/tutorial.py</code>, except
1616 the parallel IO example, which is in <code>examples/mpi_example.py</code>.
1617 Unit tests are in the <code>test</code> directory.</p>
1618
1619 <p><strong>contact</strong>: Jeffrey Whitaker <a href="&#109;&#97;&#105;&#x6c;&#116;&#x6f;&#x3a;&#x6a;&#101;ff&#114;&#x65;&#121;&#x2e;&#x73;&#x2e;&#119;&#x68;&#105;&#116;&#x61;&#107;&#101;&#114;&#64;n&#x6f;&#x61;a.&#x67;&#111;v">&#x6a;&#101;ff&#114;&#x65;&#121;&#x2e;&#x73;&#x2e;&#119;&#x68;&#105;&#116;&#x61;&#107;&#101;&#114;&#64;n&#x6f;&#x61;a.&#x67;&#111;v</a></p>
1620
1621 <p><strong>copyright</strong>: 2008 by Jeffrey Whitaker.</p>
1622
1623 <p><strong>license</strong>: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
1624
1625 <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
1626
1627 <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
1628 </div>
1629
1630
1631 </section>
1632 <section id="Dataset">
1633 <div class="attr class">
1634 <a class="headerlink" href="#Dataset">#&nbsp;&nbsp</a>
1635
1636
1637 <span class="def">class</span>
1638 <span class="name">Dataset</span>:
1639 </div>
1640
1641
1642 <div class="docstring"><p>A netCDF <a href="#Dataset">Dataset</a> is a collection of dimensions, groups, variables and
1643 attributes. Together they describe the meaning of data and relations among
1644 data fields stored in a netCDF file. See <a href="#<a href="#Dataset.__init__">Dataset.__init__</a>"><a href="#Dataset.__init__">Dataset.__init__</a></a> for more
1645 details.</p>
1646
1647 <p>A list of attribute names corresponding to global netCDF attributes
1648 defined for the <a href="#Dataset">Dataset</a> can be obtained with the
1649 <a href="#<a href="#Dataset.ncattrs">Dataset.ncattrs</a>"><a href="#Dataset.ncattrs">Dataset.ncattrs</a></a> method.
1650 These attributes can be created by assigning to an attribute of the
1651 <a href="#Dataset">Dataset</a> instance. A dictionary containing all the netCDF attribute
1652 name/value pairs is provided by the <code>__dict__</code> attribute of a
1653 <a href="#Dataset">Dataset</a> instance.</p>
1654
1655 <p>The following class variables are read-only and should not be
1656 modified by the user.</p>
1657
1658 <p><strong><code>dimensions</code></strong>: The <code>dimensions</code> dictionary maps the names of
1659 dimensions defined for the <a href="#Group">Group</a> or <a href="#Dataset">Dataset</a> to instances of the
1660 <a href="#Dimension">Dimension</a> class.</p>
1661
1662 <p><strong><code>variables</code></strong>: The <code>variables</code> dictionary maps the names of variables
1663 defined for this <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> to instances of the
1664 <a href="#Variable">Variable</a> class.</p>
1665
1666 <p><strong><code>groups</code></strong>: The groups dictionary maps the names of groups created for
1667 this <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> to instances of the <a href="#Group">Group</a> class (the
1668 <a href="#Dataset">Dataset</a> class is simply a special case of the <a href="#Group">Group</a> class which
1669 describes the root group in the netCDF4 file).</p>
1670
1671 <p><strong><code>cmptypes</code></strong>: The <code>cmptypes</code> dictionary maps the names of
1672 compound types defined for the <a href="#Group">Group</a> or <a href="#Dataset">Dataset</a> to instances of the
1673 <a href="#CompoundType">CompoundType</a> class.</p>
1674
1675 <p><strong><code>vltypes</code></strong>: The <code>vltypes</code> dictionary maps the names of
1676 variable-length types defined for the <a href="#Group">Group</a> or <a href="#Dataset">Dataset</a> to instances
1677 of the <a href="#VLType">VLType</a> class.</p>
1678
1679 <p><strong><code>enumtypes</code></strong>: The <code>enumtypes</code> dictionary maps the names of
1680 Enum types defined for the <a href="#Group">Group</a> or <a href="#Dataset">Dataset</a> to instances
1681 of the <a href="#EnumType">EnumType</a> class.</p>
1682
1683 <p><strong><code>data_model</code></strong>: <code>data_model</code> describes the netCDF
1684 data model version, one of <code>NETCDF3_CLASSIC</code>, <code>NETCDF4</code>,
1685 <code>NETCDF4_CLASSIC</code>, <code>NETCDF3_64BIT_OFFSET</code> or <code>NETCDF3_64BIT_DATA</code>.</p>
1686
1687 <p><strong><code>file_format</code></strong>: same as <code>data_model</code>, retained for backwards compatibility.</p>
1688
1689 <p><strong><code>disk_format</code></strong>: <code>disk_format</code> describes the underlying
1690 file format, one of <code>NETCDF3</code>, <code>HDF5</code>, <code>HDF4</code>,
1691 <code>PNETCDF</code>, <code>DAP2</code>, <code>DAP4</code> or <code>UNDEFINED</code>. Only available if using
1692 netcdf C library version &gt;= 4.3.1, otherwise will always return
1693 <code>UNDEFINED</code>.</p>
1694
1695 <p><strong><code>parent</code></strong>: <code>parent</code> is a reference to the parent
1696 <a href="#Group">Group</a> instance. <code>None</code> for the root group or <a href="#Dataset">Dataset</a>
1697 instance.</p>
1698
1699 <p><strong><code>path</code></strong>: <code>path</code> shows the location of the <a href="#Group">Group</a> in
1700 the <a href="#Dataset">Dataset</a> in a unix directory format (the names of groups in the
1701 hierarchy separated by backslashes). A <a href="#Dataset">Dataset</a> instance is the root
1702 group, so the path is simply <code>'/'</code>.</p>
1703
1704 <p><strong><code>keepweakref</code></strong>: If <code>True</code>, child Dimension and Variables objects only keep weak
1705 references to the parent Dataset or Group.</p>
1706
1707 <p><strong><code>_ncstring_attrs__</code></strong>: If <code>True</code>, all text attributes will be written as variable-length
1708 strings.</p>
1709 </div>
1710
1711
1712 <div id="Dataset.__init__" class="classattr">
1713 <div class="attr function"><a class="headerlink" href="#Dataset.__init__">#&nbsp;&nbsp</a>
1714
1715
1716 <span class="name">Dataset</span><span class="signature">(unknown)</span> </div>
1717
1718
1719 <div class="docstring"><p><strong><code>__init__(self, filename, mode="r", clobber=True, diskless=False,
1720 persist=False, keepweakref=False, memory=None, encoding=None,
1721 parallel=False, comm=None, info=None, format='NETCDF4')</code></strong></p>
1722
1723 <p><a href="#Dataset">Dataset</a> constructor.</p>
1724
1725 <p><strong><code>filename</code></strong>: Name of netCDF file to hold dataset. Can also
1726 be a python 3 pathlib instance or the URL of an OpenDAP dataset. When memory is
1727 set this is just used to set the <code>filepath()</code>.</p>
1728
1729 <p><strong><code>mode</code></strong>: access mode. <code>r</code> means read-only; no data can be
1730 modified. <code>w</code> means write; a new file is created, an existing file with
1731 the same name is deleted. <code>a</code> and <code>r+</code> mean append (in analogy with
1732 serial files); an existing file is opened for reading and writing.
1733 Appending <code>s</code> to modes <code>r</code>, <code>w</code>, <code>r+</code> or <code>a</code> will enable unbuffered shared
1734 access to <code>NETCDF3_CLASSIC</code>, <code>NETCDF3_64BIT_OFFSET</code> or
1735 <code>NETCDF3_64BIT_DATA</code> formatted files.
1736 Unbuffered access may be useful even if you don't need shared
1737 access, since it may be faster for programs that don't access data
1738 sequentially. This option is ignored for <code>NETCDF4</code> and <code>NETCDF4_CLASSIC</code>
1739 formatted files.</p>
1740
1741 <p><strong><code>clobber</code></strong>: if <code>True</code> (default), opening a file with <code>mode='w'</code>
1742 will clobber an existing file with the same name. if <code>False</code>, an
1743 exception will be raised if a file with the same name already exists.</p>
1744
1745 <p><strong><code>format</code></strong>: underlying file format (one of <code>'NETCDF4',
1746 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC'</code>, <code>'NETCDF3_64BIT_OFFSET'</code> or
1747 <code>'NETCDF3_64BIT_DATA'</code>.
1748 Only relevant if <code>mode = 'w'</code> (if <code>mode = 'r','a'</code> or <code>'r+'</code> the file format
1749 is automatically detected). Default <code>'NETCDF4'</code>, which means the data is
1750 stored in an HDF5 file, using netCDF 4 API features. Setting
1751 <code>format='NETCDF4_CLASSIC'</code> will create an HDF5 file, using only netCDF 3
1752 compatible API features. netCDF 3 clients must be recompiled and linked
1753 against the netCDF 4 library to read files in <code>NETCDF4_CLASSIC</code> format.
1754 <code>'NETCDF3_CLASSIC'</code> is the classic netCDF 3 file format that does not
1755 handle 2+ Gb files. <code>'NETCDF3_64BIT_OFFSET'</code> is the 64-bit offset
1756 version of the netCDF 3 file format, which fully supports 2+ GB files, but
1757 is only compatible with clients linked against netCDF version 3.6.0 or
1758 later. <code>'NETCDF3_64BIT_DATA'</code> is the 64-bit data version of the netCDF 3
1759 file format, which supports 64-bit dimension sizes plus unsigned and
1760 64 bit integer data types, but is only compatible with clients linked against
1761 netCDF version 4.4.0 or later.</p>
1762
1763 <p><strong><code>diskless</code></strong>: If <code>True</code>, create diskless (in-core) file.
1764 This is a feature added to the C library after the
1765 netcdf-4.2 release. If you need to access the memory buffer directly,
1766 use the in-memory feature instead (see <code>memory</code> kwarg).</p>
1767
1768 <p><strong><code>persist</code></strong>: if <code>diskless=True</code>, persist file to disk when closed
1769 (default <code>False</code>).</p>
1770
1771 <p><strong><code>keepweakref</code></strong>: if <code>True</code>, child Dimension and Variable instances will keep weak
1772 references to the parent Dataset or Group object. Default is <code>False</code>, which
1773 means strong references will be kept. Having Dimension and Variable instances
1774 keep a strong reference to the parent Dataset instance, which in turn keeps a
1775 reference to child Dimension and Variable instances, creates circular references.
1776 Circular references complicate garbage collection, which may mean increased
1777 memory usage for programs that create may Dataset instances with lots of
1778 Variables. It also will result in the Dataset object never being deleted, which
1779 means it may keep open files alive as well. Setting <code>keepweakref=True</code> allows
1780 Dataset instances to be garbage collected as soon as they go out of scope, potentially
1781 reducing memory usage and open file handles. However, in many cases this is not
1782 desirable, since the associated Variable instances may still be needed, but are
1783 rendered unusable when the parent Dataset instance is garbage collected.</p>
1784
1785 <p><strong><code>memory</code></strong>: if not <code>None</code>, create or open an in-memory Dataset.
1786 If mode = 'r', the memory kwarg must contain a memory buffer object
1787 (an object that supports the python buffer interface).
1788 The Dataset will then be created with contents taken from this block of memory.
1789 If mode = 'w', the memory kwarg should contain the anticipated size
1790 of the Dataset in bytes (used only for NETCDF3 files). A memory
1791 buffer containing a copy of the Dataset is returned by the
1792 <code><a href="#Dataset.close">Dataset.close</a></code> method. Requires netcdf-c version 4.4.1 for mode='r,
1793 netcdf-c 4.6.2 for mode='w'. To persist the file to disk, the raw
1794 bytes from the returned buffer can be written into a binary file.
1795 The Dataset can also be re-opened using this memory buffer.</p>
1796
1797 <p><strong><code>encoding</code></strong>: encoding used to encode filename string into bytes.
1798 Default is None (<code>sys.getdefaultfileencoding()</code> is used).</p>
1799
1800 <p><strong><code>parallel</code></strong>: open for parallel access using MPI (requires mpi4py and
1801 parallel-enabled netcdf-c and hdf5 libraries). Default is <code>False</code>. If
1802 <code>True</code>, <code>comm</code> and <code>info</code> kwargs may also be specified.</p>
1803
1804 <p><strong><code>comm</code></strong>: MPI_Comm object for parallel access. Default <code>None</code>, which
1805 means MPI_COMM_WORLD will be used. Ignored if <code>parallel=False</code>.</p>
1806
1807 <p><strong><code>info</code></strong>: MPI_Info object for parallel access. Default <code>None</code>, which
1808 means MPI_INFO_NULL will be used. Ignored if <code>parallel=False</code>.</p>
1809 </div>
1810
1811
1812 </div>
1813 <div id="Dataset.filepath" class="classattr">
1814 <div class="attr function"><a class="headerlink" href="#Dataset.filepath">#&nbsp;&nbsp</a>
1815
1816
1817 <span class="def">def</span>
1818 <span class="name">filepath</span><span class="signature">(unknown)</span>:
1819 </div>
1820
1821
1822 <div class="docstring"><p><strong><code>filepath(self,encoding=None)</code></strong></p>
1823
1824 <p>Get the file system path (or the opendap URL) which was used to
1825 open/create the Dataset. Requires netcdf &gt;= 4.1.2. The path
1826 is decoded into a string using <code>sys.getfilesystemencoding()</code> by default, this can be
1827 changed using the <code>encoding</code> kwarg.</p>
1828 </div>
1829
1830
1831 </div>
1832 <div id="Dataset.close" class="classattr">
1833 <div class="attr function"><a class="headerlink" href="#Dataset.close">#&nbsp;&nbsp</a>
1834
1835
1836 <span class="def">def</span>
1837 <span class="name">close</span><span class="signature">(unknown)</span>:
1838 </div>
1839
1840
1841 <div class="docstring"><p><strong><code>close(self)</code></strong></p>
1842
1843 <p>Close the Dataset.</p>
1844 </div>
1845
1846
1847 </div>
1848 <div id="Dataset.isopen" class="classattr">
1849 <div class="attr function"><a class="headerlink" href="#Dataset.isopen">#&nbsp;&nbsp</a>
1850
1851
1852 <span class="def">def</span>
1853 <span class="name">isopen</span><span class="signature">(unknown)</span>:
1854 </div>
1855
1856
1857 <div class="docstring"><p><strong><code>close(self)</code></strong></p>
1858
1859 <p>is the Dataset open or closed?</p>
1860 </div>
1861
1862
1863 </div>
1864 <div id="Dataset.sync" class="classattr">
1865 <div class="attr function"><a class="headerlink" href="#Dataset.sync">#&nbsp;&nbsp</a>
1866
1867
1868 <span class="def">def</span>
1869 <span class="name">sync</span><span class="signature">(unknown)</span>:
1870 </div>
1871
1872
1873 <div class="docstring"><p><strong><code>sync(self)</code></strong></p>
1874
1875 <p>Writes all buffered data in the <a href="#Dataset">Dataset</a> to the disk file.</p>
1876 </div>
1877
1878
1879 </div>
1880 <div id="Dataset.set_fill_on" class="classattr">
1881 <div class="attr function"><a class="headerlink" href="#Dataset.set_fill_on">#&nbsp;&nbsp</a>
1882
1883
1884 <span class="def">def</span>
1885 <span class="name">set_fill_on</span><span class="signature">(unknown)</span>:
1886 </div>
1887
1888
1889 <div class="docstring"><p><strong><code>set_fill_on(self)</code></strong></p>
1890
1891 <p>Sets the fill mode for a <a href="#Dataset">Dataset</a> open for writing to <code>on</code>.</p>
1892
1893 <p>This causes data to be pre-filled with fill values. The fill values can be
1894 controlled by the variable's <code>_Fill_Value</code> attribute, but is usually
1895 sufficient to the use the netCDF default <code>_Fill_Value</code> (defined
1896 separately for each variable type). The default behavior of the netCDF
1897 library corresponds to <code>set_fill_on</code>. Data which are equal to the
1898 <code>_Fill_Value</code> indicate that the variable was created, but never written
1899 to.</p>
1900 </div>
1901
1902
1903 </div>
1904 <div id="Dataset.set_fill_off" class="classattr">
1905 <div class="attr function"><a class="headerlink" href="#Dataset.set_fill_off">#&nbsp;&nbsp</a>
1906
1907
1908 <span class="def">def</span>
1909 <span class="name">set_fill_off</span><span class="signature">(unknown)</span>:
1910 </div>
1911
1912
1913 <div class="docstring"><p><strong><code>set_fill_off(self)</code></strong></p>
1914
1915 <p>Sets the fill mode for a <a href="#Dataset">Dataset</a> open for writing to <code>off</code>.</p>
1916
1917 <p>This will prevent the data from being pre-filled with fill values, which
1918 may result in some performance improvements. However, you must then make
1919 sure the data is actually written before being read.</p>
1920 </div>
1921
1922
1923 </div>
1924 <div id="Dataset.createDimension" class="classattr">
1925 <div class="attr function"><a class="headerlink" href="#Dataset.createDimension">#&nbsp;&nbsp</a>
1926
1927
1928 <span class="def">def</span>
1929 <span class="name">createDimension</span><span class="signature">(unknown)</span>:
1930 </div>
1931
1932
1933 <div class="docstring"><p><strong><code>createDimension(self, dimname, size=None)</code></strong></p>
1934
1935 <p>Creates a new dimension with the given <code>dimname</code> and <code>size</code>.</p>
1936
1937 <p><code>size</code> must be a positive integer or <code>None</code>, which stands for
1938 "unlimited" (default is <code>None</code>). Specifying a size of 0 also
1939 results in an unlimited dimension. The return value is the <a href="#Dimension">Dimension</a>
1940 class instance describing the new dimension. To determine the current
1941 maximum size of the dimension, use the <code>len</code> function on the <a href="#Dimension">Dimension</a>
1942 instance. To determine if a dimension is 'unlimited', use the
1943 <a href="#<a href="#Dimension.isunlimited">Dimension.isunlimited</a>"><a href="#Dimension.isunlimited">Dimension.isunlimited</a></a> method of the <a href="#Dimension">Dimension</a> instance.</p>
1944 </div>
1945
1946
1947 </div>
1948 <div id="Dataset.renameDimension" class="classattr">
1949 <div class="attr function"><a class="headerlink" href="#Dataset.renameDimension">#&nbsp;&nbsp</a>
1950
1951
1952 <span class="def">def</span>
1953 <span class="name">renameDimension</span><span class="signature">(unknown)</span>:
1954 </div>
1955
1956
1957 <div class="docstring"><p><strong><code>renameDimension(self, oldname, newname)</code></strong></p>
1958
1959 <p>rename a <a href="#Dimension">Dimension</a> named <code>oldname</code> to <code>newname</code>.</p>
1960 </div>
1961
1962
1963 </div>
1964 <div id="Dataset.createCompoundType" class="classattr">
1965 <div class="attr function"><a class="headerlink" href="#Dataset.createCompoundType">#&nbsp;&nbsp</a>
1966
1967
1968 <span class="def">def</span>
1969 <span class="name">createCompoundType</span><span class="signature">(unknown)</span>:
1970 </div>
1971
1972
1973 <div class="docstring"><p><strong><code>createCompoundType(self, datatype, datatype_name)</code></strong></p>
1974
1975 <p>Creates a new compound data type named <code>datatype_name</code> from the numpy
1976 dtype object <code>datatype</code>.</p>
1977
1978 <p><strong><em>Note</em></strong>: If the new compound data type contains other compound data types
1979 (i.e. it is a 'nested' compound type, where not all of the elements
1980 are homogeneous numeric data types), then the 'inner' compound types <strong>must</strong> be
1981 created first.</p>
1982
1983 <p>The return value is the <a href="#CompoundType">CompoundType</a> class instance describing the new
1984 datatype.</p>
1985 </div>
1986
1987
1988 </div>
1989 <div id="Dataset.createVLType" class="classattr">
1990 <div class="attr function"><a class="headerlink" href="#Dataset.createVLType">#&nbsp;&nbsp</a>
1991
1992
1993 <span class="def">def</span>
1994 <span class="name">createVLType</span><span class="signature">(unknown)</span>:
1995 </div>
1996
1997
1998 <div class="docstring"><p><strong><code>createVLType(self, datatype, datatype_name)</code></strong></p>
1999
2000 <p>Creates a new VLEN data type named <code>datatype_name</code> from a numpy
2001 dtype object <code>datatype</code>.</p>
2002
2003 <p>The return value is the <a href="#VLType">VLType</a> class instance describing the new
2004 datatype.</p>
2005 </div>
2006
2007
2008 </div>
2009 <div id="Dataset.createEnumType" class="classattr">
2010 <div class="attr function"><a class="headerlink" href="#Dataset.createEnumType">#&nbsp;&nbsp</a>
2011
2012
2013 <span class="def">def</span>
2014 <span class="name">createEnumType</span><span class="signature">(unknown)</span>:
2015 </div>
2016
2017
2018 <div class="docstring"><p><strong><code>createEnumType(self, datatype, datatype_name, enum_dict)</code></strong></p>
2019
2020 <p>Creates a new Enum data type named <code>datatype_name</code> from a numpy
2021 integer dtype object <code>datatype</code>, and a python dictionary
2022 defining the enum fields and values.</p>
2023
2024 <p>The return value is the <a href="#EnumType">EnumType</a> class instance describing the new
2025 datatype.</p>
2026 </div>
2027
2028
2029 </div>
2030 <div id="Dataset.createVariable" class="classattr">
2031 <div class="attr function"><a class="headerlink" href="#Dataset.createVariable">#&nbsp;&nbsp</a>
2032
2033
2034 <span class="def">def</span>
2035 <span class="name">createVariable</span><span class="signature">(unknown)</span>:
2036 </div>
2037
2038
2039 <div class="docstring"><p><strong><code>createVariable(self, varname, datatype, dimensions=(), zlib=False,
2040 complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None,
2041 endian='native', least_significant_digit=None, fill_value=None, chunk_cache=None)</code></strong></p>
2042
2043 <p>Creates a new variable with the given <code>varname</code>, <code>datatype</code>, and
2044 <code>dimensions</code>. If dimensions are not given, the variable is assumed to be
2045 a scalar.</p>
2046
2047 <p>If <code>varname</code> is specified as a path, using forward slashes as in unix to
2048 separate components, then intermediate groups will be created as necessary
2049 For example, <code>createVariable('/GroupA/GroupB/VarC', float, ('x','y'))</code> will create groups <code>GroupA</code>
2050 and <code>GroupA/GroupB</code>, plus the variable <code>GroupA/GroupB/VarC</code>, if the preceding
2051 groups don't already exist.</p>
2052
2053 <p>The <code>datatype</code> can be a numpy datatype object, or a string that describes
2054 a numpy dtype object (like the <code>dtype.str</code> attribute of a numpy array).
2055 Supported specifiers include: <code>'S1' or 'c' (NC_CHAR), 'i1' or 'b' or 'B'
2056 (NC_BYTE), 'u1' (NC_UBYTE), 'i2' or 'h' or 's' (NC_SHORT), 'u2'
2057 (NC_USHORT), 'i4' or 'i' or 'l' (NC_INT), 'u4' (NC_UINT), 'i8' (NC_INT64),
2058 'u8' (NC_UINT64), 'f4' or 'f' (NC_FLOAT), 'f8' or 'd' (NC_DOUBLE)</code>.
2059 <code>datatype</code> can also be a <a href="#CompoundType">CompoundType</a> instance
2060 (for a structured, or compound array), a <a href="#VLType">VLType</a> instance
2061 (for a variable-length array), or the python <code>str</code> builtin
2062 (for a variable-length string array). Numpy string and unicode datatypes with
2063 length greater than one are aliases for <code>str</code>.</p>
2064
2065 <p>Data from netCDF variables is presented to python as numpy arrays with
2066 the corresponding data type.</p>
2067
2068 <p><code>dimensions</code> must be a tuple containing dimension names (strings) that
2069 have been defined previously using <a href="#<a href="#Dataset.createDimension">Dataset.createDimension</a>"><a href="#Dataset.createDimension">Dataset.createDimension</a></a>. The default value
2070 is an empty tuple, which means the variable is a scalar.</p>
2071
2072 <p>If the optional keyword <code>zlib</code> is <code>True</code>, the data will be compressed in
2073 the netCDF file using gzip compression (default <code>False</code>).</p>
2074
2075 <p>The optional keyword <code>complevel</code> is an integer between 1 and 9 describing
2076 the level of compression desired (default 4). Ignored if <code>zlib=False</code>.</p>
2077
2078 <p>If the optional keyword <code>shuffle</code> is <code>True</code>, the HDF5 shuffle filter
2079 will be applied before compressing the data (default <code>True</code>). This
2080 significantly improves compression. Default is <code>True</code>. Ignored if
2081 <code>zlib=False</code>.</p>
2082
2083 <p>If the optional keyword <code>fletcher32</code> is <code>True</code>, the Fletcher32 HDF5
2084 checksum algorithm is activated to detect errors. Default <code>False</code>.</p>
2085
2086 <p>If the optional keyword <code>contiguous</code> is <code>True</code>, the variable data is
2087 stored contiguously on disk. Default <code>False</code>. Setting to <code>True</code> for
2088 a variable with an unlimited dimension will trigger an error.</p>
2089
2090 <p>The optional keyword <code>chunksizes</code> can be used to manually specify the
2091 HDF5 chunksizes for each dimension of the variable. A detailed
2092 discussion of HDF chunking and I/O performance is available
2093 <a href="http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html">here</a>.
2094 Basically, you want the chunk size for each dimension to match as
2095 closely as possible the size of the data block that users will read
2096 from the file. <code>chunksizes</code> cannot be set if <code>contiguous=True</code>.</p>
2097
2098 <p>The optional keyword <code>endian</code> can be used to control whether the
2099 data is stored in little or big endian format on disk. Possible
2100 values are <code>little, big</code> or <code>native</code> (default). The library
2101 will automatically handle endian conversions when the data is read,
2102 but if the data is always going to be read on a computer with the
2103 opposite format as the one used to create the file, there may be
2104 some performance advantage to be gained by setting the endian-ness.</p>
2105
2106 <p>The <code>zlib, complevel, shuffle, fletcher32, contiguous, chunksizes</code> and <code>endian</code>
2107 keywords are silently ignored for netCDF 3 files that do not use HDF5.</p>
2108
2109 <p>The optional keyword <code>fill_value</code> can be used to override the default
2110 netCDF <code>_FillValue</code> (the value that the variable gets filled with before
2111 any data is written to it, defaults given in <a href="#default_fillvals">default_fillvals</a>).
2112 If fill_value is set to <code>False</code>, then the variable is not pre-filled.</p>
2113
2114 <p>If the optional keyword parameter <code>least_significant_digit</code> is
2115 specified, variable data will be truncated (quantized). In conjunction
2116 with <code>zlib=True</code> this produces 'lossy', but significantly more
2117 efficient compression. For example, if <code>least_significant_digit=1</code>,
2118 data will be quantized using <code>numpy.around(scale*data)/scale</code>, where
2119 scale = 2**bits, and bits is determined so that a precision of 0.1 is
2120 retained (in this case bits=4). From the
2121 <a href="http://www.esrl.noaa.gov/psl/data/gridded/conventions/cdc_netcdf_standard.shtml">PSL metadata conventions</a>:
2122 "least_significant_digit -- power of ten of the smallest decimal place
2123 in unpacked data that is a reliable value." Default is <code>None</code>, or no
2124 quantization, or 'lossless' compression.</p>
2125
2126 <p>When creating variables in a <code>NETCDF4</code> or <code>NETCDF4_CLASSIC</code> formatted file,
2127 HDF5 creates something called a 'chunk cache' for each variable. The
2128 default size of the chunk cache may be large enough to completely fill
2129 available memory when creating thousands of variables. The optional
2130 keyword <code>chunk_cache</code> allows you to reduce (or increase) the size of
2131 the default chunk cache when creating a variable. The setting only
2132 persists as long as the Dataset is open - you can use the set_var_chunk_cache
2133 method to change it the next time the Dataset is opened.
2134 Warning - messing with this parameter can seriously degrade performance.</p>
2135
2136 <p>The return value is the <a href="#Variable">Variable</a> class instance describing the new
2137 variable.</p>
2138
2139 <p>A list of names corresponding to netCDF variable attributes can be
2140 obtained with the <a href="#Variable">Variable</a> method <a href="#<a href="#Variable.ncattrs">Variable.ncattrs</a>"><a href="#Variable.ncattrs">Variable.ncattrs</a></a>. A dictionary
2141 containing all the netCDF attribute name/value pairs is provided by
2142 the <code>__dict__</code> attribute of a <a href="#Variable">Variable</a> instance.</p>
2143
2144 <p><a href="#Variable">Variable</a> instances behave much like array objects. Data can be
2145 assigned to or retrieved from a variable with indexing and slicing
2146 operations on the <a href="#Variable">Variable</a> instance. A <a href="#Variable">Variable</a> instance has six
2147 Dataset standard attributes: <code>dimensions, dtype, shape, ndim, name</code> and
2148 <code>least_significant_digit</code>. Application programs should never modify
2149 these attributes. The <code>dimensions</code> attribute is a tuple containing the
2150 names of the dimensions associated with this variable. The <code>dtype</code>
2151 attribute is a string describing the variable's data type (<code>i4, f8,
2152 S1,</code> etc). The <code>shape</code> attribute is a tuple describing the current
2153 sizes of all the variable's dimensions. The <code>name</code> attribute is a
2154 string containing the name of the Variable instance.
2155 The <code>least_significant_digit</code>
2156 attributes describes the power of ten of the smallest decimal place in
2157 the data the contains a reliable value. assigned to the <a href="#Variable">Variable</a>
2158 instance. If <code>None</code>, the data is not truncated. The <code>ndim</code> attribute
2159 is the number of variable dimensions.</p>
2160 </div>
2161
2162
2163 </div>
2164 <div id="Dataset.renameVariable" class="classattr">
2165 <div class="attr function"><a class="headerlink" href="#Dataset.renameVariable">#&nbsp;&nbsp</a>
2166
2167
2168 <span class="def">def</span>
2169 <span class="name">renameVariable</span><span class="signature">(unknown)</span>:
2170 </div>
2171
2172
2173 <div class="docstring"><p><strong><code>renameVariable(self, oldname, newname)</code></strong></p>
2174
2175 <p>rename a <a href="#Variable">Variable</a> named <code>oldname</code> to <code>newname</code></p>
2176 </div>
2177
2178
2179 </div>
2180 <div id="Dataset.createGroup" class="classattr">
2181 <div class="attr function"><a class="headerlink" href="#Dataset.createGroup">#&nbsp;&nbsp</a>
2182
2183
2184 <span class="def">def</span>
2185 <span class="name">createGroup</span><span class="signature">(unknown)</span>:
2186 </div>
2187
2188
2189 <div class="docstring"><p><strong><code>createGroup(self, groupname)</code></strong></p>
2190
2191 <p>Creates a new <a href="#Group">Group</a> with the given <code>groupname</code>.</p>
2192
2193 <p>If <code>groupname</code> is specified as a path, using forward slashes as in unix to
2194 separate components, then intermediate groups will be created as necessary
2195 (analogous to <code>mkdir -p</code> in unix). For example,
2196 <code>createGroup('/GroupA/GroupB/GroupC')</code> will create <code>GroupA</code>,
2197 <code>GroupA/GroupB</code>, and <code>GroupA/GroupB/GroupC</code>, if they don't already exist.
2198 If the specified path describes a group that already exists, no error is
2199 raised.</p>
2200
2201 <p>The return value is a <a href="#Group">Group</a> class instance.</p>
2202 </div>
2203
2204
2205 </div>
2206 <div id="Dataset.ncattrs" class="classattr">
2207 <div class="attr function"><a class="headerlink" href="#Dataset.ncattrs">#&nbsp;&nbsp</a>
2208
2209
2210 <span class="def">def</span>
2211 <span class="name">ncattrs</span><span class="signature">(unknown)</span>:
2212 </div>
2213
2214
2215 <div class="docstring"><p><strong><code>ncattrs(self)</code></strong></p>
2216
2217 <p>return netCDF global attribute names for this <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> in a list.</p>
2218 </div>
2219
2220
2221 </div>
2222 <div id="Dataset.setncattr" class="classattr">
2223 <div class="attr function"><a class="headerlink" href="#Dataset.setncattr">#&nbsp;&nbsp</a>
2224
2225
2226 <span class="def">def</span>
2227 <span class="name">setncattr</span><span class="signature">(unknown)</span>:
2228 </div>
2229
2230
2231 <div class="docstring"><p><strong><code>setncattr(self,name,value)</code></strong></p>
2232
2233 <p>set a netCDF dataset or group attribute using name,value pair.
2234 Use if you need to set a netCDF attribute with the
2235 with the same name as one of the reserved python attributes.</p>
2236 </div>
2237
2238
2239 </div>
2240 <div id="Dataset.setncattr_string" class="classattr">
2241 <div class="attr function"><a class="headerlink" href="#Dataset.setncattr_string">#&nbsp;&nbsp</a>
2242
2243
2244 <span class="def">def</span>
2245 <span class="name">setncattr_string</span><span class="signature">(unknown)</span>:
2246 </div>
2247
2248
2249 <div class="docstring"><p><strong><code>setncattr_string(self,name,value)</code></strong></p>
2250
2251 <p>set a netCDF dataset or group string attribute using name,value pair.
2252 Use if you need to ensure that a netCDF attribute is created with type
2253 <code>NC_STRING</code> if the file format is <code>NETCDF4</code>.</p>
2254 </div>
2255
2256
2257 </div>
2258 <div id="Dataset.setncatts" class="classattr">
2259 <div class="attr function"><a class="headerlink" href="#Dataset.setncatts">#&nbsp;&nbsp</a>
2260
2261
2262 <span class="def">def</span>
2263 <span class="name">setncatts</span><span class="signature">(unknown)</span>:
2264 </div>
2265
2266
2267 <div class="docstring"><p><strong><code>setncatts(self,attdict)</code></strong></p>
2268
2269 <p>set a bunch of netCDF dataset or group attributes at once using a python dictionary.
2270 This may be faster when setting a lot of attributes for a <code>NETCDF3</code>
2271 formatted file, since nc_redef/nc_enddef is not called in between setting
2272 each attribute</p>
2273 </div>
2274
2275
2276 </div>
2277 <div id="Dataset.getncattr" class="classattr">
2278 <div class="attr function"><a class="headerlink" href="#Dataset.getncattr">#&nbsp;&nbsp</a>
2279
2280
2281 <span class="def">def</span>
2282 <span class="name">getncattr</span><span class="signature">(unknown)</span>:
2283 </div>
2284
2285
2286 <div class="docstring"><p><strong><code>getncattr(self,name)</code></strong></p>
2287
2288 <p>retrieve a netCDF dataset or group attribute.
2289 Use if you need to get a netCDF attribute with the same
2290 name as one of the reserved python attributes.</p>
2291
2292 <p>option kwarg <code>encoding</code> can be used to specify the
2293 character encoding of a string attribute (default is <code>utf-8</code>).</p>
2294 </div>
2295
2296
2297 </div>
2298 <div id="Dataset.delncattr" class="classattr">
2299 <div class="attr function"><a class="headerlink" href="#Dataset.delncattr">#&nbsp;&nbsp</a>
2300
2301
2302 <span class="def">def</span>
2303 <span class="name">delncattr</span><span class="signature">(unknown)</span>:
2304 </div>
2305
2306
2307 <div class="docstring"><p><strong><code>delncattr(self,name,value)</code></strong></p>
2308
2309 <p>delete a netCDF dataset or group attribute. Use if you need to delete a
2310 netCDF attribute with the same name as one of the reserved python
2311 attributes.</p>
2312 </div>
2313
2314
2315 </div>
2316 <div id="Dataset.renameAttribute" class="classattr">
2317 <div class="attr function"><a class="headerlink" href="#Dataset.renameAttribute">#&nbsp;&nbsp</a>
2318
2319
2320 <span class="def">def</span>
2321 <span class="name">renameAttribute</span><span class="signature">(unknown)</span>:
2322 </div>
2323
2324
2325 <div class="docstring"><p><strong><code>renameAttribute(self, oldname, newname)</code></strong></p>
2326
2327 <p>rename a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> attribute named <code>oldname</code> to <code>newname</code>.</p>
2328 </div>
2329
2330
2331 </div>
2332 <div id="Dataset.renameGroup" class="classattr">
2333 <div class="attr function"><a class="headerlink" href="#Dataset.renameGroup">#&nbsp;&nbsp</a>
2334
2335
2336 <span class="def">def</span>
2337 <span class="name">renameGroup</span><span class="signature">(unknown)</span>:
2338 </div>
2339
2340
2341 <div class="docstring"><p><strong><code>renameGroup(self, oldname, newname)</code></strong></p>
2342
2343 <p>rename a <a href="#Group">Group</a> named <code>oldname</code> to <code>newname</code> (requires netcdf &gt;= 4.3.1).</p>
2344 </div>
2345
2346
2347 </div>
2348 <div id="Dataset.set_auto_chartostring" class="classattr">
2349 <div class="attr function"><a class="headerlink" href="#Dataset.set_auto_chartostring">#&nbsp;&nbsp</a>
2350
2351
2352 <span class="def">def</span>
2353 <span class="name">set_auto_chartostring</span><span class="signature">(unknown)</span>:
2354 </div>
2355
2356
2357 <div class="docstring"><p><strong><code>set_auto_chartostring(self, True_or_False)</code></strong></p>
2358
2359 <p>Call <a href="#<a href="#Variable.set_auto_chartostring">Variable.set_auto_chartostring</a>"><a href="#Variable.set_auto_chartostring">Variable.set_auto_chartostring</a></a> for all variables contained in this <a href="#Dataset">Dataset</a> or
2360 <a href="#Group">Group</a>, as well as for all variables in all its subgroups.</p>
2361
2362 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion of
2363 all character arrays &lt;--> string arrays should be performed for
2364 character variables (variables of type <code>NC_CHAR</code> or <code>S1</code>) with the
2365 <code>_Encoding</code> attribute set.</p>
2366
2367 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
2368 after calling this function will follow the default behaviour.</p>
2369 </div>
2370
2371
2372 </div>
2373 <div id="Dataset.set_auto_maskandscale" class="classattr">
2374 <div class="attr function"><a class="headerlink" href="#Dataset.set_auto_maskandscale">#&nbsp;&nbsp</a>
2375
2376
2377 <span class="def">def</span>
2378 <span class="name">set_auto_maskandscale</span><span class="signature">(unknown)</span>:
2379 </div>
2380
2381
2382 <div class="docstring"><p><strong><code>set_auto_maskandscale(self, True_or_False)</code></strong></p>
2383
2384 <p>Call <a href="#<a href="#Variable.set_auto_maskandscale">Variable.set_auto_maskandscale</a>"><a href="#Variable.set_auto_maskandscale">Variable.set_auto_maskandscale</a></a> for all variables contained in this <a href="#Dataset">Dataset</a> or
2385 <a href="#Group">Group</a>, as well as for all variables in all its subgroups.</p>
2386
2387 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion to masked arrays
2388 and variable scaling shall be applied for all variables.</p>
2389
2390 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
2391 after calling this function will follow the default behaviour.</p>
2392 </div>
2393
2394
2395 </div>
2396 <div id="Dataset.set_auto_mask" class="classattr">
2397 <div class="attr function"><a class="headerlink" href="#Dataset.set_auto_mask">#&nbsp;&nbsp</a>
2398
2399
2400 <span class="def">def</span>
2401 <span class="name">set_auto_mask</span><span class="signature">(unknown)</span>:
2402 </div>
2403
2404
2405 <div class="docstring"><p><strong><code>set_auto_mask(self, True_or_False)</code></strong></p>
2406
2407 <p>Call <a href="#<a href="#Variable.set_auto_mask">Variable.set_auto_mask</a>"><a href="#Variable.set_auto_mask">Variable.set_auto_mask</a></a> for all variables contained in this <a href="#Dataset">Dataset</a> or
2408 <a href="#Group">Group</a>, as well as for all variables in all its subgroups.</p>
2409
2410 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion to masked arrays
2411 shall be applied for all variables.</p>
2412
2413 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
2414 after calling this function will follow the default behaviour.</p>
2415 </div>
2416
2417
2418 </div>
2419 <div id="Dataset.set_auto_scale" class="classattr">
2420 <div class="attr function"><a class="headerlink" href="#Dataset.set_auto_scale">#&nbsp;&nbsp</a>
2421
2422
2423 <span class="def">def</span>
2424 <span class="name">set_auto_scale</span><span class="signature">(unknown)</span>:
2425 </div>
2426
2427
2428 <div class="docstring"><p><strong><code>set_auto_scale(self, True_or_False)</code></strong></p>
2429
2430 <p>Call <a href="#<a href="#Variable.set_auto_scale">Variable.set_auto_scale</a>"><a href="#Variable.set_auto_scale">Variable.set_auto_scale</a></a> for all variables contained in this <a href="#Dataset">Dataset</a> or
2431 <a href="#Group">Group</a>, as well as for all variables in all its subgroups.</p>
2432
2433 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic variable scaling
2434 shall be applied for all variables.</p>
2435
2436 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
2437 after calling this function will follow the default behaviour.</p>
2438 </div>
2439
2440
2441 </div>
2442 <div id="Dataset.set_always_mask" class="classattr">
2443 <div class="attr function"><a class="headerlink" href="#Dataset.set_always_mask">#&nbsp;&nbsp</a>
2444
2445
2446 <span class="def">def</span>
2447 <span class="name">set_always_mask</span><span class="signature">(unknown)</span>:
2448 </div>
2449
2450
2451 <div class="docstring"><p><strong><code>set_always_mask(self, True_or_False)</code></strong></p>
2452
2453 <p>Call <a href="#<a href="#Variable.set_always_mask">Variable.set_always_mask</a>"><a href="#Variable.set_always_mask">Variable.set_always_mask</a></a> for all variables contained in
2454 this <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a>, as well as for all
2455 variables in all its subgroups.</p>
2456
2457 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion of
2458 masked arrays with no missing values to regular numpy arrays shall be
2459 applied for all variables. Default True. Set to False to restore the default behaviour
2460 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
2461 otherwise masked array returned).</p>
2462
2463 <p><strong><em>Note</em></strong>: Calling this function only affects existing
2464 variables. Variables created after calling this function will follow
2465 the default behaviour.</p>
2466 </div>
2467
2468
2469 </div>
2470 <div id="Dataset.set_ncstring_attrs" class="classattr">
2471 <div class="attr function"><a class="headerlink" href="#Dataset.set_ncstring_attrs">#&nbsp;&nbsp</a>
2472
2473
2474 <span class="def">def</span>
2475 <span class="name">set_ncstring_attrs</span><span class="signature">(unknown)</span>:
2476 </div>
2477
2478
2479 <div class="docstring"><p><strong><code>set_ncstring_attrs(self, True_or_False)</code></strong></p>
2480
2481 <p>Call <a href="#<a href="#Variable.set_ncstring_attrs">Variable.set_ncstring_attrs</a>"><a href="#Variable.set_ncstring_attrs">Variable.set_ncstring_attrs</a></a> for all variables contained in
2482 this <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a>, as well as for all its
2483 subgroups and their variables.</p>
2484
2485 <p><strong><code>True_or_False</code></strong>: Boolean determining if all string attributes are
2486 created as variable-length NC_STRINGs, (if True), or if ascii text
2487 attributes are stored as NC_CHARs (if False; default)</p>
2488
2489 <p><strong><em>Note</em></strong>: Calling this function only affects newly created attributes
2490 of existing (sub-) groups and their variables.</p>
2491 </div>
2492
2493
2494 </div>
2495 <div id="Dataset.get_variables_by_attributes" class="classattr">
2496 <div class="attr function"><a class="headerlink" href="#Dataset.get_variables_by_attributes">#&nbsp;&nbsp</a>
2497
2498
2499 <span class="def">def</span>
2500 <span class="name">get_variables_by_attributes</span><span class="signature">(unknown)</span>:
2501 </div>
2502
2503
2504 <div class="docstring"><p><strong><code>get_variables_by_attribute(self, **kwargs)</code></strong></p>
2505
2506 <p>Returns a list of variables that match specific conditions.</p>
2507
2508 <p>Can pass in key=value parameters and variables are returned that
2509 contain all of the matches. For example,</p>
2510
2511 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables with x-axis attribute.</span>
2512 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="s1">&#39;X&#39;</span><span class="p">)</span>
2513 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables with matching &quot;standard_name&quot; attribute</span>
2514 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">standard_name</span><span class="o">=</span><span class="s1">&#39;northward_sea_water_velocity&#39;</span><span class="p">)</span>
2515 </code></pre></div>
2516
2517 <p>Can pass in key=callable parameter and variables are returned if the
2518 callable returns True. The callable should accept a single parameter,
2519 the attribute value. None is given as the attribute value when the
2520 attribute does not exist on the variable. For example,</p>
2521
2522 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get Axis variables</span>
2523 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">&#39;X&#39;</span><span class="p">,</span> <span class="s1">&#39;Y&#39;</span><span class="p">,</span> <span class="s1">&#39;Z&#39;</span><span class="p">,</span> <span class="s1">&#39;T&#39;</span><span class="p">])</span>
2524 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables that don&#39;t have an &quot;axis&quot; attribute</span>
2525 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">)</span>
2526 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables that have a &quot;grid_mapping&quot; attribute</span>
2527 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">grid_mapping</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">)</span>
2528 </code></pre></div>
2529 </div>
2530
2531
2532 </div>
2533 <div id="Dataset.fromcdl" class="classattr">
2534 <div class="attr function"><a class="headerlink" href="#Dataset.fromcdl">#&nbsp;&nbsp</a>
2535
2536
2537 <span class="def">def</span>
2538 <span class="name">fromcdl</span><span class="signature">(unknown)</span>:
2539 </div>
2540
2541
2542 <div class="docstring"><p><strong><code>fromcdl(cdlfilename, ncfilename=None, mode='a',format='NETCDF4')</code></strong></p>
2543
2544 <p>call <code>ncgen</code> via subprocess to create Dataset from <a href="https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_utilities_guide.html#cdl_guide">CDL</a>
2545 text representation. Requires <code>ncgen</code> to be installed and in <code>$PATH</code>.</p>
2546
2547 <p><strong><code>cdlfilename</code></strong>: CDL file.</p>
2548
2549 <p><strong><code>ncfilename</code></strong>: netCDF file to create. If not given, CDL filename with
2550 suffix replaced by <code>.nc</code> is used..</p>
2551
2552 <p><strong><code>mode</code></strong>: Access mode to open Dataset (Default <code>'a'</code>).</p>
2553
2554 <p><strong><code>format</code></strong>: underlying file format to use (one of <code>'NETCDF4',
2555 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC'</code>, <code>'NETCDF3_64BIT_OFFSET'</code> or
2556 <code>'NETCDF3_64BIT_DATA'</code>. Default <code>'NETCDF4'</code>.</p>
2557
2558 <p>Dataset instance for <code>ncfilename</code> is returned.</p>
2559 </div>
2560
2561
2562 </div>
2563 <div id="Dataset.tocdl" class="classattr">
2564 <div class="attr function"><a class="headerlink" href="#Dataset.tocdl">#&nbsp;&nbsp</a>
2565
2566
2567 <span class="def">def</span>
2568 <span class="name">tocdl</span><span class="signature">(unknown)</span>:
2569 </div>
2570
2571
2572 <div class="docstring"><p><strong><code>tocdl(self, coordvars=False, data=False, outfile=None)</code></strong></p>
2573
2574 <p>call <code>ncdump</code> via subprocess to create <a href="https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_utilities_guide.html#cdl_guide">CDL</a>
2575 text representation of Dataset. Requires <code>ncdump</code> to be installed and in <code>$PATH</code>.</p>
2576
2577 <p><strong><code>coordvars</code></strong>: include coordinate variable data (via <code>ncdump -c</code>). Default False</p>
2578
2579 <p><strong><code>data</code></strong>: if True, write out variable data (Default False).</p>
2580
2581 <p><strong><code>outfile</code></strong>: If not None, file to output ncdump to. Default is to return a string.</p>
2582 </div>
2583
2584
2585 </div>
2586 <div id="Dataset.name" class="classattr">
2587 <div class="attr variable"><a class="headerlink" href="#Dataset.name">#&nbsp;&nbsp</a>
2588
2589 <span class="name">name</span><span class="default_value"> = &lt;attribute &#39;name&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2590 </div>
2591
2592
2593
2594 </div>
2595 <div id="Dataset.groups" class="classattr">
2596 <div class="attr variable"><a class="headerlink" href="#Dataset.groups">#&nbsp;&nbsp</a>
2597
2598 <span class="name">groups</span><span class="default_value"> = &lt;attribute &#39;groups&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2599 </div>
2600
2601
2602
2603 </div>
2604 <div id="Dataset.dimensions" class="classattr">
2605 <div class="attr variable"><a class="headerlink" href="#Dataset.dimensions">#&nbsp;&nbsp</a>
2606
2607 <span class="name">dimensions</span><span class="default_value"> = &lt;attribute &#39;dimensions&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2608 </div>
2609
2610
2611
2612 </div>
2613 <div id="Dataset.variables" class="classattr">
2614 <div class="attr variable"><a class="headerlink" href="#Dataset.variables">#&nbsp;&nbsp</a>
2615
2616 <span class="name">variables</span><span class="default_value"> = &lt;attribute &#39;variables&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2617 </div>
2618
2619
2620
2621 </div>
2622 <div id="Dataset.disk_format" class="classattr">
2623 <div class="attr variable"><a class="headerlink" href="#Dataset.disk_format">#&nbsp;&nbsp</a>
2624
2625 <span class="name">disk_format</span><span class="default_value"> = &lt;attribute &#39;disk_format&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2626 </div>
2627
2628
2629
2630 </div>
2631 <div id="Dataset.path" class="classattr">
2632 <div class="attr variable"><a class="headerlink" href="#Dataset.path">#&nbsp;&nbsp</a>
2633
2634 <span class="name">path</span><span class="default_value"> = &lt;attribute &#39;path&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2635 </div>
2636
2637
2638
2639 </div>
2640 <div id="Dataset.parent" class="classattr">
2641 <div class="attr variable"><a class="headerlink" href="#Dataset.parent">#&nbsp;&nbsp</a>
2642
2643 <span class="name">parent</span><span class="default_value"> = &lt;attribute &#39;parent&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2644 </div>
2645
2646
2647
2648 </div>
2649 <div id="Dataset.file_format" class="classattr">
2650 <div class="attr variable"><a class="headerlink" href="#Dataset.file_format">#&nbsp;&nbsp</a>
2651
2652 <span class="name">file_format</span><span class="default_value"> = &lt;attribute &#39;file_format&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2653 </div>
2654
2655
2656
2657 </div>
2658 <div id="Dataset.data_model" class="classattr">
2659 <div class="attr variable"><a class="headerlink" href="#Dataset.data_model">#&nbsp;&nbsp</a>
2660
2661 <span class="name">data_model</span><span class="default_value"> = &lt;attribute &#39;data_model&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2662 </div>
2663
2664
2665
2666 </div>
2667 <div id="Dataset.cmptypes" class="classattr">
2668 <div class="attr variable"><a class="headerlink" href="#Dataset.cmptypes">#&nbsp;&nbsp</a>
2669
2670 <span class="name">cmptypes</span><span class="default_value"> = &lt;attribute &#39;cmptypes&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2671 </div>
2672
2673
2674
2675 </div>
2676 <div id="Dataset.vltypes" class="classattr">
2677 <div class="attr variable"><a class="headerlink" href="#Dataset.vltypes">#&nbsp;&nbsp</a>
2678
2679 <span class="name">vltypes</span><span class="default_value"> = &lt;attribute &#39;vltypes&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2680 </div>
2681
2682
2683
2684 </div>
2685 <div id="Dataset.enumtypes" class="classattr">
2686 <div class="attr variable"><a class="headerlink" href="#Dataset.enumtypes">#&nbsp;&nbsp</a>
2687
2688 <span class="name">enumtypes</span><span class="default_value"> = &lt;attribute &#39;enumtypes&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2689 </div>
2690
2691
2692
2693 </div>
2694 <div id="Dataset.keepweakref" class="classattr">
2695 <div class="attr variable"><a class="headerlink" href="#Dataset.keepweakref">#&nbsp;&nbsp</a>
2696
2697 <span class="name">keepweakref</span><span class="default_value"> = &lt;attribute &#39;keepweakref&#39; of &#39;<a href="#Dataset">netCDF4._netCDF4.Dataset</a>&#39; objects&gt;</span>
2698 </div>
2699
2700
2701
2702 </div>
2703 </section>
2704 <section id="Group">
2705 <div class="attr class">
2706 <a class="headerlink" href="#Group">#&nbsp;&nbsp</a>
2707
2708
2709 <span class="def">class</span>
2710 <span class="name">Group</span>(<span class="base"><a href="#Dataset">Dataset</a></span>):
2711 </div>
2712
2713
2714 <div class="docstring"><p>Groups define a hierarchical namespace within a netCDF file. They are
2715 analogous to directories in a unix filesystem. Each <a href="#Group">Group</a> behaves like
2716 a <a href="#Dataset">Dataset</a> within a Dataset, and can contain it's own variables,
2717 dimensions and attributes (and other Groups). See <a href="#<a href="#Group.__init__">Group.__init__</a>"><a href="#Group.__init__">Group.__init__</a></a>
2718 for more details.</p>
2719
2720 <p><a href="#Group">Group</a> inherits from <a href="#Dataset">Dataset</a>, so all the
2721 <a href="#Dataset">Dataset</a> class methods and variables are available
2722 to a <a href="#Group">Group</a> instance (except the <code>close</code> method).</p>
2723
2724 <p>Additional read-only class variables:</p>
2725
2726 <p><strong><code>name</code></strong>: String describing the group name.</p>
2727 </div>
2728
2729
2730 <div id="Group.__init__" class="classattr">
2731 <div class="attr function"><a class="headerlink" href="#Group.__init__">#&nbsp;&nbsp</a>
2732
2733
2734 <span class="name">Group</span><span class="signature">(unknown)</span> </div>
2735
2736
2737 <div class="docstring"><p><strong><code>__init__(self, parent, name)</code></strong>
2738 <a href="#Group">Group</a> constructor.</p>
2739
2740 <p><strong><code>parent</code></strong>: <a href="#Group">Group</a> instance for the parent group. If being created
2741 in the root group, use a <a href="#Dataset">Dataset</a> instance.</p>
2742
2743 <p><strong><code>name</code></strong>: - Name of the group.</p>
2744
2745 <p><strong><em>Note</em></strong>: <a href="#Group">Group</a> instances should be created using the
2746 <a href="#<a href="#Dataset.createGroup">Dataset.createGroup</a>"><a href="#Dataset.createGroup">Dataset.createGroup</a></a> method of a <a href="#Dataset">Dataset</a> instance, or
2747 another <a href="#Group">Group</a> instance, not using this class directly.</p>
2748 </div>
2749
2750
2751 </div>
2752 <div id="Group.close" class="classattr">
2753 <div class="attr function"><a class="headerlink" href="#Group.close">#&nbsp;&nbsp</a>
2754
2755
2756 <span class="def">def</span>
2757 <span class="name">close</span><span class="signature">(unknown)</span>:
2758 </div>
2759
2760
2761 <div class="docstring"><p><strong><code>close(self)</code></strong></p>
2762
2763 <p>overrides <a href="#Dataset">Dataset</a> close method which does not apply to <a href="#Group">Group</a>
2764 instances, raises IOError.</p>
2765 </div>
2766
2767
2768 </div>
2769 <div class="inherited">
2770 <h5>Inherited Members</h5>
2771 <dl>
2772 <div><dt><a href="#Dataset">netCDF4._netCDF4.Dataset</a></dt>
2773 <dd id="Group.filepath" class="function"><a href="#Dataset.filepath">filepath</a></dd>
2774 <dd id="Group.isopen" class="function"><a href="#Dataset.isopen">isopen</a></dd>
2775 <dd id="Group.sync" class="function"><a href="#Dataset.sync">sync</a></dd>
2776 <dd id="Group.set_fill_on" class="function"><a href="#Dataset.set_fill_on">set_fill_on</a></dd>
2777 <dd id="Group.set_fill_off" class="function"><a href="#Dataset.set_fill_off">set_fill_off</a></dd>
2778 <dd id="Group.createDimension" class="function"><a href="#Dataset.createDimension">createDimension</a></dd>
2779 <dd id="Group.renameDimension" class="function"><a href="#Dataset.renameDimension">renameDimension</a></dd>
2780 <dd id="Group.createCompoundType" class="function"><a href="#Dataset.createCompoundType">createCompoundType</a></dd>
2781 <dd id="Group.createVLType" class="function"><a href="#Dataset.createVLType">createVLType</a></dd>
2782 <dd id="Group.createEnumType" class="function"><a href="#Dataset.createEnumType">createEnumType</a></dd>
2783 <dd id="Group.createVariable" class="function"><a href="#Dataset.createVariable">createVariable</a></dd>
2784 <dd id="Group.renameVariable" class="function"><a href="#Dataset.renameVariable">renameVariable</a></dd>
2785 <dd id="Group.createGroup" class="function"><a href="#Dataset.createGroup">createGroup</a></dd>
2786 <dd id="Group.ncattrs" class="function"><a href="#Dataset.ncattrs">ncattrs</a></dd>
2787 <dd id="Group.setncattr" class="function"><a href="#Dataset.setncattr">setncattr</a></dd>
2788 <dd id="Group.setncattr_string" class="function"><a href="#Dataset.setncattr_string">setncattr_string</a></dd>
2789 <dd id="Group.setncatts" class="function"><a href="#Dataset.setncatts">setncatts</a></dd>
2790 <dd id="Group.getncattr" class="function"><a href="#Dataset.getncattr">getncattr</a></dd>
2791 <dd id="Group.delncattr" class="function"><a href="#Dataset.delncattr">delncattr</a></dd>
2792 <dd id="Group.renameAttribute" class="function"><a href="#Dataset.renameAttribute">renameAttribute</a></dd>
2793 <dd id="Group.renameGroup" class="function"><a href="#Dataset.renameGroup">renameGroup</a></dd>
2794 <dd id="Group.set_auto_chartostring" class="function"><a href="#Dataset.set_auto_chartostring">set_auto_chartostring</a></dd>
2795 <dd id="Group.set_auto_maskandscale" class="function"><a href="#Dataset.set_auto_maskandscale">set_auto_maskandscale</a></dd>
2796 <dd id="Group.set_auto_mask" class="function"><a href="#Dataset.set_auto_mask">set_auto_mask</a></dd>
2797 <dd id="Group.set_auto_scale" class="function"><a href="#Dataset.set_auto_scale">set_auto_scale</a></dd>
2798 <dd id="Group.set_always_mask" class="function"><a href="#Dataset.set_always_mask">set_always_mask</a></dd>
2799 <dd id="Group.set_ncstring_attrs" class="function"><a href="#Dataset.set_ncstring_attrs">set_ncstring_attrs</a></dd>
2800 <dd id="Group.get_variables_by_attributes" class="function"><a href="#Dataset.get_variables_by_attributes">get_variables_by_attributes</a></dd>
2801 <dd id="Group.fromcdl" class="function"><a href="#Dataset.fromcdl">fromcdl</a></dd>
2802 <dd id="Group.tocdl" class="function"><a href="#Dataset.tocdl">tocdl</a></dd>
2803 <dd id="Group.name" class="variable"><a href="#Dataset.name">name</a></dd>
2804 <dd id="Group.groups" class="variable"><a href="#Dataset.groups">groups</a></dd>
2805 <dd id="Group.dimensions" class="variable"><a href="#Dataset.dimensions">dimensions</a></dd>
2806 <dd id="Group.variables" class="variable"><a href="#Dataset.variables">variables</a></dd>
2807 <dd id="Group.disk_format" class="variable"><a href="#Dataset.disk_format">disk_format</a></dd>
2808 <dd id="Group.path" class="variable"><a href="#Dataset.path">path</a></dd>
2809 <dd id="Group.parent" class="variable"><a href="#Dataset.parent">parent</a></dd>
2810 <dd id="Group.file_format" class="variable"><a href="#Dataset.file_format">file_format</a></dd>
2811 <dd id="Group.data_model" class="variable"><a href="#Dataset.data_model">data_model</a></dd>
2812 <dd id="Group.cmptypes" class="variable"><a href="#Dataset.cmptypes">cmptypes</a></dd>
2813 <dd id="Group.vltypes" class="variable"><a href="#Dataset.vltypes">vltypes</a></dd>
2814 <dd id="Group.enumtypes" class="variable"><a href="#Dataset.enumtypes">enumtypes</a></dd>
2815 <dd id="Group.keepweakref" class="variable"><a href="#Dataset.keepweakref">keepweakref</a></dd>
2816
2817 </div>
2818 </dl>
2819 </div>
2820 </section>
2821 <section id="Dimension">
2822 <div class="attr class">
2823 <a class="headerlink" href="#Dimension">#&nbsp;&nbsp</a>
2824
2825
2826 <span class="def">class</span>
2827 <span class="name">Dimension</span>:
2828 </div>
2829
2830
2831 <div class="docstring"><p>A netCDF <a href="#Dimension">Dimension</a> is used to describe the coordinates of a <a href="#Variable">Variable</a>.
2832 See <a href="#<a href="#Dimension.__init__">Dimension.__init__</a>"><a href="#Dimension.__init__">Dimension.__init__</a></a> for more details.</p>
2833
2834 <p>The current maximum size of a <a href="#Dimension">Dimension</a> instance can be obtained by
2835 calling the python <code>len</code> function on the <a href="#Dimension">Dimension</a> instance. The
2836 <a href="#<a href="#Dimension.isunlimited">Dimension.isunlimited</a>"><a href="#Dimension.isunlimited">Dimension.isunlimited</a></a> method of a <a href="#Dimension">Dimension</a> instance can be used to
2837 determine if the dimension is unlimited.</p>
2838
2839 <p>Read-only class variables:</p>
2840
2841 <p><strong><code>name</code></strong>: String name, used when creating a <a href="#Variable">Variable</a> with
2842 <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a>.</p>
2843
2844 <p><strong><code>size</code></strong>: Current <a href="#Dimension">Dimension</a> size (same as <code>len(d)</code>, where <code>d</code> is a
2845 <a href="#Dimension">Dimension</a> instance).</p>
2846 </div>
2847
2848
2849 <div id="Dimension.__init__" class="classattr">
2850 <div class="attr function"><a class="headerlink" href="#Dimension.__init__">#&nbsp;&nbsp</a>
2851
2852
2853 <span class="name">Dimension</span><span class="signature">(unknown)</span> </div>
2854
2855
2856 <div class="docstring"><p><strong><code>__init__(self, group, name, size=None)</code></strong></p>
2857
2858 <p><a href="#Dimension">Dimension</a> constructor.</p>
2859
2860 <p><strong><code>group</code></strong>: <a href="#Group">Group</a> instance to associate with dimension.</p>
2861
2862 <p><strong><code>name</code></strong>: Name of the dimension.</p>
2863
2864 <p><strong><code>size</code></strong>: Size of the dimension. <code>None</code> or 0 means unlimited. (Default <code>None</code>).</p>
2865
2866 <p><strong><em>Note</em></strong>: <a href="#Dimension">Dimension</a> instances should be created using the
2867 <a href="#<a href="#Dataset.createDimension">Dataset.createDimension</a>"><a href="#Dataset.createDimension">Dataset.createDimension</a></a> method of a <a href="#Group">Group</a> or
2868 <a href="#Dataset">Dataset</a> instance, not using <a href="#<a href="#Dimension.__init__">Dimension.__init__</a>"><a href="#Dimension.__init__">Dimension.__init__</a></a> directly.</p>
2869 </div>
2870
2871
2872 </div>
2873 <div id="Dimension.group" class="classattr">
2874 <div class="attr function"><a class="headerlink" href="#Dimension.group">#&nbsp;&nbsp</a>
2875
2876
2877 <span class="def">def</span>
2878 <span class="name">group</span><span class="signature">(unknown)</span>:
2879 </div>
2880
2881
2882 <div class="docstring"><p><strong><code>group(self)</code></strong></p>
2883
2884 <p>return the group that this <a href="#Dimension">Dimension</a> is a member of.</p>
2885 </div>
2886
2887
2888 </div>
2889 <div id="Dimension.isunlimited" class="classattr">
2890 <div class="attr function"><a class="headerlink" href="#Dimension.isunlimited">#&nbsp;&nbsp</a>
2891
2892
2893 <span class="def">def</span>
2894 <span class="name">isunlimited</span><span class="signature">(unknown)</span>:
2895 </div>
2896
2897
2898 <div class="docstring"><p><strong><code>isunlimited(self)</code></strong></p>
2899
2900 <p>returns <code>True</code> if the <a href="#Dimension">Dimension</a> instance is unlimited, <code>False</code> otherwise.</p>
2901 </div>
2902
2903
2904 </div>
2905 <div id="Dimension.name" class="classattr">
2906 <div class="attr variable"><a class="headerlink" href="#Dimension.name">#&nbsp;&nbsp</a>
2907
2908 <span class="name">name</span><span class="default_value"> = &lt;attribute &#39;name&#39; of &#39;<a href="#Dimension">netCDF4._netCDF4.Dimension</a>&#39; objects&gt;</span>
2909 </div>
2910
2911
2912
2913 </div>
2914 <div id="Dimension.size" class="classattr">
2915 <div class="attr variable"><a class="headerlink" href="#Dimension.size">#&nbsp;&nbsp</a>
2916
2917 <span class="name">size</span><span class="default_value"> = &lt;attribute &#39;size&#39; of &#39;<a href="#Dimension">netCDF4._netCDF4.Dimension</a>&#39; objects&gt;</span>
2918 </div>
2919
2920
2921
2922 </div>
2923 </section>
2924 <section id="Variable">
2925 <div class="attr class">
2926 <a class="headerlink" href="#Variable">#&nbsp;&nbsp</a>
2927
2928
2929 <span class="def">class</span>
2930 <span class="name">Variable</span>:
2931 </div>
2932
2933
2934 <div class="docstring"><p>A netCDF <a href="#Variable">Variable</a> is used to read and write netCDF data. They are
2935 analogous to numpy array objects. See <a href="#<a href="#Variable.__init__">Variable.__init__</a>"><a href="#Variable.__init__">Variable.__init__</a></a> for more
2936 details.</p>
2937
2938 <p>A list of attribute names corresponding to netCDF attributes defined for
2939 the variable can be obtained with the <a href="#<a href="#Variable.ncattrs">Variable.ncattrs</a>"><a href="#Variable.ncattrs">Variable.ncattrs</a></a> method. These
2940 attributes can be created by assigning to an attribute of the
2941 <a href="#Variable">Variable</a> instance. A dictionary containing all the netCDF attribute
2942 name/value pairs is provided by the <code>__dict__</code> attribute of a
2943 <a href="#Variable">Variable</a> instance.</p>
2944
2945 <p>The following class variables are read-only:</p>
2946
2947 <p><strong><code>dimensions</code></strong>: A tuple containing the names of the
2948 dimensions associated with this variable.</p>
2949
2950 <p><strong><code>dtype</code></strong>: A numpy dtype object describing the
2951 variable's data type.</p>
2952
2953 <p><strong><code>ndim</code></strong>: The number of variable dimensions.</p>
2954
2955 <p><strong><code>shape</code></strong>: A tuple with the current shape (length of all dimensions).</p>
2956
2957 <p><strong><code>scale</code></strong>: If True, <code>scale_factor</code> and <code>add_offset</code> are
2958 applied, and signed integer data is automatically converted to
2959 unsigned integer data if the <code>_Unsigned</code> attribute is set.
2960 Default is <code>True</code>, can be reset using <a href="#<a href="#Variable.set_auto_scale">Variable.set_auto_scale</a>"><a href="#Variable.set_auto_scale">Variable.set_auto_scale</a></a> and
2961 <a href="#<a href="#Variable.set_auto_maskandscale">Variable.set_auto_maskandscale</a>"><a href="#Variable.set_auto_maskandscale">Variable.set_auto_maskandscale</a></a> methods.</p>
2962
2963 <p><strong><code>mask</code></strong>: If True, data is automatically converted to/from masked
2964 arrays when missing values or fill values are present. Default is <code>True</code>, can be
2965 reset using <a href="#<a href="#Variable.set_auto_mask">Variable.set_auto_mask</a>"><a href="#Variable.set_auto_mask">Variable.set_auto_mask</a></a> and <a href="#<a href="#Variable.set_auto_maskandscale">Variable.set_auto_maskandscale</a>"><a href="#Variable.set_auto_maskandscale">Variable.set_auto_maskandscale</a></a>
2966 methods.</p>
2967
2968 <p><strong><code><a href="#chartostring">chartostring</a></code></strong>: If True, data is automatically converted to/from character
2969 arrays to string arrays when the <code>_Encoding</code> variable attribute is set.
2970 Default is <code>True</code>, can be reset using
2971 <a href="#<a href="#Variable.set_auto_chartostring">Variable.set_auto_chartostring</a>"><a href="#Variable.set_auto_chartostring">Variable.set_auto_chartostring</a></a> method.</p>
2972
2973 <p><strong><code>least_significant_digit</code></strong>: Describes the power of ten of the
2974 smallest decimal place in the data the contains a reliable value. Data is
2975 truncated to this decimal place when it is assigned to the <a href="#Variable">Variable</a>
2976 instance. If <code>None</code>, the data is not truncated.</p>
2977
2978 <p><strong><code>__orthogonal_indexing__</code></strong>: Always <code>True</code>. Indicates to client code
2979 that the object supports 'orthogonal indexing', which means that slices
2980 that are 1d arrays or lists slice along each dimension independently. This
2981 behavior is similar to Fortran or Matlab, but different than numpy.</p>
2982
2983 <p><strong><code>datatype</code></strong>: numpy data type (for primitive data types) or VLType/CompoundType
2984 instance (for compound or vlen data types).</p>
2985
2986 <p><strong><code>name</code></strong>: String name.</p>
2987
2988 <p><strong><code>size</code></strong>: The number of stored elements.</p>
2989 </div>
2990
2991
2992 <div id="Variable.__init__" class="classattr">
2993 <div class="attr function"><a class="headerlink" href="#Variable.__init__">#&nbsp;&nbsp</a>
2994
2995
2996 <span class="name">Variable</span><span class="signature">(unknown)</span> </div>
2997
2998
2999 <div class="docstring"><p><strong><code>__init__(self, group, name, datatype, dimensions=(), zlib=False,
3000 complevel=4, shuffle=True, fletcher32=False, contiguous=False,
3001 chunksizes=None, endian='native',
3002 least_significant_digit=None,fill_value=None,chunk_cache=None)</code></strong></p>
3003
3004 <p><a href="#Variable">Variable</a> constructor.</p>
3005
3006 <p><strong><code>group</code></strong>: <a href="#Group">Group</a> or <a href="#Dataset">Dataset</a> instance to associate with variable.</p>
3007
3008 <p><strong><code>name</code></strong>: Name of the variable.</p>
3009
3010 <p><strong><code>datatype</code></strong>: <a href="#Variable">Variable</a> data type. Can be specified by providing a
3011 numpy dtype object, or a string that describes a numpy dtype object.
3012 Supported values, corresponding to <code>str</code> attribute of numpy dtype
3013 objects, include <code>'f4'</code> (32-bit floating point), <code>'f8'</code> (64-bit floating
3014 point), <code>'i4'</code> (32-bit signed integer), <code>'i2'</code> (16-bit signed integer),
3015 <code>'i8'</code> (64-bit signed integer), <code>'i4'</code> (8-bit signed integer), <code>'i1'</code>
3016 (8-bit signed integer), <code>'u1'</code> (8-bit unsigned integer), <code>'u2'</code> (16-bit
3017 unsigned integer), <code>'u4'</code> (32-bit unsigned integer), <code>'u8'</code> (64-bit
3018 unsigned integer), or <code>'S1'</code> (single-character string). From
3019 compatibility with Scientific.IO.NetCDF, the old Numeric single character
3020 typecodes can also be used (<code>'f'</code> instead of <code>'f4'</code>, <code>'d'</code> instead of
3021 <code>'f8'</code>, <code>'h'</code> or <code>'s'</code> instead of <code>'i2'</code>, <code>'b'</code> or <code>'B'</code> instead of
3022 <code>'i1'</code>, <code>'c'</code> instead of <code>'S1'</code>, and <code>'i'</code> or <code>'l'</code> instead of
3023 <code>'i4'</code>). <code>datatype</code> can also be a <a href="#CompoundType">CompoundType</a> instance
3024 (for a structured, or compound array), a <a href="#VLType">VLType</a> instance
3025 (for a variable-length array), or the python <code>str</code> builtin
3026 (for a variable-length string array). Numpy string and unicode datatypes with
3027 length greater than one are aliases for <code>str</code>.</p>
3028
3029 <p><strong><code>dimensions</code></strong>: a tuple containing the variable's dimension names
3030 (defined previously with <code>createDimension</code>). Default is an empty tuple
3031 which means the variable is a scalar (and therefore has no dimensions).</p>
3032
3033 <p><strong><code>zlib</code></strong>: if <code>True</code>, data assigned to the <a href="#Variable">Variable</a>
3034 instance is compressed on disk. Default <code>False</code>.</p>
3035
3036 <p><strong><code>complevel</code></strong>: the level of zlib compression to use (1 is the fastest,
3037 but poorest compression, 9 is the slowest but best compression). Default 4.
3038 Ignored if <code>zlib=False</code>.</p>
3039
3040 <p><strong><code>shuffle</code></strong>: if <code>True</code>, the HDF5 shuffle filter is applied
3041 to improve compression. Default <code>True</code>. Ignored if <code>zlib=False</code>.</p>
3042
3043 <p><strong><code>fletcher32</code></strong>: if <code>True</code> (default <code>False</code>), the Fletcher32 checksum
3044 algorithm is used for error detection.</p>
3045
3046 <p><strong><code>contiguous</code></strong>: if <code>True</code> (default <code>False</code>), the variable data is
3047 stored contiguously on disk. Default <code>False</code>. Setting to <code>True</code> for
3048 a variable with an unlimited dimension will trigger an error.</p>
3049
3050 <p><strong><code>chunksizes</code></strong>: Can be used to specify the HDF5 chunksizes for each
3051 dimension of the variable. A detailed discussion of HDF chunking and I/O
3052 performance is available
3053 <a href="http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html">here</a>.
3054 Basically, you want the chunk size for each dimension to match as
3055 closely as possible the size of the data block that users will read
3056 from the file. <code>chunksizes</code> cannot be set if <code>contiguous=True</code>.</p>
3057
3058 <p><strong><code>endian</code></strong>: Can be used to control whether the
3059 data is stored in little or big endian format on disk. Possible
3060 values are <code>little, big</code> or <code>native</code> (default). The library
3061 will automatically handle endian conversions when the data is read,
3062 but if the data is always going to be read on a computer with the
3063 opposite format as the one used to create the file, there may be
3064 some performance advantage to be gained by setting the endian-ness.
3065 For netCDF 3 files (that don't use HDF5), only <code>endian='native'</code> is allowed.</p>
3066
3067 <p>The <code>zlib, complevel, shuffle, fletcher32, contiguous</code> and <code>chunksizes</code>
3068 keywords are silently ignored for netCDF 3 files that do not use HDF5.</p>
3069
3070 <p><strong><code>least_significant_digit</code></strong>: If specified, variable data will be
3071 truncated (quantized). In conjunction with <code>zlib=True</code> this produces
3072 'lossy', but significantly more efficient compression. For example, if
3073 <code>least_significant_digit=1</code>, data will be quantized using
3074 around(scale<em>data)/scale, where scale = 2</em>*bits, and bits is determined
3075 so that a precision of 0.1 is retained (in this case bits=4). Default is
3076 <code>None</code>, or no quantization.</p>
3077
3078 <p><strong><code>fill_value</code></strong>: If specified, the default netCDF <code>_FillValue</code> (the
3079 value that the variable gets filled with before any data is written to it)
3080 is replaced with this value. If fill_value is set to <code>False</code>, then
3081 the variable is not pre-filled. The default netCDF fill values can be found
3082 in <a href="#default_fillvals">default_fillvals</a>.</p>
3083
3084 <p><strong><code>chunk_cache</code></strong>: If specified, sets the chunk cache size for this variable.
3085 Persists as long as Dataset is open. Use <a href="#set_var_chunk_cache">set_var_chunk_cache</a> to
3086 change it when Dataset is re-opened. </p>
3087
3088 <p><strong><em>Note</em></strong>: <a href="#Variable">Variable</a> instances should be created using the
3089 <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> method of a <a href="#Dataset">Dataset</a> or
3090 <a href="#Group">Group</a> instance, not using this class directly.</p>
3091 </div>
3092
3093
3094 </div>
3095 <div id="Variable.group" class="classattr">
3096 <div class="attr function"><a class="headerlink" href="#Variable.group">#&nbsp;&nbsp</a>
3097
3098
3099 <span class="def">def</span>
3100 <span class="name">group</span><span class="signature">(unknown)</span>:
3101 </div>
3102
3103
3104 <div class="docstring"><p><strong><code>group(self)</code></strong></p>
3105
3106 <p>return the group that this <a href="#Variable">Variable</a> is a member of.</p>
3107 </div>
3108
3109
3110 </div>
3111 <div id="Variable.ncattrs" class="classattr">
3112 <div class="attr function"><a class="headerlink" href="#Variable.ncattrs">#&nbsp;&nbsp</a>
3113
3114
3115 <span class="def">def</span>
3116 <span class="name">ncattrs</span><span class="signature">(unknown)</span>:
3117 </div>
3118
3119
3120 <div class="docstring"><p><strong><code>ncattrs(self)</code></strong></p>
3121
3122 <p>return netCDF attribute names for this <a href="#Variable">Variable</a> in a list.</p>
3123 </div>
3124
3125
3126 </div>
3127 <div id="Variable.setncattr" class="classattr">
3128 <div class="attr function"><a class="headerlink" href="#Variable.setncattr">#&nbsp;&nbsp</a>
3129
3130
3131 <span class="def">def</span>
3132 <span class="name">setncattr</span><span class="signature">(unknown)</span>:
3133 </div>
3134
3135
3136 <div class="docstring"><p><strong><code>setncattr(self,name,value)</code></strong></p>
3137
3138 <p>set a netCDF variable attribute using name,value pair. Use if you need to set a
3139 netCDF attribute with the same name as one of the reserved python
3140 attributes.</p>
3141 </div>
3142
3143
3144 </div>
3145 <div id="Variable.setncattr_string" class="classattr">
3146 <div class="attr function"><a class="headerlink" href="#Variable.setncattr_string">#&nbsp;&nbsp</a>
3147
3148
3149 <span class="def">def</span>
3150 <span class="name">setncattr_string</span><span class="signature">(unknown)</span>:
3151 </div>
3152
3153
3154 <div class="docstring"><p><strong><code>setncattr_string(self,name,value)</code></strong></p>
3155
3156 <p>set a netCDF variable string attribute using name,value pair.
3157 Use if you need to ensure that a netCDF attribute is created with type
3158 <code>NC_STRING</code> if the file format is <code>NETCDF4</code>.
3159 Use if you need to set an attribute to an array of variable-length strings.</p>
3160 </div>
3161
3162
3163 </div>
3164 <div id="Variable.setncatts" class="classattr">
3165 <div class="attr function"><a class="headerlink" href="#Variable.setncatts">#&nbsp;&nbsp</a>
3166
3167
3168 <span class="def">def</span>
3169 <span class="name">setncatts</span><span class="signature">(unknown)</span>:
3170 </div>
3171
3172
3173 <div class="docstring"><p><strong><code>setncatts(self,attdict)</code></strong></p>
3174
3175 <p>set a bunch of netCDF variable attributes at once using a python dictionary.
3176 This may be faster when setting a lot of attributes for a <code>NETCDF3</code>
3177 formatted file, since nc_redef/nc_enddef is not called in between setting
3178 each attribute</p>
3179 </div>
3180
3181
3182 </div>
3183 <div id="Variable.getncattr" class="classattr">
3184 <div class="attr function"><a class="headerlink" href="#Variable.getncattr">#&nbsp;&nbsp</a>
3185
3186
3187 <span class="def">def</span>
3188 <span class="name">getncattr</span><span class="signature">(unknown)</span>:
3189 </div>
3190
3191
3192 <div class="docstring"><p><strong><code>getncattr(self,name)</code></strong></p>
3193
3194 <p>retrieve a netCDF variable attribute. Use if you need to set a
3195 netCDF attribute with the same name as one of the reserved python
3196 attributes.</p>
3197
3198 <p>option kwarg <code>encoding</code> can be used to specify the
3199 character encoding of a string attribute (default is <code>utf-8</code>).</p>
3200 </div>
3201
3202
3203 </div>
3204 <div id="Variable.delncattr" class="classattr">
3205 <div class="attr function"><a class="headerlink" href="#Variable.delncattr">#&nbsp;&nbsp</a>
3206
3207
3208 <span class="def">def</span>
3209 <span class="name">delncattr</span><span class="signature">(unknown)</span>:
3210 </div>
3211
3212
3213 <div class="docstring"><p><strong><code>delncattr(self,name,value)</code></strong></p>
3214
3215 <p>delete a netCDF variable attribute. Use if you need to delete a
3216 netCDF attribute with the same name as one of the reserved python
3217 attributes.</p>
3218 </div>
3219
3220
3221 </div>
3222 <div id="Variable.filters" class="classattr">
3223 <div class="attr function"><a class="headerlink" href="#Variable.filters">#&nbsp;&nbsp</a>
3224
3225
3226 <span class="def">def</span>
3227 <span class="name">filters</span><span class="signature">(unknown)</span>:
3228 </div>
3229
3230
3231 <div class="docstring"><p><strong><code>filters(self)</code></strong></p>
3232
3233 <p>return dictionary containing HDF5 filter parameters.</p>
3234 </div>
3235
3236
3237 </div>
3238 <div id="Variable.endian" class="classattr">
3239 <div class="attr function"><a class="headerlink" href="#Variable.endian">#&nbsp;&nbsp</a>
3240
3241
3242 <span class="def">def</span>
3243 <span class="name">endian</span><span class="signature">(unknown)</span>:
3244 </div>
3245
3246
3247 <div class="docstring"><p><strong><code>endian(self)</code></strong></p>
3248
3249 <p>return endian-ness (<code>little,big,native</code>) of variable (as stored in HDF5 file).</p>
3250 </div>
3251
3252
3253 </div>
3254 <div id="Variable.chunking" class="classattr">
3255 <div class="attr function"><a class="headerlink" href="#Variable.chunking">#&nbsp;&nbsp</a>
3256
3257
3258 <span class="def">def</span>
3259 <span class="name">chunking</span><span class="signature">(unknown)</span>:
3260 </div>
3261
3262
3263 <div class="docstring"><p><strong><code>chunking(self)</code></strong></p>
3264
3265 <p>return variable chunking information. If the dataset is
3266 defined to be contiguous (and hence there is no chunking) the word 'contiguous'
3267 is returned. Otherwise, a sequence with the chunksize for
3268 each dimension is returned.</p>
3269 </div>
3270
3271
3272 </div>
3273 <div id="Variable.get_var_chunk_cache" class="classattr">
3274 <div class="attr function"><a class="headerlink" href="#Variable.get_var_chunk_cache">#&nbsp;&nbsp</a>
3275
3276
3277 <span class="def">def</span>
3278 <span class="name">get_var_chunk_cache</span><span class="signature">(unknown)</span>:
3279 </div>
3280
3281
3282 <div class="docstring"><p><strong><code>get_var_chunk_cache(self)</code></strong></p>
3283
3284 <p>return variable chunk cache information in a tuple (size,nelems,preemption).
3285 See netcdf C library documentation for <code>nc_get_var_chunk_cache</code> for
3286 details.</p>
3287 </div>
3288
3289
3290 </div>
3291 <div id="Variable.set_var_chunk_cache" class="classattr">
3292 <div class="attr function"><a class="headerlink" href="#Variable.set_var_chunk_cache">#&nbsp;&nbsp</a>
3293
3294
3295 <span class="def">def</span>
3296 <span class="name">set_var_chunk_cache</span><span class="signature">(unknown)</span>:
3297 </div>
3298
3299
3300 <div class="docstring"><p><strong><code>set_var_chunk_cache(self,size=None,nelems=None,preemption=None)</code></strong></p>
3301
3302 <p>change variable chunk cache settings.
3303 See netcdf C library documentation for <code>nc_set_var_chunk_cache</code> for
3304 details.</p>
3305 </div>
3306
3307
3308 </div>
3309 <div id="Variable.renameAttribute" class="classattr">
3310 <div class="attr function"><a class="headerlink" href="#Variable.renameAttribute">#&nbsp;&nbsp</a>
3311
3312
3313 <span class="def">def</span>
3314 <span class="name">renameAttribute</span><span class="signature">(unknown)</span>:
3315 </div>
3316
3317
3318 <div class="docstring"><p><strong><code>renameAttribute(self, oldname, newname)</code></strong></p>
3319
3320 <p>rename a <a href="#Variable">Variable</a> attribute named <code>oldname</code> to <code>newname</code>.</p>
3321 </div>
3322
3323
3324 </div>
3325 <div id="Variable.assignValue" class="classattr">
3326 <div class="attr function"><a class="headerlink" href="#Variable.assignValue">#&nbsp;&nbsp</a>
3327
3328
3329 <span class="def">def</span>
3330 <span class="name">assignValue</span><span class="signature">(unknown)</span>:
3331 </div>
3332
3333
3334 <div class="docstring"><p><strong><code>assignValue(self, val)</code></strong></p>
3335
3336 <p>assign a value to a scalar variable. Provided for compatibility with
3337 Scientific.IO.NetCDF, can also be done by assigning to an Ellipsis slice ([...]).</p>
3338 </div>
3339
3340
3341 </div>
3342 <div id="Variable.getValue" class="classattr">
3343 <div class="attr function"><a class="headerlink" href="#Variable.getValue">#&nbsp;&nbsp</a>
3344
3345
3346 <span class="def">def</span>
3347 <span class="name">getValue</span><span class="signature">(unknown)</span>:
3348 </div>
3349
3350
3351 <div class="docstring"><p><strong><code>getValue(self)</code></strong></p>
3352
3353 <p>get the value of a scalar variable. Provided for compatibility with
3354 Scientific.IO.NetCDF, can also be done by slicing with an Ellipsis ([...]).</p>
3355 </div>
3356
3357
3358 </div>
3359 <div id="Variable.set_auto_chartostring" class="classattr">
3360 <div class="attr function"><a class="headerlink" href="#Variable.set_auto_chartostring">#&nbsp;&nbsp</a>
3361
3362
3363 <span class="def">def</span>
3364 <span class="name">set_auto_chartostring</span><span class="signature">(unknown)</span>:
3365 </div>
3366
3367
3368 <div class="docstring"><p><strong><code>set_auto_chartostring(self,chartostring)</code></strong></p>
3369
3370 <p>turn on or off automatic conversion of character variable data to and
3371 from numpy fixed length string arrays when the <code>_Encoding</code> variable attribute
3372 is set.</p>
3373
3374 <p>If <code><a href="#chartostring">chartostring</a></code> is set to <code>True</code>, when data is read from a character variable
3375 (dtype = <code>S1</code>) that has an <code>_Encoding</code> attribute, it is converted to a numpy
3376 fixed length unicode string array (dtype = <code>UN</code>, where <code>N</code> is the length
3377 of the the rightmost dimension of the variable). The value of <code>_Encoding</code>
3378 is the unicode encoding that is used to decode the bytes into strings.</p>
3379
3380 <p>When numpy string data is written to a variable it is converted back to
3381 indiviual bytes, with the number of bytes in each string equalling the
3382 rightmost dimension of the variable.</p>
3383
3384 <p>The default value of <code><a href="#chartostring">chartostring</a></code> is <code>True</code>
3385 (automatic conversions are performed).</p>
3386 </div>
3387
3388
3389 </div>
3390 <div id="Variable.use_nc_get_vars" class="classattr">
3391 <div class="attr function"><a class="headerlink" href="#Variable.use_nc_get_vars">#&nbsp;&nbsp</a>
3392
3393
3394 <span class="def">def</span>
3395 <span class="name">use_nc_get_vars</span><span class="signature">(unknown)</span>:
3396 </div>
3397
3398
3399 <div class="docstring"><p><strong><code>use_nc_get_vars(self,_use_get_vars)</code></strong></p>
3400
3401 <p>enable the use of netcdf library routine <code>nc_get_vars</code>
3402 to retrieve strided variable slices. By default,
3403 <code>nc_get_vars</code> may not used by default (depending on the
3404 version of the netcdf-c library being used) since it may be
3405 slower than multiple calls to the unstrided read routine <code>nc_get_vara</code>.</p>
3406 </div>
3407
3408
3409 </div>
3410 <div id="Variable.set_auto_maskandscale" class="classattr">
3411 <div class="attr function"><a class="headerlink" href="#Variable.set_auto_maskandscale">#&nbsp;&nbsp</a>
3412
3413
3414 <span class="def">def</span>
3415 <span class="name">set_auto_maskandscale</span><span class="signature">(unknown)</span>:
3416 </div>
3417
3418
3419 <div class="docstring"><p><strong><code>set_auto_maskandscale(self,maskandscale)</code></strong></p>
3420
3421 <p>turn on or off automatic conversion of variable data to and
3422 from masked arrays, automatic packing/unpacking of variable
3423 data using <code>scale_factor</code> and <code>add_offset</code> attributes and
3424 automatic conversion of signed integer data to unsigned integer
3425 data if the <code>_Unsigned</code> attribute exists.</p>
3426
3427 <p>If <code>maskandscale</code> is set to <code>True</code>, when data is read from a variable
3428 it is converted to a masked array if any of the values are exactly
3429 equal to the either the netCDF _FillValue or the value specified by the
3430 missing_value variable attribute. The fill_value of the masked array
3431 is set to the missing_value attribute (if it exists), otherwise
3432 the netCDF _FillValue attribute (which has a default value
3433 for each data type). When data is written to a variable, the masked
3434 array is converted back to a regular numpy array by replacing all the
3435 masked values by the missing_value attribute of the variable (if it
3436 exists). If the variable has no missing_value attribute, the _FillValue
3437 is used instead. If the variable has valid_min/valid_max and
3438 missing_value attributes, data outside the specified range will be
3439 set to missing_value.</p>
3440
3441 <p>If <code>maskandscale</code> is set to <code>True</code>, and the variable has a
3442 <code>scale_factor</code> or an <code>add_offset</code> attribute, then data read
3443 from that variable is unpacked using::</p>
3444
3445 <pre><code>data = self.scale_factor*data + self.add_offset
3446 </code></pre>
3447
3448 <p>When data is written to a variable it is packed using::</p>
3449
3450 <pre><code>data = (data - self.add_offset)/self.scale_factor
3451 </code></pre>
3452
3453 <p>If either scale_factor is present, but add_offset is missing, add_offset
3454 is assumed zero. If add_offset is present, but scale_factor is missing,
3455 scale_factor is assumed to be one.
3456 For more information on how <code>scale_factor</code> and <code>add_offset</code> can be
3457 used to provide simple compression, see the
3458 <a href="http://www.esrl.noaa.gov/psl/data/gridded/conventions/cdc_netcdf_standard.shtml">PSL metadata conventions</a>.</p>
3459
3460 <p>In addition, if <code>maskandscale</code> is set to <code>True</code>, and if the variable has an
3461 attribute <code>_Unsigned</code> set, and the variable has a signed integer data type,
3462 a view to the data is returned with the corresponding unsigned integer data type.
3463 This convention is used by the netcdf-java library to save unsigned integer
3464 data in <code>NETCDF3</code> or <code>NETCDF4_CLASSIC</code> files (since the <code>NETCDF3</code>
3465 data model does not have unsigned integer data types).</p>
3466
3467 <p>The default value of <code>maskandscale</code> is <code>True</code>
3468 (automatic conversions are performed).</p>
3469 </div>
3470
3471
3472 </div>
3473 <div id="Variable.set_auto_scale" class="classattr">
3474 <div class="attr function"><a class="headerlink" href="#Variable.set_auto_scale">#&nbsp;&nbsp</a>
3475
3476
3477 <span class="def">def</span>
3478 <span class="name">set_auto_scale</span><span class="signature">(unknown)</span>:
3479 </div>
3480
3481
3482 <div class="docstring"><p><strong><code>set_auto_scale(self,scale)</code></strong></p>
3483
3484 <p>turn on or off automatic packing/unpacking of variable
3485 data using <code>scale_factor</code> and <code>add_offset</code> attributes.
3486 Also turns on and off automatic conversion of signed integer data
3487 to unsigned integer data if the variable has an <code>_Unsigned</code>
3488 attribute.</p>
3489
3490 <p>If <code>scale</code> is set to <code>True</code>, and the variable has a
3491 <code>scale_factor</code> or an <code>add_offset</code> attribute, then data read
3492 from that variable is unpacked using::</p>
3493
3494 <pre><code>data = self.scale_factor*data + self.add_offset
3495 </code></pre>
3496
3497 <p>When data is written to a variable it is packed using::</p>
3498
3499 <pre><code>data = (data - self.add_offset)/self.scale_factor
3500 </code></pre>
3501
3502 <p>If either scale_factor is present, but add_offset is missing, add_offset
3503 is assumed zero. If add_offset is present, but scale_factor is missing,
3504 scale_factor is assumed to be one.
3505 For more information on how <code>scale_factor</code> and <code>add_offset</code> can be
3506 used to provide simple compression, see the
3507 <a href="http://www.esrl.noaa.gov/psl/data/gridded/conventions/cdc_netcdf_standard.shtml">PSL metadata conventions</a>.</p>
3508
3509 <p>In addition, if <code>scale</code> is set to <code>True</code>, and if the variable has an
3510 attribute <code>_Unsigned</code> set, and the variable has a signed integer data type,
3511 a view to the data is returned with the corresponding unsigned integer datatype.
3512 This convention is used by the netcdf-java library to save unsigned integer
3513 data in <code>NETCDF3</code> or <code>NETCDF4_CLASSIC</code> files (since the <code>NETCDF3</code>
3514 data model does not have unsigned integer data types).</p>
3515
3516 <p>The default value of <code>scale</code> is <code>True</code>
3517 (automatic conversions are performed).</p>
3518 </div>
3519
3520
3521 </div>
3522 <div id="Variable.set_auto_mask" class="classattr">
3523 <div class="attr function"><a class="headerlink" href="#Variable.set_auto_mask">#&nbsp;&nbsp</a>
3524
3525
3526 <span class="def">def</span>
3527 <span class="name">set_auto_mask</span><span class="signature">(unknown)</span>:
3528 </div>
3529
3530
3531 <div class="docstring"><p><strong><code>set_auto_mask(self,mask)</code></strong></p>
3532
3533 <p>turn on or off automatic conversion of variable data to and
3534 from masked arrays .</p>
3535
3536 <p>If <code>mask</code> is set to <code>True</code>, when data is read from a variable
3537 it is converted to a masked array if any of the values are exactly
3538 equal to the either the netCDF _FillValue or the value specified by the
3539 missing_value variable attribute. The fill_value of the masked array
3540 is set to the missing_value attribute (if it exists), otherwise
3541 the netCDF _FillValue attribute (which has a default value
3542 for each data type). When data is written to a variable, the masked
3543 array is converted back to a regular numpy array by replacing all the
3544 masked values by the missing_value attribute of the variable (if it
3545 exists). If the variable has no missing_value attribute, the _FillValue
3546 is used instead. If the variable has valid_min/valid_max and
3547 missing_value attributes, data outside the specified range will be
3548 set to missing_value.</p>
3549
3550 <p>The default value of <code>mask</code> is <code>True</code>
3551 (automatic conversions are performed).</p>
3552 </div>
3553
3554
3555 </div>
3556 <div id="Variable.set_always_mask" class="classattr">
3557 <div class="attr function"><a class="headerlink" href="#Variable.set_always_mask">#&nbsp;&nbsp</a>
3558
3559
3560 <span class="def">def</span>
3561 <span class="name">set_always_mask</span><span class="signature">(unknown)</span>:
3562 </div>
3563
3564
3565 <div class="docstring"><p><strong><code>set_always_mask(self,always_mask)</code></strong></p>
3566
3567 <p>turn on or off conversion of data without missing values to regular
3568 numpy arrays.</p>
3569
3570 <p><code>always_mask</code> is a Boolean determining if automatic conversion of
3571 masked arrays with no missing values to regular numpy arrays shall be
3572 applied. Default is True. Set to False to restore the default behaviour
3573 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
3574 otherwise masked array returned).</p>
3575 </div>
3576
3577
3578 </div>
3579 <div id="Variable.set_ncstring_attrs" class="classattr">
3580 <div class="attr function"><a class="headerlink" href="#Variable.set_ncstring_attrs">#&nbsp;&nbsp</a>
3581
3582
3583 <span class="def">def</span>
3584 <span class="name">set_ncstring_attrs</span><span class="signature">(unknown)</span>:
3585 </div>
3586
3587
3588 <div class="docstring"><p><strong><code>set_always_mask(self,ncstring_attrs)</code></strong></p>
3589
3590 <p>turn on or off creating NC_STRING string attributes.</p>
3591
3592 <p>If <code>ncstring_attrs</code> is set to <code>True</code> then text attributes will be variable-length
3593 NC_STRINGs.</p>
3594
3595 <p>The default value of <code>ncstring_attrs</code> is <code>False</code> (writing ascii text attributes as
3596 NC_CHAR).</p>
3597 </div>
3598
3599
3600 </div>
3601 <div id="Variable.set_collective" class="classattr">
3602 <div class="attr function"><a class="headerlink" href="#Variable.set_collective">#&nbsp;&nbsp</a>
3603
3604
3605 <span class="def">def</span>
3606 <span class="name">set_collective</span><span class="signature">(unknown)</span>:
3607 </div>
3608
3609
3610 <div class="docstring"><p><strong><code>set_collective(self,True_or_False)</code></strong></p>
3611
3612 <p>turn on or off collective parallel IO access. Ignored if file is not
3613 open for parallel access.</p>
3614 </div>
3615
3616
3617 </div>
3618 <div id="Variable.get_dims" class="classattr">
3619 <div class="attr function"><a class="headerlink" href="#Variable.get_dims">#&nbsp;&nbsp</a>
3620
3621
3622 <span class="def">def</span>
3623 <span class="name">get_dims</span><span class="signature">(unknown)</span>:
3624 </div>
3625
3626
3627 <div class="docstring"><p><strong><code>get_dims(self)</code></strong></p>
3628
3629 <p>return a tuple of <a href="#Dimension">Dimension</a> instances associated with this
3630 <a href="#Variable">Variable</a>.</p>
3631 </div>
3632
3633
3634 </div>
3635 <div id="Variable.name" class="classattr">
3636 <div class="attr variable"><a class="headerlink" href="#Variable.name">#&nbsp;&nbsp</a>
3637
3638 <span class="name">name</span><span class="default_value"> = &lt;attribute &#39;name&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3639 </div>
3640
3641
3642
3643 </div>
3644 <div id="Variable.datatype" class="classattr">
3645 <div class="attr variable"><a class="headerlink" href="#Variable.datatype">#&nbsp;&nbsp</a>
3646
3647 <span class="name">datatype</span><span class="default_value"> = &lt;attribute &#39;datatype&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3648 </div>
3649
3650
3651
3652 </div>
3653 <div id="Variable.shape" class="classattr">
3654 <div class="attr variable"><a class="headerlink" href="#Variable.shape">#&nbsp;&nbsp</a>
3655
3656 <span class="name">shape</span><span class="default_value"> = &lt;attribute &#39;shape&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3657 </div>
3658
3659
3660
3661 </div>
3662 <div id="Variable.size" class="classattr">
3663 <div class="attr variable"><a class="headerlink" href="#Variable.size">#&nbsp;&nbsp</a>
3664
3665 <span class="name">size</span><span class="default_value"> = &lt;attribute &#39;size&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3666 </div>
3667
3668
3669
3670 </div>
3671 <div id="Variable.dimensions" class="classattr">
3672 <div class="attr variable"><a class="headerlink" href="#Variable.dimensions">#&nbsp;&nbsp</a>
3673
3674 <span class="name">dimensions</span><span class="default_value"> = &lt;attribute &#39;dimensions&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3675 </div>
3676
3677
3678
3679 </div>
3680 <div id="Variable.ndim" class="classattr">
3681 <div class="attr variable"><a class="headerlink" href="#Variable.ndim">#&nbsp;&nbsp</a>
3682
3683 <span class="name">ndim</span><span class="default_value"> = &lt;attribute &#39;ndim&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3684 </div>
3685
3686
3687
3688 </div>
3689 <div id="Variable.dtype" class="classattr">
3690 <div class="attr variable"><a class="headerlink" href="#Variable.dtype">#&nbsp;&nbsp</a>
3691
3692 <span class="name">dtype</span><span class="default_value"> = &lt;attribute &#39;dtype&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3693 </div>
3694
3695
3696
3697 </div>
3698 <div id="Variable.mask" class="classattr">
3699 <div class="attr variable"><a class="headerlink" href="#Variable.mask">#&nbsp;&nbsp</a>
3700
3701 <span class="name">mask</span><span class="default_value"> = &lt;attribute &#39;mask&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3702 </div>
3703
3704
3705
3706 </div>
3707 <div id="Variable.scale" class="classattr">
3708 <div class="attr variable"><a class="headerlink" href="#Variable.scale">#&nbsp;&nbsp</a>
3709
3710 <span class="name">scale</span><span class="default_value"> = &lt;attribute &#39;scale&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3711 </div>
3712
3713
3714
3715 </div>
3716 <div id="Variable.always_mask" class="classattr">
3717 <div class="attr variable"><a class="headerlink" href="#Variable.always_mask">#&nbsp;&nbsp</a>
3718
3719 <span class="name">always_mask</span><span class="default_value"> = &lt;attribute &#39;always_mask&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3720 </div>
3721
3722
3723
3724 </div>
3725 <div id="Variable.chartostring" class="classattr">
3726 <div class="attr variable"><a class="headerlink" href="#Variable.chartostring">#&nbsp;&nbsp</a>
3727
3728 <span class="name">chartostring</span><span class="default_value"> = &lt;attribute &#39;chartostring&#39; of &#39;<a href="#Variable">netCDF4._netCDF4.Variable</a>&#39; objects&gt;</span>
3729 </div>
3730
3731
3732
3733 </div>
3734 </section>
3735 <section id="CompoundType">
3736 <div class="attr class">
3737 <a class="headerlink" href="#CompoundType">#&nbsp;&nbsp</a>
3738
3739
3740 <span class="def">class</span>
3741 <span class="name">CompoundType</span>:
3742 </div>
3743
3744
3745 <div class="docstring"><p>A <a href="#CompoundType">CompoundType</a> instance is used to describe a compound data
3746 type, and can be passed to the the <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> method of
3747 a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance.
3748 Compound data types map to numpy structured arrays.
3749 See <a href="#<a href="#CompoundType.__init__">CompoundType.__init__</a>"><a href="#CompoundType.__init__">CompoundType.__init__</a></a> for more details.</p>
3750
3751 <p>The instance variables <code>dtype</code> and <code>name</code> should not be modified by
3752 the user.</p>
3753 </div>
3754
3755
3756 <div id="CompoundType.__init__" class="classattr">
3757 <div class="attr function"><a class="headerlink" href="#CompoundType.__init__">#&nbsp;&nbsp</a>
3758
3759
3760 <span class="name">CompoundType</span><span class="signature">(unknown)</span> </div>
3761
3762
3763 <div class="docstring"><p><strong><em><code>__init__(group, datatype, datatype_name)</code></em></strong></p>
3764
3765 <p>CompoundType constructor.</p>
3766
3767 <p><strong><code>group</code></strong>: <a href="#Group">Group</a> instance to associate with the compound datatype.</p>
3768
3769 <p><strong><code>datatype</code></strong>: A numpy dtype object describing a structured (a.k.a record)
3770 array. Can be composed of homogeneous numeric or character data types, or
3771 other structured array data types.</p>
3772
3773 <p><strong><code>datatype_name</code></strong>: a Python string containing a description of the
3774 compound data type.</p>
3775
3776 <p><strong><em>Note 1</em></strong>: When creating nested compound data types,
3777 the inner compound data types must already be associated with CompoundType
3778 instances (so create CompoundType instances for the innermost structures
3779 first).</p>
3780
3781 <p><strong><em>Note 2</em></strong>: <a href="#CompoundType">CompoundType</a> instances should be created using the
3782 <a href="#<a href="#Dataset.createCompoundType">Dataset.createCompoundType</a>"><a href="#Dataset.createCompoundType">Dataset.createCompoundType</a></a>
3783 method of a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance, not using this class directly.</p>
3784 </div>
3785
3786
3787 </div>
3788 <div id="CompoundType.dtype" class="classattr">
3789 <div class="attr variable"><a class="headerlink" href="#CompoundType.dtype">#&nbsp;&nbsp</a>
3790
3791 <span class="name">dtype</span><span class="default_value"> = &lt;attribute &#39;dtype&#39; of &#39;<a href="#CompoundType">netCDF4._netCDF4.CompoundType</a>&#39; objects&gt;</span>
3792 </div>
3793
3794
3795
3796 </div>
3797 <div id="CompoundType.dtype_view" class="classattr">
3798 <div class="attr variable"><a class="headerlink" href="#CompoundType.dtype_view">#&nbsp;&nbsp</a>
3799
3800 <span class="name">dtype_view</span><span class="default_value"> = &lt;attribute &#39;dtype_view&#39; of &#39;<a href="#CompoundType">netCDF4._netCDF4.CompoundType</a>&#39; objects&gt;</span>
3801 </div>
3802
3803
3804
3805 </div>
3806 <div id="CompoundType.name" class="classattr">
3807 <div class="attr variable"><a class="headerlink" href="#CompoundType.name">#&nbsp;&nbsp</a>
3808
3809 <span class="name">name</span><span class="default_value"> = &lt;attribute &#39;name&#39; of &#39;<a href="#CompoundType">netCDF4._netCDF4.CompoundType</a>&#39; objects&gt;</span>
3810 </div>
3811
3812
3813
3814 </div>
3815 </section>
3816 <section id="VLType">
3817 <div class="attr class">
3818 <a class="headerlink" href="#VLType">#&nbsp;&nbsp</a>
3819
3820
3821 <span class="def">class</span>
3822 <span class="name">VLType</span>:
3823 </div>
3824
3825
3826 <div class="docstring"><p>A <a href="#VLType">VLType</a> instance is used to describe a variable length (VLEN) data
3827 type, and can be passed to the the <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> method of
3828 a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance. See
3829 <a href="#<a href="#VLType.__init__">VLType.__init__</a>"><a href="#VLType.__init__">VLType.__init__</a></a>for more details.</p>
3830
3831 <p>The instance variables <code>dtype</code> and <code>name</code> should not be modified by
3832 the user.</p>
3833 </div>
3834
3835
3836 <div id="VLType.__init__" class="classattr">
3837 <div class="attr function"><a class="headerlink" href="#VLType.__init__">#&nbsp;&nbsp</a>
3838
3839
3840 <span class="name">VLType</span><span class="signature">(unknown)</span> </div>
3841
3842
3843 <div class="docstring"><p><strong><code>__init__(group, datatype, datatype_name)</code></strong></p>
3844
3845 <p>VLType constructor.</p>
3846
3847 <p><strong><code>group</code></strong>: <a href="#Group">Group</a> instance to associate with the VLEN datatype.</p>
3848
3849 <p><strong><code>datatype</code></strong>: An numpy dtype object describing the component type for the
3850 variable length array.</p>
3851
3852 <p><strong><code>datatype_name</code></strong>: a Python string containing a description of the
3853 VLEN data type.</p>
3854
3855 <p><strong><em><code>Note</code></em></strong>: <a href="#VLType">VLType</a> instances should be created using the
3856 <a href="#<a href="#Dataset.createVLType">Dataset.createVLType</a>"><a href="#Dataset.createVLType">Dataset.createVLType</a></a>
3857 method of a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance, not using this class directly.</p>
3858 </div>
3859
3860
3861 </div>
3862 <div id="VLType.dtype" class="classattr">
3863 <div class="attr variable"><a class="headerlink" href="#VLType.dtype">#&nbsp;&nbsp</a>
3864
3865 <span class="name">dtype</span><span class="default_value"> = &lt;attribute &#39;dtype&#39; of &#39;<a href="#VLType">netCDF4._netCDF4.VLType</a>&#39; objects&gt;</span>
3866 </div>
3867
3868
3869
3870 </div>
3871 <div id="VLType.name" class="classattr">
3872 <div class="attr variable"><a class="headerlink" href="#VLType.name">#&nbsp;&nbsp</a>
3873
3874 <span class="name">name</span><span class="default_value"> = &lt;attribute &#39;name&#39; of &#39;<a href="#VLType">netCDF4._netCDF4.VLType</a>&#39; objects&gt;</span>
3875 </div>
3876
3877
3878
3879 </div>
3880 </section>
3881 <section id="EnumType">
3882 <div class="attr class">
3883 <a class="headerlink" href="#EnumType">#&nbsp;&nbsp</a>
3884
3885
3886 <span class="def">class</span>
3887 <span class="name">EnumType</span>:
3888 </div>
3889
3890
3891 <div class="docstring"><p>A <a href="#EnumType">EnumType</a> instance is used to describe an Enum data
3892 type, and can be passed to the the <a href="#<a href="#Dataset.createVariable">Dataset.createVariable</a>"><a href="#Dataset.createVariable">Dataset.createVariable</a></a> method of
3893 a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance. See
3894 <a href="#<a href="#EnumType.__init__">EnumType.__init__</a>"><a href="#EnumType.__init__">EnumType.__init__</a></a> for more details.</p>
3895
3896 <p>The instance variables <code>dtype</code>, <code>name</code> and <code>enum_dict</code> should not be modified by
3897 the user.</p>
3898 </div>
3899
3900
3901 <div id="EnumType.__init__" class="classattr">
3902 <div class="attr function"><a class="headerlink" href="#EnumType.__init__">#&nbsp;&nbsp</a>
3903
3904
3905 <span class="name">EnumType</span><span class="signature">(unknown)</span> </div>
3906
3907
3908 <div class="docstring"><p><strong><code>__init__(group, datatype, datatype_name, enum_dict)</code></strong></p>
3909
3910 <p>EnumType constructor.</p>
3911
3912 <p><strong><code>group</code></strong>: <a href="#Group">Group</a> instance to associate with the VLEN datatype.</p>
3913
3914 <p><strong><code>datatype</code></strong>: An numpy integer dtype object describing the base type
3915 for the Enum.</p>
3916
3917 <p><strong><code>datatype_name</code></strong>: a Python string containing a description of the
3918 Enum data type.</p>
3919
3920 <p><strong><code>enum_dict</code></strong>: a Python dictionary containing the Enum field/value
3921 pairs.</p>
3922
3923 <p><strong><em><code>Note</code></em></strong>: <a href="#EnumType">EnumType</a> instances should be created using the
3924 <a href="#<a href="#Dataset.createEnumType">Dataset.createEnumType</a>"><a href="#Dataset.createEnumType">Dataset.createEnumType</a></a>
3925 method of a <a href="#Dataset">Dataset</a> or <a href="#Group">Group</a> instance, not using this class directly.</p>
3926 </div>
3927
3928
3929 </div>
3930 <div id="EnumType.dtype" class="classattr">
3931 <div class="attr variable"><a class="headerlink" href="#EnumType.dtype">#&nbsp;&nbsp</a>
3932
3933 <span class="name">dtype</span><span class="default_value"> = &lt;attribute &#39;dtype&#39; of &#39;<a href="#EnumType">netCDF4._netCDF4.EnumType</a>&#39; objects&gt;</span>
3934 </div>
3935
3936
3937
3938 </div>
3939 <div id="EnumType.name" class="classattr">
3940 <div class="attr variable"><a class="headerlink" href="#EnumType.name">#&nbsp;&nbsp</a>
3941
3942 <span class="name">name</span><span class="default_value"> = &lt;attribute &#39;name&#39; of &#39;<a href="#EnumType">netCDF4._netCDF4.EnumType</a>&#39; objects&gt;</span>
3943 </div>
3944
3945
3946
3947 </div>
3948 <div id="EnumType.enum_dict" class="classattr">
3949 <div class="attr variable"><a class="headerlink" href="#EnumType.enum_dict">#&nbsp;&nbsp</a>
3950
3951 <span class="name">enum_dict</span><span class="default_value"> = &lt;attribute &#39;enum_dict&#39; of &#39;<a href="#EnumType">netCDF4._netCDF4.EnumType</a>&#39; objects&gt;</span>
3952 </div>
3953
3954
3955
3956 </div>
3957 </section>
3958 <section id="getlibversion">
3959 <div class="attr function"><a class="headerlink" href="#getlibversion">#&nbsp;&nbsp</a>
3960
3961
3962 <span class="def">def</span>
3963 <span class="name">getlibversion</span><span class="signature">(unknown)</span>:
3964 </div>
3965
3966
3967 <div class="docstring"><p><strong><code><a href="#getlibversion">getlibversion()</a></code></strong></p>
3968
3969 <p>returns a string describing the version of the netcdf library
3970 used to build the module, and when it was built.</p>
3971 </div>
3972
3973
3974 </section>
3975 <section id="get_chunk_cache">
3976 <div class="attr function"><a class="headerlink" href="#get_chunk_cache">#&nbsp;&nbsp</a>
3977
3978
3979 <span class="def">def</span>
3980 <span class="name">get_chunk_cache</span><span class="signature">(unknown)</span>:
3981 </div>
3982
3983
3984 <div class="docstring"><p><strong><code><a href="#get_chunk_cache">get_chunk_cache()</a></code></strong></p>
3985
3986 <p>return current netCDF chunk cache information in a tuple (size,nelems,preemption).
3987 See netcdf C library documentation for <code>nc_get_chunk_cache</code> for
3988 details. Values can be reset with <a href="#set_chunk_cache">set_chunk_cache</a>.</p>
3989 </div>
3990
3991
3992 </section>
3993 <section id="set_chunk_cache">
3994 <div class="attr function"><a class="headerlink" href="#set_chunk_cache">#&nbsp;&nbsp</a>
3995
3996
3997 <span class="def">def</span>
3998 <span class="name">set_chunk_cache</span><span class="signature">(unknown)</span>:
3999 </div>
4000
4001
4002 <div class="docstring"><p><strong><code>set_chunk_cache(self,size=None,nelems=None,preemption=None)</code></strong></p>
4003
4004 <p>change netCDF4 chunk cache settings.
4005 See netcdf C library documentation for <code>nc_set_chunk_cache</code> for
4006 details.</p>
4007 </div>
4008
4009
4010 </section>
4011 <section id="stringtoarr">
4012 <div class="attr function"><a class="headerlink" href="#stringtoarr">#&nbsp;&nbsp</a>
4013
4014
4015 <span class="def">def</span>
4016 <span class="name">stringtoarr</span><span class="signature">(unknown)</span>:
4017 </div>
4018
4019
4020 <div class="docstring"><p><strong><code>stringtoarr(a, NUMCHARS,dtype='S')</code></strong></p>
4021
4022 <p>convert a string to a character array of length <code>NUMCHARS</code></p>
4023
4024 <p><strong><code>a</code></strong>: Input python string.</p>
4025
4026 <p><strong><code>NUMCHARS</code></strong>: number of characters used to represent string
4027 (if len(a) &lt; <code>NUMCHARS</code>, it will be padded on the right with blanks).</p>
4028
4029 <p><strong><code>dtype</code></strong>: type of numpy array to return. Default is <code>'S'</code>, which
4030 means an array of dtype <code>'S1'</code> will be returned. If dtype=<code>'U'</code>, a
4031 unicode array (dtype = <code>'U1'</code>) will be returned.</p>
4032
4033 <p>returns a rank 1 numpy character array of length NUMCHARS with datatype <code>'S1'</code>
4034 (default) or <code>'U1'</code> (if dtype=<code>'U'</code>)</p>
4035 </div>
4036
4037
4038 </section>
4039 <section id="stringtochar">
4040 <div class="attr function"><a class="headerlink" href="#stringtochar">#&nbsp;&nbsp</a>
4041
4042
4043 <span class="def">def</span>
4044 <span class="name">stringtochar</span><span class="signature">(unknown)</span>:
4045 </div>
4046
4047
4048 <div class="docstring"><p><strong><code>stringtochar(a,encoding='utf-8')</code></strong></p>
4049
4050 <p>convert a string array to a character array with one extra dimension</p>
4051
4052 <p><strong><code>a</code></strong>: Input numpy string array with numpy datatype <code>'SN'</code> or <code>'UN'</code>, where N
4053 is the number of characters in each string. Will be converted to
4054 an array of characters (datatype <code>'S1'</code> or <code>'U1'</code>) of shape <code>a.shape + (N,)</code>.</p>
4055
4056 <p>optional kwarg <code>encoding</code> can be used to specify character encoding (default
4057 <code>utf-8</code>). If <code>encoding</code> is 'none' or 'bytes', a <code>numpy.string_</code> the input array
4058 is treated a raw byte strings (<code>numpy.string_</code>).</p>
4059
4060 <p>returns a numpy character array with datatype <code>'S1'</code> or <code>'U1'</code>
4061 and shape <code>a.shape + (N,)</code>, where N is the length of each string in a.</p>
4062 </div>
4063
4064
4065 </section>
4066 <section id="chartostring">
4067 <div class="attr function"><a class="headerlink" href="#chartostring">#&nbsp;&nbsp</a>
4068
4069
4070 <span class="def">def</span>
4071 <span class="name">chartostring</span><span class="signature">(unknown)</span>:
4072 </div>
4073
4074
4075 <div class="docstring"><p><strong><code>chartostring(b,encoding='utf-8')</code></strong></p>
4076
4077 <p>convert a character array to a string array with one less dimension.</p>
4078
4079 <p><strong><code>b</code></strong>: Input character array (numpy datatype <code>'S1'</code> or <code>'U1'</code>).
4080 Will be converted to a array of strings, where each string has a fixed
4081 length of <code>b.shape[-1]</code> characters.</p>
4082
4083 <p>optional kwarg <code>encoding</code> can be used to specify character encoding (default
4084 <code>utf-8</code>). If <code>encoding</code> is 'none' or 'bytes', a <code>numpy.string_</code> btye array is
4085 returned.</p>
4086
4087 <p>returns a numpy string array with datatype <code>'UN'</code> (or <code>'SN'</code>) and shape
4088 <code>b.shape[:-1]</code> where where <code>N=b.shape[-1]</code>.</p>
4089 </div>
4090
4091
4092 </section>
4093 <section id="MFDataset">
4094 <div class="attr class">
4095 <a class="headerlink" href="#MFDataset">#&nbsp;&nbsp</a>
4096
4097
4098 <span class="def">class</span>
4099 <span class="name">MFDataset</span>(<span class="base"><a href="#Dataset">Dataset</a></span>):
4100 </div>
4101
4102
4103 <div class="docstring"><p>Class for reading multi-file netCDF Datasets, making variables
4104 spanning multiple files appear as if they were in one file.
4105 Datasets must be in <code>NETCDF4_CLASSIC, NETCDF3_CLASSIC, NETCDF3_64BIT_OFFSET
4106 or NETCDF3_64BIT_DATA</code> format (<code>NETCDF4</code> Datasets won't work).</p>
4107
4108 <p>Adapted from <a href="http://pysclint.sourceforge.net/pycdf">pycdf</a> by Andre Gosselin.</p>
4109
4110 <p>Example usage (See <a href="#<a href="#MFDataset.__init__">MFDataset.__init__</a>"><a href="#MFDataset.__init__">MFDataset.__init__</a></a> for more details):</p>
4111
4112 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
4113 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a series of netCDF files with a variable sharing</span>
4114 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># the same unlimited dimension.</span>
4115 <span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">nf</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
4116 <span class="o">...</span> <span class="k">with</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;mftest</span><span class="si">%s</span><span class="s2">.nc&quot;</span> <span class="o">%</span> <span class="n">nf</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;NETCDF4_CLASSIC&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
4117 <span class="o">...</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
4118 <span class="o">...</span> <span class="n">x</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="s2">&quot;i&quot;</span><span class="p">,(</span><span class="s2">&quot;x&quot;</span><span class="p">,))</span>
4119 <span class="o">...</span> <span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">]</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">nf</span><span class="o">*</span><span class="mi">10</span><span class="p">,</span><span class="mi">10</span><span class="o">*</span><span class="p">(</span><span class="n">nf</span><span class="o">+</span><span class="mi">1</span><span class="p">))</span>
4120 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># now read all those files in at once, in one Dataset.</span>
4121 <span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">MFDataset</span><span class="p">(</span><span class="s2">&quot;mftest*nc&quot;</span><span class="p">)</span>
4122 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;x&quot;</span><span class="p">][:])</span>
4123 <span class="p">[</span> <span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span> <span class="mi">5</span> <span class="mi">6</span> <span class="mi">7</span> <span class="mi">8</span> <span class="mi">9</span> <span class="mi">10</span> <span class="mi">11</span> <span class="mi">12</span> <span class="mi">13</span> <span class="mi">14</span> <span class="mi">15</span> <span class="mi">16</span> <span class="mi">17</span> <span class="mi">18</span> <span class="mi">19</span> <span class="mi">20</span> <span class="mi">21</span> <span class="mi">22</span> <span class="mi">23</span>
4124 <span class="mi">24</span> <span class="mi">25</span> <span class="mi">26</span> <span class="mi">27</span> <span class="mi">28</span> <span class="mi">29</span> <span class="mi">30</span> <span class="mi">31</span> <span class="mi">32</span> <span class="mi">33</span> <span class="mi">34</span> <span class="mi">35</span> <span class="mi">36</span> <span class="mi">37</span> <span class="mi">38</span> <span class="mi">39</span> <span class="mi">40</span> <span class="mi">41</span> <span class="mi">42</span> <span class="mi">43</span> <span class="mi">44</span> <span class="mi">45</span> <span class="mi">46</span> <span class="mi">47</span>
4125 <span class="mi">48</span> <span class="mi">49</span> <span class="mi">50</span> <span class="mi">51</span> <span class="mi">52</span> <span class="mi">53</span> <span class="mi">54</span> <span class="mi">55</span> <span class="mi">56</span> <span class="mi">57</span> <span class="mi">58</span> <span class="mi">59</span> <span class="mi">60</span> <span class="mi">61</span> <span class="mi">62</span> <span class="mi">63</span> <span class="mi">64</span> <span class="mi">65</span> <span class="mi">66</span> <span class="mi">67</span> <span class="mi">68</span> <span class="mi">69</span> <span class="mi">70</span> <span class="mi">71</span>
4126 <span class="mi">72</span> <span class="mi">73</span> <span class="mi">74</span> <span class="mi">75</span> <span class="mi">76</span> <span class="mi">77</span> <span class="mi">78</span> <span class="mi">79</span> <span class="mi">80</span> <span class="mi">81</span> <span class="mi">82</span> <span class="mi">83</span> <span class="mi">84</span> <span class="mi">85</span> <span class="mi">86</span> <span class="mi">87</span> <span class="mi">88</span> <span class="mi">89</span> <span class="mi">90</span> <span class="mi">91</span> <span class="mi">92</span> <span class="mi">93</span> <span class="mi">94</span> <span class="mi">95</span>
4127 <span class="mi">96</span> <span class="mi">97</span> <span class="mi">98</span> <span class="mi">99</span><span class="p">]</span>
4128 </code></pre></div>
4129 </div>
4130
4131
4132 <div id="MFDataset.__init__" class="classattr">
4133 <div class="attr function"><a class="headerlink" href="#MFDataset.__init__">#&nbsp;&nbsp</a>
4134
4135
4136 <span class="name">MFDataset</span><span class="signature">(files, check=False, aggdim=None, exclude=[], master_file=None)</span> </div>
4137
4138
4139 <div class="docstring"><p><strong><code>__init__(self, files, check=False, aggdim=None, exclude=[],
4140 master_file=None)</code></strong></p>
4141
4142 <p>Open a Dataset spanning multiple files, making it look as if it was a
4143 single file. Variables in the list of files that share the same
4144 dimension (specified with the keyword <code>aggdim</code>) are aggregated. If
4145 <code>aggdim</code> is not specified, the unlimited is aggregated. Currently,
4146 <code>aggdim</code> must be the leftmost (slowest varying) dimension of each
4147 of the variables to be aggregated.</p>
4148
4149 <p><strong><code>files</code></strong>: either a sequence of netCDF files or a string with a
4150 wildcard (converted to a sorted list of files using glob) If
4151 the <code>master_file</code> kwarg is not specified, the first file
4152 in the list will become the "master" file, defining all the
4153 variables with an aggregation dimension which may span
4154 subsequent files. Attribute access returns attributes only from "master"
4155 file. The files are always opened in read-only mode.</p>
4156
4157 <p><strong><code>check</code></strong>: True if you want to do consistency checking to ensure the
4158 correct variables structure for all of the netcdf files. Checking makes
4159 the initialization of the MFDataset instance much slower. Default is
4160 False.</p>
4161
4162 <p><strong><code>aggdim</code></strong>: The name of the dimension to aggregate over (must
4163 be the leftmost dimension of each of the variables to be aggregated).
4164 If None (default), aggregate over the unlimited dimension.</p>
4165
4166 <p><strong><code>exclude</code></strong>: A list of variable names to exclude from aggregation.
4167 Default is an empty list.</p>
4168
4169 <p><strong><code>master_file</code></strong>: file to use as "master file", defining all the
4170 variables with an aggregation dimension and all global attributes.</p>
4171 </div>
4172
4173
4174 </div>
4175 <div id="MFDataset.ncattrs" class="classattr">
4176 <div class="attr function"><a class="headerlink" href="#MFDataset.ncattrs">#&nbsp;&nbsp</a>
4177
4178
4179 <span class="def">def</span>
4180 <span class="name">ncattrs</span><span class="signature">(self)</span>:
4181 </div>
4182
4183
4184 <div class="docstring"><p><strong><code>ncattrs(self)</code></strong></p>
4185
4186 <p>return the netcdf attribute names from the master file.</p>
4187 </div>
4188
4189
4190 </div>
4191 <div id="MFDataset.close" class="classattr">
4192 <div class="attr function"><a class="headerlink" href="#MFDataset.close">#&nbsp;&nbsp</a>
4193
4194
4195 <span class="def">def</span>
4196 <span class="name">close</span><span class="signature">(self)</span>:
4197 </div>
4198
4199
4200 <div class="docstring"><p><strong><code>close(self)</code></strong></p>
4201
4202 <p>close all the open files.</p>
4203 </div>
4204
4205
4206 </div>
4207 <div class="inherited">
4208 <h5>Inherited Members</h5>
4209 <dl>
4210 <div><dt><a href="#Dataset">netCDF4._netCDF4.Dataset</a></dt>
4211 <dd id="MFDataset.filepath" class="function"><a href="#Dataset.filepath">filepath</a></dd>
4212 <dd id="MFDataset.isopen" class="function"><a href="#Dataset.isopen">isopen</a></dd>
4213 <dd id="MFDataset.sync" class="function"><a href="#Dataset.sync">sync</a></dd>
4214 <dd id="MFDataset.set_fill_on" class="function"><a href="#Dataset.set_fill_on">set_fill_on</a></dd>
4215 <dd id="MFDataset.set_fill_off" class="function"><a href="#Dataset.set_fill_off">set_fill_off</a></dd>
4216 <dd id="MFDataset.createDimension" class="function"><a href="#Dataset.createDimension">createDimension</a></dd>
4217 <dd id="MFDataset.renameDimension" class="function"><a href="#Dataset.renameDimension">renameDimension</a></dd>
4218 <dd id="MFDataset.createCompoundType" class="function"><a href="#Dataset.createCompoundType">createCompoundType</a></dd>
4219 <dd id="MFDataset.createVLType" class="function"><a href="#Dataset.createVLType">createVLType</a></dd>
4220 <dd id="MFDataset.createEnumType" class="function"><a href="#Dataset.createEnumType">createEnumType</a></dd>
4221 <dd id="MFDataset.createVariable" class="function"><a href="#Dataset.createVariable">createVariable</a></dd>
4222 <dd id="MFDataset.renameVariable" class="function"><a href="#Dataset.renameVariable">renameVariable</a></dd>
4223 <dd id="MFDataset.createGroup" class="function"><a href="#Dataset.createGroup">createGroup</a></dd>
4224 <dd id="MFDataset.setncattr" class="function"><a href="#Dataset.setncattr">setncattr</a></dd>
4225 <dd id="MFDataset.setncattr_string" class="function"><a href="#Dataset.setncattr_string">setncattr_string</a></dd>
4226 <dd id="MFDataset.setncatts" class="function"><a href="#Dataset.setncatts">setncatts</a></dd>
4227 <dd id="MFDataset.getncattr" class="function"><a href="#Dataset.getncattr">getncattr</a></dd>
4228 <dd id="MFDataset.delncattr" class="function"><a href="#Dataset.delncattr">delncattr</a></dd>
4229 <dd id="MFDataset.renameAttribute" class="function"><a href="#Dataset.renameAttribute">renameAttribute</a></dd>
4230 <dd id="MFDataset.renameGroup" class="function"><a href="#Dataset.renameGroup">renameGroup</a></dd>
4231 <dd id="MFDataset.set_auto_chartostring" class="function"><a href="#Dataset.set_auto_chartostring">set_auto_chartostring</a></dd>
4232 <dd id="MFDataset.set_auto_maskandscale" class="function"><a href="#Dataset.set_auto_maskandscale">set_auto_maskandscale</a></dd>
4233 <dd id="MFDataset.set_auto_mask" class="function"><a href="#Dataset.set_auto_mask">set_auto_mask</a></dd>
4234 <dd id="MFDataset.set_auto_scale" class="function"><a href="#Dataset.set_auto_scale">set_auto_scale</a></dd>
4235 <dd id="MFDataset.set_always_mask" class="function"><a href="#Dataset.set_always_mask">set_always_mask</a></dd>
4236 <dd id="MFDataset.set_ncstring_attrs" class="function"><a href="#Dataset.set_ncstring_attrs">set_ncstring_attrs</a></dd>
4237 <dd id="MFDataset.get_variables_by_attributes" class="function"><a href="#Dataset.get_variables_by_attributes">get_variables_by_attributes</a></dd>
4238 <dd id="MFDataset.fromcdl" class="function"><a href="#Dataset.fromcdl">fromcdl</a></dd>
4239 <dd id="MFDataset.tocdl" class="function"><a href="#Dataset.tocdl">tocdl</a></dd>
4240 <dd id="MFDataset.name" class="variable"><a href="#Dataset.name">name</a></dd>
4241 <dd id="MFDataset.groups" class="variable"><a href="#Dataset.groups">groups</a></dd>
4242 <dd id="MFDataset.dimensions" class="variable"><a href="#Dataset.dimensions">dimensions</a></dd>
4243 <dd id="MFDataset.variables" class="variable"><a href="#Dataset.variables">variables</a></dd>
4244 <dd id="MFDataset.disk_format" class="variable"><a href="#Dataset.disk_format">disk_format</a></dd>
4245 <dd id="MFDataset.path" class="variable"><a href="#Dataset.path">path</a></dd>
4246 <dd id="MFDataset.parent" class="variable"><a href="#Dataset.parent">parent</a></dd>
4247 <dd id="MFDataset.file_format" class="variable"><a href="#Dataset.file_format">file_format</a></dd>
4248 <dd id="MFDataset.data_model" class="variable"><a href="#Dataset.data_model">data_model</a></dd>
4249 <dd id="MFDataset.cmptypes" class="variable"><a href="#Dataset.cmptypes">cmptypes</a></dd>
4250 <dd id="MFDataset.vltypes" class="variable"><a href="#Dataset.vltypes">vltypes</a></dd>
4251 <dd id="MFDataset.enumtypes" class="variable"><a href="#Dataset.enumtypes">enumtypes</a></dd>
4252 <dd id="MFDataset.keepweakref" class="variable"><a href="#Dataset.keepweakref">keepweakref</a></dd>
4253
4254 </div>
4255 </dl>
4256 </div>
4257 </section>
4258 <section id="MFTime">
4259 <div class="attr class">
4260 <a class="headerlink" href="#MFTime">#&nbsp;&nbsp</a>
4261
4262
4263 <span class="def">class</span>
4264 <span class="name">MFTime</span>(<span class="base"><a href="#_Variable">_Variable</a></span>):
4265 </div>
4266
4267
4268 <div class="docstring"><p>Class providing an interface to a MFDataset time Variable by imposing a unique common
4269 time unit and/or calendar to all files.</p>
4270
4271 <p>Example usage (See <a href="#<a href="#MFTime.__init__">MFTime.__init__</a>"><a href="#MFTime.__init__">MFTime.__init__</a></a> for more details):</p>
4272
4273 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">numpy</span>
4274 <span class="o">&gt;&gt;&gt;</span> <span class="n">f1</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;mftest_1.nc&quot;</span><span class="p">,</span><span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s2">&quot;NETCDF4_CLASSIC&quot;</span><span class="p">)</span>
4275 <span class="o">&gt;&gt;&gt;</span> <span class="n">f2</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;mftest_2.nc&quot;</span><span class="p">,</span><span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s2">&quot;NETCDF4_CLASSIC&quot;</span><span class="p">)</span>
4276 <span class="o">&gt;&gt;&gt;</span> <span class="n">f1</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
4277 <span class="o">&gt;&gt;&gt;</span> <span class="n">f2</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
4278 <span class="o">&gt;&gt;&gt;</span> <span class="n">t1</span> <span class="o">=</span> <span class="n">f1</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;i&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,))</span>
4279 <span class="o">&gt;&gt;&gt;</span> <span class="n">t2</span> <span class="o">=</span> <span class="n">f2</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;i&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,))</span>
4280 <span class="o">&gt;&gt;&gt;</span> <span class="n">t1</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;days since 2000-01-01&quot;</span>
4281 <span class="o">&gt;&gt;&gt;</span> <span class="n">t2</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;days since 2000-02-01&quot;</span>
4282 <span class="o">&gt;&gt;&gt;</span> <span class="n">t1</span><span class="o">.</span><span class="n">calendar</span> <span class="o">=</span> <span class="s2">&quot;standard&quot;</span>
4283 <span class="o">&gt;&gt;&gt;</span> <span class="n">t2</span><span class="o">.</span><span class="n">calendar</span> <span class="o">=</span> <span class="s2">&quot;standard&quot;</span>
4284 <span class="o">&gt;&gt;&gt;</span> <span class="n">t1</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">31</span><span class="p">)</span>
4285 <span class="o">&gt;&gt;&gt;</span> <span class="n">t2</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">30</span><span class="p">)</span>
4286 <span class="o">&gt;&gt;&gt;</span> <span class="n">f1</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
4287 <span class="o">&gt;&gt;&gt;</span> <span class="n">f2</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
4288 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Read the two files in at once, in one Dataset.</span>
4289 <span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">MFDataset</span><span class="p">(</span><span class="s2">&quot;mftest_*nc&quot;</span><span class="p">)</span>
4290 <span class="o">&gt;&gt;&gt;</span> <span class="n">t</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;time&quot;</span><span class="p">]</span>
4291 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">units</span><span class="p">)</span>
4292 <span class="n">days</span> <span class="n">since</span> <span class="mi">2000</span><span class="o">-</span><span class="mi">01</span><span class="o">-</span><span class="mi">01</span>
4293 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">t</span><span class="p">[</span><span class="mi">32</span><span class="p">])</span> <span class="c1"># The value written in the file, inconsistent with the MF time units.</span>
4294 <span class="mi">1</span>
4295 <span class="o">&gt;&gt;&gt;</span> <span class="n">T</span> <span class="o">=</span> <span class="n">MFTime</span><span class="p">(</span><span class="n">t</span><span class="p">)</span>
4296 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">T</span><span class="p">[</span><span class="mi">32</span><span class="p">])</span>
4297 <span class="mi">32</span>
4298 </code></pre></div>
4299 </div>
4300
4301
4302 <div id="MFTime.__init__" class="classattr">
4303 <div class="attr function"><a class="headerlink" href="#MFTime.__init__">#&nbsp;&nbsp</a>
4304
4305
4306 <span class="name">MFTime</span><span class="signature">(time, units=None, calendar=None)</span> </div>
4307
4308
4309 <div class="docstring"><p><strong><code>__init__(self, time, units=None, calendar=None)</code></strong></p>
4310
4311 <p>Create a time Variable with units consistent across a multifile
4312 dataset.</p>
4313
4314 <p><strong><code>time</code></strong>: Time variable from a <a href="#MFDataset">MFDataset</a>.</p>
4315
4316 <p><strong><code>units</code></strong>: Time units, for example, <code>'days since 1979-01-01'</code>. If <code>None</code>,
4317 use the units from the master variable.</p>
4318
4319 <p><strong><code>calendar</code></strong>: Calendar overload to use across all files, for example,
4320 <code>'standard'</code> or <code>'gregorian'</code>. If <code>None</code>, check that the calendar attribute
4321 is present on each variable and values are unique across files raising a
4322 <code>ValueError</code> otherwise.</p>
4323 </div>
4324
4325
4326 </div>
4327 <div class="inherited">
4328 <h5>Inherited Members</h5>
4329 <dl>
4330 <div><dt><a href="#_Variable">netCDF4._netCDF4._Variable</a></dt>
4331 <dd id="MFTime.typecode" class="function"><a href="#_Variable.typecode">typecode</a></dd>
4332 <dd id="MFTime.ncattrs" class="function"><a href="#_Variable.ncattrs">ncattrs</a></dd>
4333 <dd id="MFTime.set_auto_chartostring" class="function"><a href="#_Variable.set_auto_chartostring">set_auto_chartostring</a></dd>
4334 <dd id="MFTime.set_auto_maskandscale" class="function"><a href="#_Variable.set_auto_maskandscale">set_auto_maskandscale</a></dd>
4335 <dd id="MFTime.set_auto_mask" class="function"><a href="#_Variable.set_auto_mask">set_auto_mask</a></dd>
4336 <dd id="MFTime.set_auto_scale" class="function"><a href="#_Variable.set_auto_scale">set_auto_scale</a></dd>
4337 <dd id="MFTime.set_always_mask" class="function"><a href="#_Variable.set_always_mask">set_always_mask</a></dd>
4338
4339 </div>
4340 </dl>
4341 </div>
4342 </section>
4343 </main>
4344 </body>
4345 </html>
+0
-6644
docs/netCDF4/index.html less more
0 <!doctype html>
1 <head>
2 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
3 <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
4
5 <title>netCDF4 API documentation</title>
6 <meta name="description" content="Version 1.5.5
7 ---------------
8 - - -
9
10 Introduction
11 ============
12
13 netcdf4-python is a Python interface..." />
14
15 <link href='http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,300' rel='stylesheet' type='text/css'>
16
17 <style type="text/css">
18
19 * {
20 box-sizing: border-box;
21 }
22 /*! normalize.css v1.1.1 | MIT License | git.io/normalize */
23
24 /* ==========================================================================
25 HTML5 display definitions
26 ========================================================================== */
27
28 /**
29 * Correct `block` display not defined in IE 6/7/8/9 and Firefox 3.
30 */
31
32 article,
33 aside,
34 details,
35 figcaption,
36 figure,
37 footer,
38 header,
39 hgroup,
40 main,
41 nav,
42 section,
43 summary {
44 display: block;
45 }
46
47 /**
48 * Correct `inline-block` display not defined in IE 6/7/8/9 and Firefox 3.
49 */
50
51 audio,
52 canvas,
53 video {
54 display: inline-block;
55 *display: inline;
56 *zoom: 1;
57 }
58
59 /**
60 * Prevent modern browsers from displaying `audio` without controls.
61 * Remove excess height in iOS 5 devices.
62 */
63
64 audio:not([controls]) {
65 display: none;
66 height: 0;
67 }
68
69 /**
70 * Address styling not present in IE 7/8/9, Firefox 3, and Safari 4.
71 * Known issue: no IE 6 support.
72 */
73
74 [hidden] {
75 display: none;
76 }
77
78 /* ==========================================================================
79 Base
80 ========================================================================== */
81
82 /**
83 * 1. Prevent system color scheme's background color being used in Firefox, IE,
84 * and Opera.
85 * 2. Prevent system color scheme's text color being used in Firefox, IE, and
86 * Opera.
87 * 3. Correct text resizing oddly in IE 6/7 when body `font-size` is set using
88 * `em` units.
89 * 4. Prevent iOS text size adjust after orientation change, without disabling
90 * user zoom.
91 */
92
93 html {
94 background: #fff; /* 1 */
95 color: #000; /* 2 */
96 font-size: 100%; /* 3 */
97 -webkit-text-size-adjust: 100%; /* 4 */
98 -ms-text-size-adjust: 100%; /* 4 */
99 }
100
101 /**
102 * Address `font-family` inconsistency between `textarea` and other form
103 * elements.
104 */
105
106 html,
107 button,
108 input,
109 select,
110 textarea {
111 font-family: sans-serif;
112 }
113
114 /**
115 * Address margins handled incorrectly in IE 6/7.
116 */
117
118 body {
119 margin: 0;
120 }
121
122 /* ==========================================================================
123 Links
124 ========================================================================== */
125
126 /**
127 * Address `outline` inconsistency between Chrome and other browsers.
128 */
129
130 a:focus {
131 outline: thin dotted;
132 }
133
134 /**
135 * Improve readability when focused and also mouse hovered in all browsers.
136 */
137
138 a:active,
139 a:hover {
140 outline: 0;
141 }
142
143 /* ==========================================================================
144 Typography
145 ========================================================================== */
146
147 /**
148 * Address font sizes and margins set differently in IE 6/7.
149 * Address font sizes within `section` and `article` in Firefox 4+, Safari 5,
150 * and Chrome.
151 */
152
153 h1 {
154 font-size: 2em;
155 margin: 0.67em 0;
156 }
157
158 h2 {
159 font-size: 1.5em;
160 margin: 0.83em 0;
161 }
162
163 h3 {
164 font-size: 1.17em;
165 margin: 1em 0;
166 }
167
168 h4 {
169 font-size: 1em;
170 margin: 1.33em 0;
171 }
172
173 h5 {
174 font-size: 0.83em;
175 margin: 1.67em 0;
176 }
177
178 h6 {
179 font-size: 0.67em;
180 margin: 2.33em 0;
181 }
182
183 /**
184 * Address styling not present in IE 7/8/9, Safari 5, and Chrome.
185 */
186
187 abbr[title] {
188 border-bottom: 1px dotted;
189 }
190
191 /**
192 * Address style set to `bolder` in Firefox 3+, Safari 4/5, and Chrome.
193 */
194
195 b,
196 strong {
197 font-weight: bold;
198 }
199
200 blockquote {
201 margin: 1em 40px;
202 }
203
204 /**
205 * Address styling not present in Safari 5 and Chrome.
206 */
207
208 dfn {
209 font-style: italic;
210 }
211
212 /**
213 * Address differences between Firefox and other browsers.
214 * Known issue: no IE 6/7 normalization.
215 */
216
217 hr {
218 -moz-box-sizing: content-box;
219 box-sizing: content-box;
220 height: 0;
221 }
222
223 /**
224 * Address styling not present in IE 6/7/8/9.
225 */
226
227 mark {
228 background: #ff0;
229 color: #000;
230 }
231
232 /**
233 * Address margins set differently in IE 6/7.
234 */
235
236 p,
237 pre {
238 margin: 1em 0;
239 }
240
241 /**
242 * Correct font family set oddly in IE 6, Safari 4/5, and Chrome.
243 */
244
245 code,
246 kbd,
247 pre,
248 samp {
249 font-family: monospace, serif;
250 _font-family: 'courier new', monospace;
251 font-size: 1em;
252 }
253
254 /**
255 * Improve readability of pre-formatted text in all browsers.
256 */
257
258 pre {
259 white-space: pre;
260 white-space: pre-wrap;
261 word-wrap: break-word;
262 }
263
264 /**
265 * Address CSS quotes not supported in IE 6/7.
266 */
267
268 q {
269 quotes: none;
270 }
271
272 /**
273 * Address `quotes` property not supported in Safari 4.
274 */
275
276 q:before,
277 q:after {
278 content: '';
279 content: none;
280 }
281
282 /**
283 * Address inconsistent and variable font size in all browsers.
284 */
285
286 small {
287 font-size: 80%;
288 }
289
290 /**
291 * Prevent `sub` and `sup` affecting `line-height` in all browsers.
292 */
293
294 sub,
295 sup {
296 font-size: 75%;
297 line-height: 0;
298 position: relative;
299 vertical-align: baseline;
300 }
301
302 sup {
303 top: -0.5em;
304 }
305
306 sub {
307 bottom: -0.25em;
308 }
309
310 /* ==========================================================================
311 Lists
312 ========================================================================== */
313
314 /**
315 * Address margins set differently in IE 6/7.
316 */
317
318 dl,
319 menu,
320 ol,
321 ul {
322 margin: 1em 0;
323 }
324
325 dd {
326 margin: 0 0 0 40px;
327 }
328
329 /**
330 * Address paddings set differently in IE 6/7.
331 */
332
333 menu,
334 ol,
335 ul {
336 padding: 0 0 0 40px;
337 }
338
339 /**
340 * Correct list images handled incorrectly in IE 7.
341 */
342
343 nav ul,
344 nav ol {
345 list-style: none;
346 list-style-image: none;
347 }
348
349 /* ==========================================================================
350 Embedded content
351 ========================================================================== */
352
353 /**
354 * 1. Remove border when inside `a` element in IE 6/7/8/9 and Firefox 3.
355 * 2. Improve image quality when scaled in IE 7.
356 */
357
358 img {
359 border: 0; /* 1 */
360 -ms-interpolation-mode: bicubic; /* 2 */
361 }
362
363 /**
364 * Correct overflow displayed oddly in IE 9.
365 */
366
367 svg:not(:root) {
368 overflow: hidden;
369 }
370
371 /* ==========================================================================
372 Figures
373 ========================================================================== */
374
375 /**
376 * Address margin not present in IE 6/7/8/9, Safari 5, and Opera 11.
377 */
378
379 figure {
380 margin: 0;
381 }
382
383 /* ==========================================================================
384 Forms
385 ========================================================================== */
386
387 /**
388 * Correct margin displayed oddly in IE 6/7.
389 */
390
391 form {
392 margin: 0;
393 }
394
395 /**
396 * Define consistent border, margin, and padding.
397 */
398
399 fieldset {
400 border: 1px solid #c0c0c0;
401 margin: 0 2px;
402 padding: 0.35em 0.625em 0.75em;
403 }
404
405 /**
406 * 1. Correct color not being inherited in IE 6/7/8/9.
407 * 2. Correct text not wrapping in Firefox 3.
408 * 3. Correct alignment displayed oddly in IE 6/7.
409 */
410
411 legend {
412 border: 0; /* 1 */
413 padding: 0;
414 white-space: normal; /* 2 */
415 *margin-left: -7px; /* 3 */
416 }
417
418 /**
419 * 1. Correct font size not being inherited in all browsers.
420 * 2. Address margins set differently in IE 6/7, Firefox 3+, Safari 5,
421 * and Chrome.
422 * 3. Improve appearance and consistency in all browsers.
423 */
424
425 button,
426 input,
427 select,
428 textarea {
429 font-size: 100%; /* 1 */
430 margin: 0; /* 2 */
431 vertical-align: baseline; /* 3 */
432 *vertical-align: middle; /* 3 */
433 }
434
435 /**
436 * Address Firefox 3+ setting `line-height` on `input` using `!important` in
437 * the UA stylesheet.
438 */
439
440 button,
441 input {
442 line-height: normal;
443 }
444
445 /**
446 * Address inconsistent `text-transform` inheritance for `button` and `select`.
447 * All other form control elements do not inherit `text-transform` values.
448 * Correct `button` style inheritance in Chrome, Safari 5+, and IE 6+.
449 * Correct `select` style inheritance in Firefox 4+ and Opera.
450 */
451
452 button,
453 select {
454 text-transform: none;
455 }
456
457 /**
458 * 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio`
459 * and `video` controls.
460 * 2. Correct inability to style clickable `input` types in iOS.
461 * 3. Improve usability and consistency of cursor style between image-type
462 * `input` and others.
463 * 4. Remove inner spacing in IE 7 without affecting normal text inputs.
464 * Known issue: inner spacing remains in IE 6.
465 */
466
467 button,
468 html input[type="button"], /* 1 */
469 input[type="reset"],
470 input[type="submit"] {
471 -webkit-appearance: button; /* 2 */
472 cursor: pointer; /* 3 */
473 *overflow: visible; /* 4 */
474 }
475
476 /**
477 * Re-set default cursor for disabled elements.
478 */
479
480 button[disabled],
481 html input[disabled] {
482 cursor: default;
483 }
484
485 /**
486 * 1. Address box sizing set to content-box in IE 8/9.
487 * 2. Remove excess padding in IE 8/9.
488 * 3. Remove excess padding in IE 7.
489 * Known issue: excess padding remains in IE 6.
490 */
491
492 input[type="checkbox"],
493 input[type="radio"] {
494 box-sizing: border-box; /* 1 */
495 padding: 0; /* 2 */
496 *height: 13px; /* 3 */
497 *width: 13px; /* 3 */
498 }
499
500 /**
501 * 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome.
502 * 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome
503 * (include `-moz` to future-proof).
504 */
505
506 input[type="search"] {
507 -webkit-appearance: textfield; /* 1 */
508 -moz-box-sizing: content-box;
509 -webkit-box-sizing: content-box; /* 2 */
510 box-sizing: content-box;
511 }
512
513 /**
514 * Remove inner padding and search cancel button in Safari 5 and Chrome
515 * on OS X.
516 */
517
518 input[type="search"]::-webkit-search-cancel-button,
519 input[type="search"]::-webkit-search-decoration {
520 -webkit-appearance: none;
521 }
522
523 /**
524 * Remove inner padding and border in Firefox 3+.
525 */
526
527 button::-moz-focus-inner,
528 input::-moz-focus-inner {
529 border: 0;
530 padding: 0;
531 }
532
533 /**
534 * 1. Remove default vertical scrollbar in IE 6/7/8/9.
535 * 2. Improve readability and alignment in all browsers.
536 */
537
538 textarea {
539 overflow: auto; /* 1 */
540 vertical-align: top; /* 2 */
541 }
542
543 /* ==========================================================================
544 Tables
545 ========================================================================== */
546
547 /**
548 * Remove most spacing between table cells.
549 */
550
551 table {
552 border-collapse: collapse;
553 border-spacing: 0;
554 }
555
556 </style>
557
558 <style type="text/css">
559
560 html, body {
561 margin: 0;
562 padding: 0;
563 min-height: 100%;
564 }
565 body {
566 background: #fff;
567 font-family: "Source Sans Pro", "Helvetica Neueue", Helvetica, sans;
568 font-weight: 300;
569 font-size: 16px;
570 line-height: 1.6em;
571 }
572 #content {
573 width: 70%;
574 max-width: 850px;
575 float: left;
576 padding: 30px 60px;
577 border-left: 1px solid #ddd;
578 }
579 #sidebar {
580 width: 25%;
581 float: left;
582 padding: 30px;
583 overflow: hidden;
584 }
585 #nav {
586 font-size: 130%;
587 margin: 0 0 15px 0;
588 }
589
590 #top {
591 display: block;
592 position: fixed;
593 bottom: 5px;
594 left: 5px;
595 font-size: .85em;
596 text-transform: uppercase;
597 }
598
599 #footer {
600 font-size: .75em;
601 padding: 5px 30px;
602 border-top: 1px solid #ddd;
603 text-align: right;
604 }
605 #footer p {
606 margin: 0 0 0 30px;
607 display: inline-block;
608 }
609
610 h1, h2, h3, h4, h5 {
611 font-weight: 300;
612 }
613 h1 {
614 font-size: 2.5em;
615 line-height: 1.1em;
616 margin: 0 0 .50em 0;
617 }
618
619 h2 {
620 font-size: 1.75em;
621 margin: 1em 0 .50em 0;
622 }
623
624 h3 {
625 margin: 25px 0 10px 0;
626 }
627
628 h4 {
629 margin: 0;
630 font-size: 105%;
631 }
632
633 a {
634 color: #058;
635 text-decoration: none;
636 transition: color .3s ease-in-out;
637 }
638
639 a:hover {
640 color: #e08524;
641 transition: color .3s ease-in-out;
642 }
643
644 pre, code, .mono, .name {
645 font-family: "Ubuntu Mono", "Cousine", "DejaVu Sans Mono", monospace;
646 }
647
648 .title .name {
649 font-weight: bold;
650 }
651 .section-title {
652 margin-top: 2em;
653 }
654 .ident {
655 color: #900;
656 }
657
658 code {
659 background: #f9f9f9;
660 }
661
662 pre {
663 background: #fefefe;
664 border: 1px solid #ddd;
665 box-shadow: 2px 2px 0 #f3f3f3;
666 margin: 0 30px;
667 padding: 15px 30px;
668 }
669
670 .codehilite {
671 margin: 0 30px 10px 30px;
672 }
673
674 .codehilite pre {
675 margin: 0;
676 }
677 .codehilite .err { background: #ff3300; color: #fff !important; }
678
679 table#module-list {
680 font-size: 110%;
681 }
682
683 table#module-list tr td:first-child {
684 padding-right: 10px;
685 white-space: nowrap;
686 }
687
688 table#module-list td {
689 vertical-align: top;
690 padding-bottom: 8px;
691 }
692
693 table#module-list td p {
694 margin: 0 0 7px 0;
695 }
696
697 .def {
698 display: table;
699 }
700
701 .def p {
702 display: table-cell;
703 vertical-align: top;
704 text-align: left;
705 }
706
707 .def p:first-child {
708 white-space: nowrap;
709 }
710
711 .def p:last-child {
712 width: 100%;
713 }
714
715
716 #index {
717 list-style-type: none;
718 margin: 0;
719 padding: 0;
720 }
721 ul#index .class_name {
722 /* font-size: 110%; */
723 font-weight: bold;
724 }
725 #index ul {
726 margin: 0;
727 }
728
729 .item {
730 margin: 0 0 15px 0;
731 }
732
733 .item .class {
734 margin: 0 0 25px 30px;
735 }
736
737 .item .class ul.class_list {
738 margin: 0 0 20px 0;
739 }
740
741 .item .name {
742 background: #fafafa;
743 margin: 0;
744 font-weight: bold;
745 padding: 5px 10px;
746 border-radius: 3px;
747 display: inline-block;
748 min-width: 40%;
749 }
750 .item .name:hover {
751 background: #f6f6f6;
752 }
753
754 .item .empty_desc {
755 margin: 0 0 5px 0;
756 padding: 0;
757 }
758
759 .item .inheritance {
760 margin: 3px 0 0 30px;
761 }
762
763 .item .inherited {
764 color: #666;
765 }
766
767 .item .desc {
768 padding: 0 8px;
769 margin: 0;
770 }
771
772 .item .desc p {
773 margin: 0 0 10px 0;
774 }
775
776 .source_cont {
777 margin: 0;
778 padding: 0;
779 }
780
781 .source_link a {
782 background: #ffc300;
783 font-weight: 400;
784 font-size: .75em;
785 text-transform: uppercase;
786 color: #fff;
787 text-shadow: 1px 1px 0 #f4b700;
788
789 padding: 3px 8px;
790 border-radius: 2px;
791 transition: background .3s ease-in-out;
792 }
793 .source_link a:hover {
794 background: #FF7200;
795 text-shadow: none;
796 transition: background .3s ease-in-out;
797 }
798
799 .source {
800 display: none;
801 max-height: 600px;
802 overflow-y: scroll;
803 margin-bottom: 15px;
804 }
805
806 .source .codehilite {
807 margin: 0;
808 }
809
810 .desc h1, .desc h2, .desc h3 {
811 font-size: 100% !important;
812 }
813 .clear {
814 clear: both;
815 }
816
817 @media all and (max-width: 950px) {
818 #sidebar {
819 width: 35%;
820 }
821 #content {
822 width: 65%;
823 }
824 }
825 @media all and (max-width: 650px) {
826 #top {
827 display: none;
828 }
829 #sidebar {
830 float: none;
831 width: auto;
832 }
833 #content {
834 float: none;
835 width: auto;
836 padding: 30px;
837 }
838
839 #index ul {
840 padding: 0;
841 margin-bottom: 15px;
842 }
843 #index ul li {
844 display: inline-block;
845 margin-right: 30px;
846 }
847 #footer {
848 text-align: left;
849 }
850 #footer p {
851 display: block;
852 margin: inherit;
853 }
854 }
855
856 /*****************************/
857
858 </style>
859
860 <style type="text/css">
861 .codehilite .hll { background-color: #ffffcc }
862 .codehilite { background: #f8f8f8; }
863 .codehilite .c { color: #408080; font-style: italic } /* Comment */
864 .codehilite .err { border: 1px solid #FF0000 } /* Error */
865 .codehilite .k { color: #008000; font-weight: bold } /* Keyword */
866 .codehilite .o { color: #666666 } /* Operator */
867 .codehilite .ch { color: #408080; font-style: italic } /* Comment.Hashbang */
868 .codehilite .cm { color: #408080; font-style: italic } /* Comment.Multiline */
869 .codehilite .cp { color: #BC7A00 } /* Comment.Preproc */
870 .codehilite .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */
871 .codehilite .c1 { color: #408080; font-style: italic } /* Comment.Single */
872 .codehilite .cs { color: #408080; font-style: italic } /* Comment.Special */
873 .codehilite .gd { color: #A00000 } /* Generic.Deleted */
874 .codehilite .ge { font-style: italic } /* Generic.Emph */
875 .codehilite .gr { color: #FF0000 } /* Generic.Error */
876 .codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */
877 .codehilite .gi { color: #00A000 } /* Generic.Inserted */
878 .codehilite .go { color: #888888 } /* Generic.Output */
879 .codehilite .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
880 .codehilite .gs { font-weight: bold } /* Generic.Strong */
881 .codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
882 .codehilite .gt { color: #0044DD } /* Generic.Traceback */
883 .codehilite .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
884 .codehilite .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
885 .codehilite .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
886 .codehilite .kp { color: #008000 } /* Keyword.Pseudo */
887 .codehilite .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
888 .codehilite .kt { color: #B00040 } /* Keyword.Type */
889 .codehilite .m { color: #666666 } /* Literal.Number */
890 .codehilite .s { color: #BA2121 } /* Literal.String */
891 .codehilite .na { color: #7D9029 } /* Name.Attribute */
892 .codehilite .nb { color: #008000 } /* Name.Builtin */
893 .codehilite .nc { color: #0000FF; font-weight: bold } /* Name.Class */
894 .codehilite .no { color: #880000 } /* Name.Constant */
895 .codehilite .nd { color: #AA22FF } /* Name.Decorator */
896 .codehilite .ni { color: #999999; font-weight: bold } /* Name.Entity */
897 .codehilite .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
898 .codehilite .nf { color: #0000FF } /* Name.Function */
899 .codehilite .nl { color: #A0A000 } /* Name.Label */
900 .codehilite .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
901 .codehilite .nt { color: #008000; font-weight: bold } /* Name.Tag */
902 .codehilite .nv { color: #19177C } /* Name.Variable */
903 .codehilite .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
904 .codehilite .w { color: #bbbbbb } /* Text.Whitespace */
905 .codehilite .mb { color: #666666 } /* Literal.Number.Bin */
906 .codehilite .mf { color: #666666 } /* Literal.Number.Float */
907 .codehilite .mh { color: #666666 } /* Literal.Number.Hex */
908 .codehilite .mi { color: #666666 } /* Literal.Number.Integer */
909 .codehilite .mo { color: #666666 } /* Literal.Number.Oct */
910 .codehilite .sa { color: #BA2121 } /* Literal.String.Affix */
911 .codehilite .sb { color: #BA2121 } /* Literal.String.Backtick */
912 .codehilite .sc { color: #BA2121 } /* Literal.String.Char */
913 .codehilite .dl { color: #BA2121 } /* Literal.String.Delimiter */
914 .codehilite .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
915 .codehilite .s2 { color: #BA2121 } /* Literal.String.Double */
916 .codehilite .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
917 .codehilite .sh { color: #BA2121 } /* Literal.String.Heredoc */
918 .codehilite .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
919 .codehilite .sx { color: #008000 } /* Literal.String.Other */
920 .codehilite .sr { color: #BB6688 } /* Literal.String.Regex */
921 .codehilite .s1 { color: #BA2121 } /* Literal.String.Single */
922 .codehilite .ss { color: #19177C } /* Literal.String.Symbol */
923 .codehilite .bp { color: #008000 } /* Name.Builtin.Pseudo */
924 .codehilite .fm { color: #0000FF } /* Name.Function.Magic */
925 .codehilite .vc { color: #19177C } /* Name.Variable.Class */
926 .codehilite .vg { color: #19177C } /* Name.Variable.Global */
927 .codehilite .vi { color: #19177C } /* Name.Variable.Instance */
928 .codehilite .vm { color: #19177C } /* Name.Variable.Magic */
929 .codehilite .il { color: #666666 } /* Literal.Number.Integer.Long */
930 </style>
931
932 <style type="text/css">
933
934 /* ==========================================================================
935 EXAMPLE Media Queries for Responsive Design.
936 These examples override the primary ('mobile first') styles.
937 Modify as content requires.
938 ========================================================================== */
939
940 @media only screen and (min-width: 35em) {
941 /* Style adjustments for viewports that meet the condition */
942 }
943
944 @media print,
945 (-o-min-device-pixel-ratio: 5/4),
946 (-webkit-min-device-pixel-ratio: 1.25),
947 (min-resolution: 120dpi) {
948 /* Style adjustments for high resolution devices */
949 }
950
951 /* ==========================================================================
952 Print styles.
953 Inlined to avoid required HTTP connection: h5bp.com/r
954 ========================================================================== */
955
956 @media print {
957 * {
958 background: transparent !important;
959 color: #000 !important; /* Black prints faster: h5bp.com/s */
960 box-shadow: none !important;
961 text-shadow: none !important;
962 }
963
964 a,
965 a:visited {
966 text-decoration: underline;
967 }
968
969 a[href]:after {
970 content: " (" attr(href) ")";
971 }
972
973 abbr[title]:after {
974 content: " (" attr(title) ")";
975 }
976
977 /*
978 * Don't show links for images, or javascript/internal links
979 */
980
981 .ir a:after,
982 a[href^="javascript:"]:after,
983 a[href^="#"]:after {
984 content: "";
985 }
986
987 pre,
988 blockquote {
989 border: 1px solid #999;
990 page-break-inside: avoid;
991 }
992
993 thead {
994 display: table-header-group; /* h5bp.com/t */
995 }
996
997 tr,
998 img {
999 page-break-inside: avoid;
1000 }
1001
1002 img {
1003 max-width: 100% !important;
1004 }
1005
1006 @page {
1007 margin: 0.5cm;
1008 }
1009
1010 p,
1011 h2,
1012 h3 {
1013 orphans: 3;
1014 widows: 3;
1015 }
1016
1017 h2,
1018 h3 {
1019 page-break-after: avoid;
1020 }
1021 }
1022
1023 </style>
1024
1025 <script type="text/javascript">
1026 function toggle(id, $link) {
1027 $node = document.getElementById(id);
1028 if (!$node)
1029 return;
1030 if (!$node.style.display || $node.style.display == 'none') {
1031 $node.style.display = 'block';
1032 $link.innerHTML = 'Hide source &nequiv;';
1033 } else {
1034 $node.style.display = 'none';
1035 $link.innerHTML = 'Show source &equiv;';
1036 }
1037 }
1038 </script>
1039 </head>
1040 <body>
1041 <a href="#" id="top">Top</a>
1042
1043 <div id="container">
1044
1045
1046 <div id="sidebar">
1047 <h1>Index</h1>
1048 <ul id="index">
1049
1050 <li class="set"><h3><a href="#header-functions">Functions</a></h3>
1051
1052 <ul>
1053 <li class="mono"><a href="#netCDF4.chartostring">chartostring</a></li>
1054 <li class="mono"><a href="#netCDF4.date2index">date2index</a></li>
1055 <li class="mono"><a href="#netCDF4.date2num">date2num</a></li>
1056 <li class="mono"><a href="#netCDF4.get_chunk_cache">get_chunk_cache</a></li>
1057 <li class="mono"><a href="#netCDF4.getlibversion">getlibversion</a></li>
1058 <li class="mono"><a href="#netCDF4.num2date">num2date</a></li>
1059 <li class="mono"><a href="#netCDF4.set_chunk_cache">set_chunk_cache</a></li>
1060 <li class="mono"><a href="#netCDF4.stringtoarr">stringtoarr</a></li>
1061 <li class="mono"><a href="#netCDF4.stringtochar">stringtochar</a></li>
1062 </ul>
1063
1064 </li>
1065
1066 <li class="set"><h3><a href="#header-classes">Classes</a></h3>
1067 <ul>
1068 <li class="mono">
1069 <span class="class_name"><a href="#netCDF4.CompoundType">CompoundType</a></span>
1070
1071
1072 <ul>
1073 <li class="mono"><a href="#netCDF4.CompoundType.__init__">__init__</a></li>
1074 </ul>
1075
1076 </li>
1077 <li class="mono">
1078 <span class="class_name"><a href="#netCDF4.Dataset">Dataset</a></span>
1079
1080
1081 <ul>
1082 <li class="mono"><a href="#netCDF4.Dataset.__init__">__init__</a></li>
1083 <li class="mono"><a href="#netCDF4.Dataset.close">close</a></li>
1084 <li class="mono"><a href="#netCDF4.Dataset.createCompoundType">createCompoundType</a></li>
1085 <li class="mono"><a href="#netCDF4.Dataset.createDimension">createDimension</a></li>
1086 <li class="mono"><a href="#netCDF4.Dataset.createEnumType">createEnumType</a></li>
1087 <li class="mono"><a href="#netCDF4.Dataset.createGroup">createGroup</a></li>
1088 <li class="mono"><a href="#netCDF4.Dataset.createVLType">createVLType</a></li>
1089 <li class="mono"><a href="#netCDF4.Dataset.createVariable">createVariable</a></li>
1090 <li class="mono"><a href="#netCDF4.Dataset.delncattr">delncattr</a></li>
1091 <li class="mono"><a href="#netCDF4.Dataset.filepath">filepath</a></li>
1092 <li class="mono"><a href="#netCDF4.Dataset.get_variables_by_attributes">get_variables_by_attributes</a></li>
1093 <li class="mono"><a href="#netCDF4.Dataset.getncattr">getncattr</a></li>
1094 <li class="mono"><a href="#netCDF4.Dataset.isopen">isopen</a></li>
1095 <li class="mono"><a href="#netCDF4.Dataset.ncattrs">ncattrs</a></li>
1096 <li class="mono"><a href="#netCDF4.Dataset.renameAttribute">renameAttribute</a></li>
1097 <li class="mono"><a href="#netCDF4.Dataset.renameDimension">renameDimension</a></li>
1098 <li class="mono"><a href="#netCDF4.Dataset.renameGroup">renameGroup</a></li>
1099 <li class="mono"><a href="#netCDF4.Dataset.renameVariable">renameVariable</a></li>
1100 <li class="mono"><a href="#netCDF4.Dataset.set_always_mask">set_always_mask</a></li>
1101 <li class="mono"><a href="#netCDF4.Dataset.set_auto_chartostring">set_auto_chartostring</a></li>
1102 <li class="mono"><a href="#netCDF4.Dataset.set_auto_mask">set_auto_mask</a></li>
1103 <li class="mono"><a href="#netCDF4.Dataset.set_auto_maskandscale">set_auto_maskandscale</a></li>
1104 <li class="mono"><a href="#netCDF4.Dataset.set_auto_scale">set_auto_scale</a></li>
1105 <li class="mono"><a href="#netCDF4.Dataset.set_fill_off">set_fill_off</a></li>
1106 <li class="mono"><a href="#netCDF4.Dataset.set_fill_on">set_fill_on</a></li>
1107 <li class="mono"><a href="#netCDF4.Dataset.set_ncstring_attrs">set_ncstring_attrs</a></li>
1108 <li class="mono"><a href="#netCDF4.Dataset.setncattr">setncattr</a></li>
1109 <li class="mono"><a href="#netCDF4.Dataset.setncattr_string">setncattr_string</a></li>
1110 <li class="mono"><a href="#netCDF4.Dataset.setncatts">setncatts</a></li>
1111 <li class="mono"><a href="#netCDF4.Dataset.sync">sync</a></li>
1112 </ul>
1113
1114 </li>
1115 <li class="mono">
1116 <span class="class_name"><a href="#netCDF4.Dimension">Dimension</a></span>
1117
1118
1119 <ul>
1120 <li class="mono"><a href="#netCDF4.Dimension.__init__">__init__</a></li>
1121 <li class="mono"><a href="#netCDF4.Dimension.group">group</a></li>
1122 <li class="mono"><a href="#netCDF4.Dimension.isunlimited">isunlimited</a></li>
1123 </ul>
1124
1125 </li>
1126 <li class="mono">
1127 <span class="class_name"><a href="#netCDF4.EnumType">EnumType</a></span>
1128
1129
1130 <ul>
1131 <li class="mono"><a href="#netCDF4.EnumType.__init__">__init__</a></li>
1132 </ul>
1133
1134 </li>
1135 <li class="mono">
1136 <span class="class_name"><a href="#netCDF4.Group">Group</a></span>
1137
1138
1139 <ul>
1140 <li class="mono"><a href="#netCDF4.Group.__init__">__init__</a></li>
1141 <li class="mono"><a href="#netCDF4.Group.close">close</a></li>
1142 <li class="mono"><a href="#netCDF4.Group.createCompoundType">createCompoundType</a></li>
1143 <li class="mono"><a href="#netCDF4.Group.createDimension">createDimension</a></li>
1144 <li class="mono"><a href="#netCDF4.Group.createEnumType">createEnumType</a></li>
1145 <li class="mono"><a href="#netCDF4.Group.createGroup">createGroup</a></li>
1146 <li class="mono"><a href="#netCDF4.Group.createVLType">createVLType</a></li>
1147 <li class="mono"><a href="#netCDF4.Group.createVariable">createVariable</a></li>
1148 <li class="mono"><a href="#netCDF4.Group.delncattr">delncattr</a></li>
1149 <li class="mono"><a href="#netCDF4.Group.filepath">filepath</a></li>
1150 <li class="mono"><a href="#netCDF4.Group.get_variables_by_attributes">get_variables_by_attributes</a></li>
1151 <li class="mono"><a href="#netCDF4.Group.getncattr">getncattr</a></li>
1152 <li class="mono"><a href="#netCDF4.Group.isopen">isopen</a></li>
1153 <li class="mono"><a href="#netCDF4.Group.ncattrs">ncattrs</a></li>
1154 <li class="mono"><a href="#netCDF4.Group.renameAttribute">renameAttribute</a></li>
1155 <li class="mono"><a href="#netCDF4.Group.renameDimension">renameDimension</a></li>
1156 <li class="mono"><a href="#netCDF4.Group.renameGroup">renameGroup</a></li>
1157 <li class="mono"><a href="#netCDF4.Group.renameVariable">renameVariable</a></li>
1158 <li class="mono"><a href="#netCDF4.Group.set_always_mask">set_always_mask</a></li>
1159 <li class="mono"><a href="#netCDF4.Group.set_auto_chartostring">set_auto_chartostring</a></li>
1160 <li class="mono"><a href="#netCDF4.Group.set_auto_mask">set_auto_mask</a></li>
1161 <li class="mono"><a href="#netCDF4.Group.set_auto_maskandscale">set_auto_maskandscale</a></li>
1162 <li class="mono"><a href="#netCDF4.Group.set_auto_scale">set_auto_scale</a></li>
1163 <li class="mono"><a href="#netCDF4.Group.set_fill_off">set_fill_off</a></li>
1164 <li class="mono"><a href="#netCDF4.Group.set_fill_on">set_fill_on</a></li>
1165 <li class="mono"><a href="#netCDF4.Group.set_ncstring_attrs">set_ncstring_attrs</a></li>
1166 <li class="mono"><a href="#netCDF4.Group.setncattr">setncattr</a></li>
1167 <li class="mono"><a href="#netCDF4.Group.setncattr_string">setncattr_string</a></li>
1168 <li class="mono"><a href="#netCDF4.Group.setncatts">setncatts</a></li>
1169 <li class="mono"><a href="#netCDF4.Group.sync">sync</a></li>
1170 </ul>
1171
1172 </li>
1173 <li class="mono">
1174 <span class="class_name"><a href="#netCDF4.MFDataset">MFDataset</a></span>
1175
1176
1177 <ul>
1178 <li class="mono"><a href="#netCDF4.MFDataset.__init__">__init__</a></li>
1179 <li class="mono"><a href="#netCDF4.MFDataset.close">close</a></li>
1180 <li class="mono"><a href="#netCDF4.MFDataset.createCompoundType">createCompoundType</a></li>
1181 <li class="mono"><a href="#netCDF4.MFDataset.createDimension">createDimension</a></li>
1182 <li class="mono"><a href="#netCDF4.MFDataset.createEnumType">createEnumType</a></li>
1183 <li class="mono"><a href="#netCDF4.MFDataset.createGroup">createGroup</a></li>
1184 <li class="mono"><a href="#netCDF4.MFDataset.createVLType">createVLType</a></li>
1185 <li class="mono"><a href="#netCDF4.MFDataset.createVariable">createVariable</a></li>
1186 <li class="mono"><a href="#netCDF4.MFDataset.delncattr">delncattr</a></li>
1187 <li class="mono"><a href="#netCDF4.MFDataset.filepath">filepath</a></li>
1188 <li class="mono"><a href="#netCDF4.MFDataset.get_variables_by_attributes">get_variables_by_attributes</a></li>
1189 <li class="mono"><a href="#netCDF4.MFDataset.getncattr">getncattr</a></li>
1190 <li class="mono"><a href="#netCDF4.MFDataset.isopen">isopen</a></li>
1191 <li class="mono"><a href="#netCDF4.MFDataset.ncattrs">ncattrs</a></li>
1192 <li class="mono"><a href="#netCDF4.MFDataset.renameAttribute">renameAttribute</a></li>
1193 <li class="mono"><a href="#netCDF4.MFDataset.renameDimension">renameDimension</a></li>
1194 <li class="mono"><a href="#netCDF4.MFDataset.renameGroup">renameGroup</a></li>
1195 <li class="mono"><a href="#netCDF4.MFDataset.renameVariable">renameVariable</a></li>
1196 <li class="mono"><a href="#netCDF4.MFDataset.set_always_mask">set_always_mask</a></li>
1197 <li class="mono"><a href="#netCDF4.MFDataset.set_auto_chartostring">set_auto_chartostring</a></li>
1198 <li class="mono"><a href="#netCDF4.MFDataset.set_auto_mask">set_auto_mask</a></li>
1199 <li class="mono"><a href="#netCDF4.MFDataset.set_auto_maskandscale">set_auto_maskandscale</a></li>
1200 <li class="mono"><a href="#netCDF4.MFDataset.set_auto_scale">set_auto_scale</a></li>
1201 <li class="mono"><a href="#netCDF4.MFDataset.set_fill_off">set_fill_off</a></li>
1202 <li class="mono"><a href="#netCDF4.MFDataset.set_fill_on">set_fill_on</a></li>
1203 <li class="mono"><a href="#netCDF4.MFDataset.set_ncstring_attrs">set_ncstring_attrs</a></li>
1204 <li class="mono"><a href="#netCDF4.MFDataset.setncattr">setncattr</a></li>
1205 <li class="mono"><a href="#netCDF4.MFDataset.setncattr_string">setncattr_string</a></li>
1206 <li class="mono"><a href="#netCDF4.MFDataset.setncatts">setncatts</a></li>
1207 <li class="mono"><a href="#netCDF4.MFDataset.sync">sync</a></li>
1208 </ul>
1209
1210 </li>
1211 <li class="mono">
1212 <span class="class_name"><a href="#netCDF4.MFTime">MFTime</a></span>
1213
1214
1215 <ul>
1216 <li class="mono"><a href="#netCDF4.MFTime.__init__">__init__</a></li>
1217 <li class="mono"><a href="#netCDF4.MFTime.ncattrs">ncattrs</a></li>
1218 <li class="mono"><a href="#netCDF4.MFTime.set_always_mask">set_always_mask</a></li>
1219 <li class="mono"><a href="#netCDF4.MFTime.set_auto_chartostring">set_auto_chartostring</a></li>
1220 <li class="mono"><a href="#netCDF4.MFTime.set_auto_mask">set_auto_mask</a></li>
1221 <li class="mono"><a href="#netCDF4.MFTime.set_auto_maskandscale">set_auto_maskandscale</a></li>
1222 <li class="mono"><a href="#netCDF4.MFTime.set_auto_scale">set_auto_scale</a></li>
1223 <li class="mono"><a href="#netCDF4.MFTime.typecode">typecode</a></li>
1224 </ul>
1225
1226 </li>
1227 <li class="mono">
1228 <span class="class_name"><a href="#netCDF4.VLType">VLType</a></span>
1229
1230
1231 <ul>
1232 <li class="mono"><a href="#netCDF4.VLType.__init__">__init__</a></li>
1233 </ul>
1234
1235 </li>
1236 <li class="mono">
1237 <span class="class_name"><a href="#netCDF4.Variable">Variable</a></span>
1238
1239
1240 <ul>
1241 <li class="mono"><a href="#netCDF4.Variable.__init__">__init__</a></li>
1242 <li class="mono"><a href="#netCDF4.Variable.assignValue">assignValue</a></li>
1243 <li class="mono"><a href="#netCDF4.Variable.chunking">chunking</a></li>
1244 <li class="mono"><a href="#netCDF4.Variable.delncattr">delncattr</a></li>
1245 <li class="mono"><a href="#netCDF4.Variable.endian">endian</a></li>
1246 <li class="mono"><a href="#netCDF4.Variable.filters">filters</a></li>
1247 <li class="mono"><a href="#netCDF4.Variable.getValue">getValue</a></li>
1248 <li class="mono"><a href="#netCDF4.Variable.get_dims">get_dims</a></li>
1249 <li class="mono"><a href="#netCDF4.Variable.get_var_chunk_cache">get_var_chunk_cache</a></li>
1250 <li class="mono"><a href="#netCDF4.Variable.getncattr">getncattr</a></li>
1251 <li class="mono"><a href="#netCDF4.Variable.group">group</a></li>
1252 <li class="mono"><a href="#netCDF4.Variable.ncattrs">ncattrs</a></li>
1253 <li class="mono"><a href="#netCDF4.Variable.renameAttribute">renameAttribute</a></li>
1254 <li class="mono"><a href="#netCDF4.Variable.set_always_mask">set_always_mask</a></li>
1255 <li class="mono"><a href="#netCDF4.Variable.set_auto_chartostring">set_auto_chartostring</a></li>
1256 <li class="mono"><a href="#netCDF4.Variable.set_auto_mask">set_auto_mask</a></li>
1257 <li class="mono"><a href="#netCDF4.Variable.set_auto_maskandscale">set_auto_maskandscale</a></li>
1258 <li class="mono"><a href="#netCDF4.Variable.set_auto_scale">set_auto_scale</a></li>
1259 <li class="mono"><a href="#netCDF4.Variable.set_collective">set_collective</a></li>
1260 <li class="mono"><a href="#netCDF4.Variable.set_ncstring_attrs">set_ncstring_attrs</a></li>
1261 <li class="mono"><a href="#netCDF4.Variable.set_var_chunk_cache">set_var_chunk_cache</a></li>
1262 <li class="mono"><a href="#netCDF4.Variable.setncattr">setncattr</a></li>
1263 <li class="mono"><a href="#netCDF4.Variable.setncattr_string">setncattr_string</a></li>
1264 <li class="mono"><a href="#netCDF4.Variable.setncatts">setncatts</a></li>
1265 <li class="mono"><a href="#netCDF4.Variable.use_nc_get_vars">use_nc_get_vars</a></li>
1266 </ul>
1267
1268 </li>
1269 </ul>
1270 </li>
1271
1272 </ul>
1273 </div>
1274
1275 <article id="content">
1276
1277
1278
1279
1280
1281
1282 <header id="section-intro">
1283 <h1 class="title"><span class="name">netCDF4</span> module</h1>
1284 <h2>Version 1.5.5</h2>
1285 <hr />
1286 <h1>Introduction</h1>
1287 <p>netcdf4-python is a Python interface to the netCDF C library.</p>
1288 <p><a href="http://www.unidata.ucar.edu/software/netcdf/">netCDF</a> version 4 has many features
1289 not found in earlier versions of the library and is implemented on top of
1290 <a href="http://www.hdfgroup.org/HDF5">HDF5</a>. This module can read and write
1291 files in both the new netCDF 4 and the old netCDF 3 format, and can create
1292 files that are readable by HDF5 clients. The API modelled after
1293 <a href="http://dirac.cnrs-orleans.fr/ScientificPython/">Scientific.IO.NetCDF</a>,
1294 and should be familiar to users of that module.</p>
1295 <p>Most new features of netCDF 4 are implemented, such as multiple
1296 unlimited dimensions, groups and zlib data compression. All the new
1297 numeric data types (such as 64 bit and unsigned integer types) are
1298 implemented. Compound (struct), variable length (vlen) and
1299 enumerated (enum) data types are supported, but not the opaque data type.
1300 Mixtures of compound, vlen and enum data types (such as
1301 compound types containing enums, or vlens containing compound
1302 types) are not supported.</p>
1303 <h1>Download</h1>
1304 <ul>
1305 <li>Latest bleeding-edge code from the
1306 <a href="http://github.com/Unidata/netcdf4-python">github repository</a>.</li>
1307 <li>Latest <a href="https://pypi.python.org/pypi/netCDF4">releases</a>
1308 (source code and binary installers).</li>
1309 </ul>
1310 <h1>Requires</h1>
1311 <ul>
1312 <li><a href="http://numpy.scipy.org">numpy array module</a>, version 1.10.0 or later.</li>
1313 <li><a href="http://cython.org">Cython</a>, version 0.21 or later.</li>
1314 <li><a href="https://pypi.python.org/pypi/setuptools">setuptools</a>, version 18.0 or
1315 later.</li>
1316 <li><a href="https://github.com/Unidata/cftime">cftime</a> for
1317 the time and date handling utility functions (<a href="#netCDF4.num2date"><code>num2date</code></a>,
1318 <a href="#netCDF4.date2num"><code>date2num</code></a> and <a href="#netCDF4.date2index"><code>date2index</code></a>).</li>
1319 <li>The HDF5 C library version 1.8.4-patch1 or higher (1.8.x recommended)
1320 from <a href="ftp://ftp.hdfgroup.org/HDF5/current/src"></a>.
1321 <strong><em>netCDF version 4.4.1 or higher is recommended if using HDF5 1.10.x -
1322 otherwise resulting files may be unreadable by clients using earlier
1323 versions of HDF5. For netCDF &lt; 4.4.1, HDF5 version 1.8.x is recommended.</em></strong>
1324 Be sure to build with <code>--enable-hl --enable-shared</code>.</li>
1325 <li><a href="http://curl.haxx.se/libcurl">Libcurl</a>, if you want
1326 <a href="http://opendap.org">OPeNDAP</a> support.</li>
1327 <li><a href="http://www.hdfgroup.org/products/hdf4">HDF4</a>, if you want
1328 to be able to read HDF4 "Scientific Dataset" (SD) files.</li>
1329 <li>The netCDF-4 C library from the <a href="https://github.com/Unidata/netcdf-c/releases">github releases
1330 page</a>.
1331 Version 4.1.1 or higher is required (4.2 or higher recommended).
1332 Be sure to build with <code>--enable-netcdf-4 --enable-shared</code>, and set
1333 <code>CPPFLAGS="-I $HDF5_DIR/include"</code> and <code>LDFLAGS="-L $HDF5_DIR/lib"</code>,
1334 where <code>$HDF5_DIR</code> is the directory where HDF5 was installed.
1335 If you want <a href="http://opendap.org">OPeNDAP</a> support, add <code>--enable-dap</code>.
1336 If you want HDF4 SD support, add <code>--enable-hdf4</code> and add
1337 the location of the HDF4 headers and library to <code>$CPPFLAGS</code> and <code>$LDFLAGS</code>.</li>
1338 <li>for MPI parallel IO support, an MPI-enabled versions of the netcdf library
1339 is required, as is the <a href="http://mpi4py.scipy.org">mpi4py</a> python module.
1340 Parallel IO further depends on the existence of MPI-enabled HDF5 or the
1341 <a href="https://parallel-netcdf.github.io/">PnetCDF</a> library.</li>
1342 </ul>
1343 <h1>Install</h1>
1344 <ul>
1345 <li>install the requisite python modules and C libraries (see above). It's
1346 easiest if all the C libs are built as shared libraries.</li>
1347 <li>By default, the utility <code>nc-config</code>, installed with netcdf 4.1.2 or higher,
1348 will be run used to determine where all the dependencies live.</li>
1349 <li>If <code>nc-config</code> is not in your default <code>PATH</code>, you can set the <code>NETCDF4_DIR</code>
1350 environment variable and <code>setup.py</code> will look in <code>$NETCDF4_DIR/bin</code>.
1351 You can also use the file <code>setup.cfg</code> to set the path to <code>nc-config</code>, or
1352 enter the paths to the libraries and include files manually. Just edit the <code>setup.cfg</code> file
1353 in a text editor and follow the instructions in the comments.
1354 To disable the use of <code>nc-config</code>, set the env var <code>USE_NCCONFIG</code> to 0.
1355 To disable the use of <code>setup.cfg</code>, set <code>USE_SETUPCFG</code> to 0.
1356 As a last resort, the library and include paths can be set via environment variables.
1357 If you go this route, set <code>USE_NCCONFIG</code> and <code>USE_SETUPCFG</code> to 0, and specify
1358 <code>NETCDF4_LIBDIR</code>, <code>NETCDF4_INCDIR</code>, <code>HDF5_LIBDIR</code> and <code>HDF5_INCDIR</code>.
1359 Similarly, environment variables
1360 (all capitalized) can be used to set the include and library paths for
1361 <code>hdf4</code>, <code>szip</code>, <code>jpeg</code>, <code>curl</code> and <code>zlib</code>. If the dependencies are not found
1362 in any of the paths specified by environment variables, then standard locations
1363 (such as <code>/usr</code> and <code>/usr/local</code>) are searched.</li>
1364 <li>run <code>python setup.py build</code>, then <code>python setup.py install</code> (as root if
1365 necessary). <code>pip install</code> can be used to install pre-compiled binary wheels from
1366 <a href="https://pypi.org/project/netCDF4">pypi</a>.</li>
1367 <li>run the tests in the 'test' directory by running <code>python run_all.py</code>.</li>
1368 </ul>
1369 <h1>Tutorial</h1>
1370 <ol>
1371 <li><a href="#section1">Creating/Opening/Closing a netCDF file.</a></li>
1372 <li><a href="#section2">Groups in a netCDF file.</a></li>
1373 <li><a href="#section3">Dimensions in a netCDF file.</a></li>
1374 <li><a href="#section4">Variables in a netCDF file.</a></li>
1375 <li><a href="#section5">Attributes in a netCDF file.</a></li>
1376 <li><a href="#section6">Writing data to and retrieving data from a netCDF variable.</a></li>
1377 <li><a href="#section7">Dealing with time coordinates.</a></li>
1378 <li><a href="#section8">Reading data from a multi-file netCDF dataset.</a></li>
1379 <li><a href="#section9">Efficient compression of netCDF variables.</a></li>
1380 <li><a href="#section10">Beyond homogeneous arrays of a fixed type - compound data types.</a></li>
1381 <li><a href="#section11">Variable-length (vlen) data types.</a></li>
1382 <li><a href="#section12">Enum data type.</a></li>
1383 <li><a href="#section13">Parallel IO.</a></li>
1384 <li><a href="#section14">Dealing with strings.</a></li>
1385 <li><a href="#section15">In-memory (diskless) Datasets.</a></li>
1386 </ol>
1387 <h2><div id='section1'>1) Creating/Opening/Closing a netCDF file.</h2>
1388 <p>To create a netCDF file from python, you simply call the <a href="#netCDF4.Dataset"><code>Dataset</code></a>
1389 constructor. This is also the method used to open an existing netCDF
1390 file. If the file is open for write access (<code>mode='w', 'r+'</code> or <code>'a'</code>), you may
1391 write any type of data including new dimensions, groups, variables and
1392 attributes. netCDF files come in five flavors (<code>NETCDF3_CLASSIC,
1393 NETCDF3_64BIT_OFFSET, NETCDF3_64BIT_DATA, NETCDF4_CLASSIC</code>, and <code>NETCDF4</code>).
1394 <code>NETCDF3_CLASSIC</code> was the original netcdf binary format, and was limited
1395 to file sizes less than 2 Gb. <code>NETCDF3_64BIT_OFFSET</code> was introduced
1396 in version 3.6.0 of the library, and extended the original binary format
1397 to allow for file sizes greater than 2 Gb.
1398 <code>NETCDF3_64BIT_DATA</code> is a new format that requires version 4.4.0 of
1399 the C library - it extends the <code>NETCDF3_64BIT_OFFSET</code> binary format to
1400 allow for unsigned/64 bit integer data types and 64-bit dimension sizes.
1401 <code>NETCDF3_64BIT</code> is an alias for <code>NETCDF3_64BIT_OFFSET</code>.
1402 <code>NETCDF4_CLASSIC</code> files use the version 4 disk format (HDF5), but omits features
1403 not found in the version 3 API. They can be read by netCDF 3 clients
1404 only if they have been relinked against the netCDF 4 library. They can
1405 also be read by HDF5 clients. <code>NETCDF4</code> files use the version 4 disk
1406 format (HDF5) and use the new features of the version 4 API. The
1407 <code>netCDF4</code> module can read and write files in any of these formats. When
1408 creating a new file, the format may be specified using the <code>format</code>
1409 keyword in the <code>Dataset</code> constructor. The default format is
1410 <code>NETCDF4</code>. To see how a given file is formatted, you can examine the
1411 <code>data_model</code> attribute. Closing the netCDF file is
1412 accomplished via the <a href="#netCDF4.Dataset.close"><code>close</code></a> method of the <a href="#netCDF4.Dataset"><code>Dataset</code></a>
1413 instance.</p>
1414 <p>Here's an example:</p>
1415 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">Dataset</span>
1416 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;test.nc&quot;</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s2">&quot;NETCDF4&quot;</span><span class="p">)</span>
1417 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">data_model</span><span class="p">)</span>
1418 <span class="n">NETCDF4</span>
1419 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
1420 </code></pre></div>
1421
1422
1423 <p>Remote <a href="http://opendap.org">OPeNDAP</a>-hosted datasets can be accessed for
1424 reading over http if a URL is provided to the <a href="#netCDF4.Dataset"><code>Dataset</code></a> constructor instead of a
1425 filename. However, this requires that the netCDF library be built with
1426 OPenDAP support, via the <code>--enable-dap</code> configure option (added in
1427 version 4.0.1).</p>
1428 <h2><div id='section2'>2) Groups in a netCDF file.</h2>
1429 <p>netCDF version 4 added support for organizing data in hierarchical
1430 groups, which are analogous to directories in a filesystem. Groups serve
1431 as containers for variables, dimensions and attributes, as well as other
1432 groups. A <a href="#netCDF4.Dataset"><code>Dataset</code></a> creates a special group, called
1433 the 'root group', which is similar to the root directory in a unix
1434 filesystem. To create <a href="#netCDF4.Group"><code>Group</code></a> instances, use the
1435 <a href="#netCDF4.Dataset.createGroup"><code>createGroup</code></a> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a>
1436 instance. <a href="#netCDF4.Dataset.createGroup"><code>createGroup</code></a> takes a single argument, a
1437 python string containing the name of the new group. The new <a href="#netCDF4.Group"><code>Group</code></a>
1438 instances contained within the root group can be accessed by name using
1439 the <code>groups</code> dictionary attribute of the <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance. Only
1440 <code>NETCDF4</code> formatted files support Groups, if you try to create a Group
1441 in a netCDF 3 file you will get an error message.</p>
1442 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;test.nc&quot;</span><span class="p">,</span> <span class="s2">&quot;a&quot;</span><span class="p">)</span>
1443 <span class="o">&gt;&gt;&gt;</span> <span class="n">fcstgrp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createGroup</span><span class="p">(</span><span class="s2">&quot;forecasts&quot;</span><span class="p">)</span>
1444 <span class="o">&gt;&gt;&gt;</span> <span class="n">analgrp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createGroup</span><span class="p">(</span><span class="s2">&quot;analyses&quot;</span><span class="p">)</span>
1445 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">groups</span><span class="p">)</span>
1446 <span class="p">{</span><span class="s1">&#39;forecasts&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
1447 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="p">:</span>
1448 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
1449 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
1450 <span class="n">groups</span><span class="p">:</span> <span class="p">,</span> <span class="s1">&#39;analyses&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
1451 <span class="n">group</span> <span class="o">/</span><span class="n">analyses</span><span class="p">:</span>
1452 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
1453 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
1454 <span class="n">groups</span><span class="p">:</span> <span class="p">}</span>
1455 </code></pre></div>
1456
1457
1458 <p>Groups can exist within groups in a <a href="#netCDF4.Dataset"><code>Dataset</code></a>, just as directories
1459 exist within directories in a unix filesystem. Each <a href="#netCDF4.Group"><code>Group</code></a> instance
1460 has a <code>groups</code> attribute dictionary containing all of the group
1461 instances contained within that group. Each <a href="#netCDF4.Group"><code>Group</code></a> instance also has a
1462 <code>path</code> attribute that contains a simulated unix directory path to
1463 that group. To simplify the creation of nested groups, you can
1464 use a unix-like path as an argument to <a href="#netCDF4.Dataset.createGroup"><code>createGroup</code></a>.</p>
1465 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">fcstgrp1</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createGroup</span><span class="p">(</span><span class="s2">&quot;/forecasts/model1&quot;</span><span class="p">)</span>
1466 <span class="o">&gt;&gt;&gt;</span> <span class="n">fcstgrp2</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createGroup</span><span class="p">(</span><span class="s2">&quot;/forecasts/model2&quot;</span><span class="p">)</span>
1467 </code></pre></div>
1468
1469
1470 <p>If any of the intermediate elements of the path do not exist, they are created,
1471 just as with the unix command <code>'mkdir -p'</code>. If you try to create a group
1472 that already exists, no error will be raised, and the existing group will be
1473 returned.</p>
1474 <p>Here's an example that shows how to navigate all the groups in a
1475 <a href="#netCDF4.Dataset"><code>Dataset</code></a>. The function <code>walktree</code> is a Python generator that is used
1476 to walk the directory tree. Note that printing the <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a>
1477 object yields summary information about it's contents.</p>
1478 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="k">def</span> <span class="nf">walktree</span><span class="p">(</span><span class="n">top</span><span class="p">):</span>
1479 <span class="o">...</span> <span class="n">values</span> <span class="o">=</span> <span class="n">top</span><span class="o">.</span><span class="n">groups</span><span class="o">.</span><span class="n">values</span><span class="p">()</span>
1480 <span class="o">...</span> <span class="k">yield</span> <span class="n">values</span>
1481 <span class="o">...</span> <span class="k">for</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">top</span><span class="o">.</span><span class="n">groups</span><span class="o">.</span><span class="n">values</span><span class="p">():</span>
1482 <span class="o">...</span> <span class="k">for</span> <span class="n">children</span> <span class="ow">in</span> <span class="n">walktree</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
1483 <span class="o">...</span> <span class="k">yield</span> <span class="n">children</span>
1484 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">)</span>
1485 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
1486 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
1487 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
1488 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
1489 <span class="n">groups</span><span class="p">:</span> <span class="n">forecasts</span><span class="p">,</span> <span class="n">analyses</span>
1490 <span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">children</span> <span class="ow">in</span> <span class="n">walktree</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">):</span>
1491 <span class="o">...</span> <span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">children</span><span class="p">:</span>
1492 <span class="o">...</span> <span class="nb">print</span><span class="p">(</span><span class="n">child</span><span class="p">)</span>
1493 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
1494 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="p">:</span>
1495 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
1496 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
1497 <span class="n">groups</span><span class="p">:</span> <span class="n">model1</span><span class="p">,</span> <span class="n">model2</span>
1498 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
1499 <span class="n">group</span> <span class="o">/</span><span class="n">analyses</span><span class="p">:</span>
1500 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
1501 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
1502 <span class="n">groups</span><span class="p">:</span>
1503 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
1504 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="o">/</span><span class="n">model1</span><span class="p">:</span>
1505 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
1506 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
1507 <span class="n">groups</span><span class="p">:</span>
1508 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
1509 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="o">/</span><span class="n">model2</span><span class="p">:</span>
1510 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
1511 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span>
1512 <span class="n">groups</span><span class="p">:</span>
1513 </code></pre></div>
1514
1515
1516 <h2><div id='section3'>3) Dimensions in a netCDF file.</h2>
1517 <p>netCDF defines the sizes of all variables in terms of dimensions, so
1518 before any variables can be created the dimensions they use must be
1519 created first. A special case, not often used in practice, is that of a
1520 scalar variable, which has no dimensions. A dimension is created using
1521 the <a href="#netCDF4.Dataset.createDimension"><code>createDimension</code></a> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a>
1522 or <a href="#netCDF4.Group"><code>Group</code></a> instance. A Python string is used to set the name of the
1523 dimension, and an integer value is used to set the size. To create an
1524 unlimited dimension (a dimension that can be appended to), the size
1525 value is set to <code>None</code> or 0. In this example, there both the <code>time</code> and
1526 <code>level</code> dimensions are unlimited. Having more than one unlimited
1527 dimension is a new netCDF 4 feature, in netCDF 3 files there may be only
1528 one, and it must be the first (leftmost) dimension of the variable.</p>
1529 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">level</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;level&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
1530 <span class="o">&gt;&gt;&gt;</span> <span class="n">time</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
1531 <span class="o">&gt;&gt;&gt;</span> <span class="n">lat</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span> <span class="mi">73</span><span class="p">)</span>
1532 <span class="o">&gt;&gt;&gt;</span> <span class="n">lon</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;lon&quot;</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
1533 </code></pre></div>
1534
1535
1536 <p>All of the <a href="#netCDF4.Dimension"><code>Dimension</code></a> instances are stored in a python dictionary.</p>
1537 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">dimensions</span><span class="p">)</span>
1538 <span class="p">{</span><span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt; (unlimited): name = &#39;</span><span class="n">level</span><span class="s1">&#39;, size = 0, &#39;</span><span class="n">time</span><span class="s1">&#39;: &lt;class &#39;</span><span class="n">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt; (unlimited): name = &#39;</span><span class="n">time</span><span class="s1">&#39;, size = 0, &#39;</span><span class="n">lat</span><span class="s1">&#39;: &lt;class &#39;</span><span class="n">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">lat</span><span class="s1">&#39;, size = 73, &#39;</span><span class="n">lon</span><span class="s1">&#39;: &lt;class &#39;</span><span class="n">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">lon</span><span class="s1">&#39;, size = 144}</span>
1539 </code></pre></div>
1540
1541
1542 <p>Calling the python <code>len</code> function with a <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance returns
1543 the current size of that dimension.
1544 The <a href="#netCDF4.Dimension.isunlimited"><code>isunlimited</code></a> method of a <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance
1545 can be used to determine if the dimensions is unlimited, or appendable.</p>
1546 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">lon</span><span class="p">))</span>
1547 <span class="mi">144</span>
1548 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">lon</span><span class="o">.</span><span class="n">isunlimited</span><span class="p">())</span>
1549 <span class="kc">False</span>
1550 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">isunlimited</span><span class="p">())</span>
1551 <span class="kc">True</span>
1552 </code></pre></div>
1553
1554
1555 <p>Printing the <a href="#netCDF4.Dimension"><code>Dimension</code></a> object
1556 provides useful summary info, including the name and length of the dimension,
1557 and whether it is unlimited.</p>
1558 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">dimobj</span> <span class="ow">in</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">dimensions</span><span class="o">.</span><span class="n">values</span><span class="p">():</span>
1559 <span class="o">...</span> <span class="nb">print</span><span class="p">(</span><span class="n">dimobj</span><span class="p">)</span>
1560 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt; (unlimited): name = &#39;</span><span class="n">level</span><span class="s1">&#39;, size = 0</span>
1561 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt; (unlimited): name = &#39;</span><span class="n">time</span><span class="s1">&#39;, size = 0</span>
1562 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">lat</span><span class="s1">&#39;, size = 73</span>
1563 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dimension</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">lon</span><span class="s1">&#39;, size = 144</span>
1564 </code></pre></div>
1565
1566
1567 <p><a href="#netCDF4.Dimension"><code>Dimension</code></a> names can be changed using the
1568 <code>netCDF4.Datatset.renameDimension</code> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
1569 <a href="#netCDF4.Group"><code>Group</code></a> instance.</p>
1570 <h2><div id='section4'>4) Variables in a netCDF file.</h2>
1571 <p>netCDF variables behave much like python multidimensional array objects
1572 supplied by the <a href="http://numpy.scipy.org">numpy module</a>. However,
1573 unlike numpy arrays, netCDF4 variables can be appended to along one or
1574 more 'unlimited' dimensions. To create a netCDF variable, use the
1575 <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
1576 <a href="#netCDF4.Group"><code>Group</code></a> instance. The <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> method
1577 has two mandatory arguments, the variable name (a Python string), and
1578 the variable datatype. The variable's dimensions are given by a tuple
1579 containing the dimension names (defined previously with
1580 <a href="#netCDF4.Dataset.createDimension"><code>createDimension</code></a>). To create a scalar
1581 variable, simply leave out the dimensions keyword. The variable
1582 primitive datatypes correspond to the dtype attribute of a numpy array.
1583 You can specify the datatype as a numpy dtype object, or anything that
1584 can be converted to a numpy dtype object. Valid datatype specifiers
1585 include: <code>'f4'</code> (32-bit floating point), <code>'f8'</code> (64-bit floating
1586 point), <code>'i4'</code> (32-bit signed integer), <code>'i2'</code> (16-bit signed
1587 integer), <code>'i8'</code> (64-bit signed integer), <code>'i1'</code> (8-bit signed
1588 integer), <code>'u1'</code> (8-bit unsigned integer), <code>'u2'</code> (16-bit unsigned
1589 integer), <code>'u4'</code> (32-bit unsigned integer), <code>'u8'</code> (64-bit unsigned
1590 integer), or <code>'S1'</code> (single-character string). The old Numeric
1591 single-character typecodes (<code>'f'</code>,<code>'d'</code>,<code>'h'</code>,
1592 <code>'s'</code>,<code>'b'</code>,<code>'B'</code>,<code>'c'</code>,<code>'i'</code>,<code>'l'</code>), corresponding to
1593 (<code>'f4'</code>,<code>'f8'</code>,<code>'i2'</code>,<code>'i2'</code>,<code>'i1'</code>,<code>'i1'</code>,<code>'S1'</code>,<code>'i4'</code>,<code>'i4'</code>),
1594 will also work. The unsigned integer types and the 64-bit integer type
1595 can only be used if the file format is <code>NETCDF4</code>.</p>
1596 <p>The dimensions themselves are usually also defined as variables, called
1597 coordinate variables. The <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a>
1598 method returns an instance of the <a href="#netCDF4.Variable"><code>Variable</code></a> class whose methods can be
1599 used later to access and set variable data and attributes.</p>
1600 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">times</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;f8&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,))</span>
1601 <span class="o">&gt;&gt;&gt;</span> <span class="n">levels</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;i4&quot;</span><span class="p">,(</span><span class="s2">&quot;level&quot;</span><span class="p">,))</span>
1602 <span class="o">&gt;&gt;&gt;</span> <span class="n">latitudes</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;lat&quot;</span><span class="p">,))</span>
1603 <span class="o">&gt;&gt;&gt;</span> <span class="n">longitudes</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;lon&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;lon&quot;</span><span class="p">,))</span>
1604 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># two dimensions unlimited</span>
1605 <span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,))</span>
1606 <span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;K&quot;</span>
1607 </code></pre></div>
1608
1609
1610 <p>To get summary info on a <a href="#netCDF4.Variable"><code>Variable</code></a> instance in an interactive session,
1611 just print it.</p>
1612 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">temp</span><span class="p">)</span>
1613 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1614 <span class="n">float32</span> <span class="n">temp</span><span class="p">(</span><span class="n">time</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">lat</span><span class="p">,</span> <span class="n">lon</span><span class="p">)</span>
1615 <span class="n">units</span><span class="p">:</span> <span class="n">K</span>
1616 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span><span class="p">,</span> <span class="n">level</span>
1617 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
1618 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span>
1619 </code></pre></div>
1620
1621
1622 <p>You can use a path to create a Variable inside a hierarchy of groups.</p>
1623 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">ftemp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;/forecasts/model1/temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,))</span>
1624 </code></pre></div>
1625
1626
1627 <p>If the intermediate groups do not yet exist, they will be created.</p>
1628 <p>You can also query a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance directly to obtain <a href="#netCDF4.Group"><code>Group</code></a> or
1629 <a href="#netCDF4.Variable"><code>Variable</code></a> instances using paths.</p>
1630 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">[</span><span class="s2">&quot;/forecasts/model1&quot;</span><span class="p">])</span> <span class="c1"># a Group instance</span>
1631 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Group</span><span class="s1">&#39;&gt;</span>
1632 <span class="n">group</span> <span class="o">/</span><span class="n">forecasts</span><span class="o">/</span><span class="n">model1</span><span class="p">:</span>
1633 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span>
1634 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">float32</span> <span class="n">temp</span><span class="p">(</span><span class="n">time</span><span class="p">,</span><span class="n">level</span><span class="p">,</span><span class="n">lat</span><span class="p">,</span><span class="n">lon</span><span class="p">)</span>
1635 <span class="n">groups</span><span class="p">:</span>
1636 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">[</span><span class="s2">&quot;/forecasts/model1/temp&quot;</span><span class="p">])</span> <span class="c1"># a Variable instance</span>
1637 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1638 <span class="n">float32</span> <span class="n">temp</span><span class="p">(</span><span class="n">time</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">lat</span><span class="p">,</span> <span class="n">lon</span><span class="p">)</span>
1639 <span class="n">path</span> <span class="o">=</span> <span class="o">/</span><span class="n">forecasts</span><span class="o">/</span><span class="n">model1</span>
1640 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span><span class="p">,</span> <span class="n">level</span>
1641 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
1642 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span>
1643 </code></pre></div>
1644
1645
1646 <p>All of the variables in the <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> are stored in a
1647 Python dictionary, in the same way as the dimensions:</p>
1648 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">variables</span><span class="p">)</span>
1649 <span class="p">{</span><span class="s1">&#39;time&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1650 <span class="n">float64</span> <span class="n">time</span><span class="p">(</span><span class="n">time</span><span class="p">)</span>
1651 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span>
1652 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,)</span>
1653 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span><span class="p">,</span> <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1654 <span class="n">int32</span> <span class="n">level</span><span class="p">(</span><span class="n">level</span><span class="p">)</span>
1655 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">level</span>
1656 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,)</span>
1657 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="o">-</span><span class="mi">2147483647</span> <span class="n">used</span><span class="p">,</span> <span class="s1">&#39;lat&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1658 <span class="n">float32</span> <span class="n">lat</span><span class="p">(</span><span class="n">lat</span><span class="p">)</span>
1659 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span>
1660 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">73</span><span class="p">,)</span>
1661 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span><span class="p">,</span> <span class="s1">&#39;lon&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1662 <span class="n">float32</span> <span class="n">lon</span><span class="p">(</span><span class="n">lon</span><span class="p">)</span>
1663 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span>
1664 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">144</span><span class="p">,)</span>
1665 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span><span class="p">,</span> <span class="s1">&#39;temp&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
1666 <span class="n">float32</span> <span class="n">temp</span><span class="p">(</span><span class="n">time</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">lat</span><span class="p">,</span> <span class="n">lon</span><span class="p">)</span>
1667 <span class="n">units</span><span class="p">:</span> <span class="n">K</span>
1668 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span><span class="p">,</span> <span class="n">level</span>
1669 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
1670 <span class="n">filling</span> <span class="n">on</span><span class="p">,</span> <span class="n">default</span> <span class="n">_FillValue</span> <span class="n">of</span> <span class="mf">9.969209968386869e+36</span> <span class="n">used</span><span class="p">}</span>
1671 </code></pre></div>
1672
1673
1674 <p><a href="#netCDF4.Variable"><code>Variable</code></a> names can be changed using the
1675 <a href="#netCDF4.Dataset.renameVariable"><code>renameVariable</code></a> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a>
1676 instance.</p>
1677 <h2><div id='section5'>5) Attributes in a netCDF file.</h2>
1678 <p>There are two types of attributes in a netCDF file, global and variable.
1679 Global attributes provide information about a group, or the entire
1680 dataset, as a whole. <a href="#netCDF4.Variable"><code>Variable</code></a> attributes provide information about
1681 one of the variables in a group. Global attributes are set by assigning
1682 values to <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance variables. <a href="#netCDF4.Variable"><code>Variable</code></a>
1683 attributes are set by assigning values to <a href="#netCDF4.Variable"><code>Variable</code></a> instances
1684 variables. Attributes can be strings, numbers or sequences. Returning to
1685 our example,</p>
1686 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">time</span>
1687 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">description</span> <span class="o">=</span> <span class="s2">&quot;bogus example script&quot;</span>
1688 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">history</span> <span class="o">=</span> <span class="s2">&quot;Created &quot;</span> <span class="o">+</span> <span class="n">time</span><span class="o">.</span><span class="n">ctime</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">())</span>
1689 <span class="o">&gt;&gt;&gt;</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">source</span> <span class="o">=</span> <span class="s2">&quot;netCDF4 python module tutorial&quot;</span>
1690 <span class="o">&gt;&gt;&gt;</span> <span class="n">latitudes</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;degrees north&quot;</span>
1691 <span class="o">&gt;&gt;&gt;</span> <span class="n">longitudes</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;degrees east&quot;</span>
1692 <span class="o">&gt;&gt;&gt;</span> <span class="n">levels</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;hPa&quot;</span>
1693 <span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;K&quot;</span>
1694 <span class="o">&gt;&gt;&gt;</span> <span class="n">times</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;hours since 0001-01-01 00:00:00.0&quot;</span>
1695 <span class="o">&gt;&gt;&gt;</span> <span class="n">times</span><span class="o">.</span><span class="n">calendar</span> <span class="o">=</span> <span class="s2">&quot;gregorian&quot;</span>
1696 </code></pre></div>
1697
1698
1699 <p>The <a href="#netCDF4.Dataset.ncattrs"><code>ncattrs</code></a> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a>, <a href="#netCDF4.Group"><code>Group</code></a> or
1700 <a href="#netCDF4.Variable"><code>Variable</code></a> instance can be used to retrieve the names of all the netCDF
1701 attributes. This method is provided as a convenience, since using the
1702 built-in <code>dir</code> Python function will return a bunch of private methods
1703 and attributes that cannot (or should not) be modified by the user.</p>
1704 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">ncattrs</span><span class="p">():</span>
1705 <span class="o">...</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Global attr </span><span class="si">{}</span><span class="s2"> = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">rootgrp</span><span class="p">,</span> <span class="n">name</span><span class="p">)))</span>
1706 <span class="n">Global</span> <span class="n">attr</span> <span class="n">description</span> <span class="o">=</span> <span class="n">bogus</span> <span class="n">example</span> <span class="n">script</span>
1707 <span class="n">Global</span> <span class="n">attr</span> <span class="n">history</span> <span class="o">=</span> <span class="n">Created</span> <span class="n">Mon</span> <span class="n">Jul</span> <span class="mi">8</span> <span class="mi">14</span><span class="p">:</span><span class="mi">19</span><span class="p">:</span><span class="mi">41</span> <span class="mi">2019</span>
1708 <span class="n">Global</span> <span class="n">attr</span> <span class="n">source</span> <span class="o">=</span> <span class="n">netCDF4</span> <span class="n">python</span> <span class="n">module</span> <span class="n">tutorial</span>
1709 </code></pre></div>
1710
1711
1712 <p>The <code>__dict__</code> attribute of a <a href="#netCDF4.Dataset"><code>Dataset</code></a>, <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Variable"><code>Variable</code></a>
1713 instance provides all the netCDF attribute name/value pairs in a python
1714 dictionary:</p>
1715 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">)</span>
1716 <span class="p">{</span><span class="s1">&#39;description&#39;</span><span class="p">:</span> <span class="s1">&#39;bogus example script&#39;</span><span class="p">,</span> <span class="s1">&#39;history&#39;</span><span class="p">:</span> <span class="s1">&#39;Created Mon Jul 8 14:19:41 2019&#39;</span><span class="p">,</span> <span class="s1">&#39;source&#39;</span><span class="p">:</span> <span class="s1">&#39;netCDF4 python module tutorial&#39;</span><span class="p">}</span>
1717 </code></pre></div>
1718
1719
1720 <p>Attributes can be deleted from a netCDF <a href="#netCDF4.Dataset"><code>Dataset</code></a>, <a href="#netCDF4.Group"><code>Group</code></a> or
1721 <a href="#netCDF4.Variable"><code>Variable</code></a> using the python <code>del</code> statement (i.e. <code>del grp.foo</code>
1722 removes the attribute <code>foo</code> the the group <code>grp</code>).</p>
1723 <h2><div id='section6'>6) Writing data to and retrieving data from a netCDF variable.</h2>
1724 <p>Now that you have a netCDF <a href="#netCDF4.Variable"><code>Variable</code></a> instance, how do you put data
1725 into it? You can just treat it like an array and assign data to a slice.</p>
1726 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">numpy</span>
1727 <span class="o">&gt;&gt;&gt;</span> <span class="n">lats</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="o">-</span><span class="mi">90</span><span class="p">,</span><span class="mi">91</span><span class="p">,</span><span class="mf">2.5</span><span class="p">)</span>
1728 <span class="o">&gt;&gt;&gt;</span> <span class="n">lons</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="o">-</span><span class="mi">180</span><span class="p">,</span><span class="mi">180</span><span class="p">,</span><span class="mf">2.5</span><span class="p">)</span>
1729 <span class="o">&gt;&gt;&gt;</span> <span class="n">latitudes</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">lats</span>
1730 <span class="o">&gt;&gt;&gt;</span> <span class="n">longitudes</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">lons</span>
1731 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;latitudes =</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">latitudes</span><span class="p">[:]))</span>
1732 <span class="n">latitudes</span> <span class="o">=</span>
1733 <span class="p">[</span><span class="o">-</span><span class="mf">90.</span> <span class="o">-</span><span class="mf">87.5</span> <span class="o">-</span><span class="mf">85.</span> <span class="o">-</span><span class="mf">82.5</span> <span class="o">-</span><span class="mf">80.</span> <span class="o">-</span><span class="mf">77.5</span> <span class="o">-</span><span class="mf">75.</span> <span class="o">-</span><span class="mf">72.5</span> <span class="o">-</span><span class="mf">70.</span> <span class="o">-</span><span class="mf">67.5</span> <span class="o">-</span><span class="mf">65.</span> <span class="o">-</span><span class="mf">62.5</span>
1734 <span class="o">-</span><span class="mf">60.</span> <span class="o">-</span><span class="mf">57.5</span> <span class="o">-</span><span class="mf">55.</span> <span class="o">-</span><span class="mf">52.5</span> <span class="o">-</span><span class="mf">50.</span> <span class="o">-</span><span class="mf">47.5</span> <span class="o">-</span><span class="mf">45.</span> <span class="o">-</span><span class="mf">42.5</span> <span class="o">-</span><span class="mf">40.</span> <span class="o">-</span><span class="mf">37.5</span> <span class="o">-</span><span class="mf">35.</span> <span class="o">-</span><span class="mf">32.5</span>
1735 <span class="o">-</span><span class="mf">30.</span> <span class="o">-</span><span class="mf">27.5</span> <span class="o">-</span><span class="mf">25.</span> <span class="o">-</span><span class="mf">22.5</span> <span class="o">-</span><span class="mf">20.</span> <span class="o">-</span><span class="mf">17.5</span> <span class="o">-</span><span class="mf">15.</span> <span class="o">-</span><span class="mf">12.5</span> <span class="o">-</span><span class="mf">10.</span> <span class="o">-</span><span class="mf">7.5</span> <span class="o">-</span><span class="mf">5.</span> <span class="o">-</span><span class="mf">2.5</span>
1736 <span class="mf">0.</span> <span class="mf">2.5</span> <span class="mf">5.</span> <span class="mf">7.5</span> <span class="mf">10.</span> <span class="mf">12.5</span> <span class="mf">15.</span> <span class="mf">17.5</span> <span class="mf">20.</span> <span class="mf">22.5</span> <span class="mf">25.</span> <span class="mf">27.5</span>
1737 <span class="mf">30.</span> <span class="mf">32.5</span> <span class="mf">35.</span> <span class="mf">37.5</span> <span class="mf">40.</span> <span class="mf">42.5</span> <span class="mf">45.</span> <span class="mf">47.5</span> <span class="mf">50.</span> <span class="mf">52.5</span> <span class="mf">55.</span> <span class="mf">57.5</span>
1738 <span class="mf">60.</span> <span class="mf">62.5</span> <span class="mf">65.</span> <span class="mf">67.5</span> <span class="mf">70.</span> <span class="mf">72.5</span> <span class="mf">75.</span> <span class="mf">77.5</span> <span class="mf">80.</span> <span class="mf">82.5</span> <span class="mf">85.</span> <span class="mf">87.5</span>
1739 <span class="mf">90.</span> <span class="p">]</span>
1740 </code></pre></div>
1741
1742
1743 <p>Unlike NumPy's array objects, netCDF <a href="#netCDF4.Variable"><code>Variable</code></a>
1744 objects with unlimited dimensions will grow along those dimensions if you
1745 assign data outside the currently defined range of indices.</p>
1746 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># append along two unlimited dimensions by assigning to slice.</span>
1747 <span class="o">&gt;&gt;&gt;</span> <span class="n">nlats</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">dimensions</span><span class="p">[</span><span class="s2">&quot;lat&quot;</span><span class="p">])</span>
1748 <span class="o">&gt;&gt;&gt;</span> <span class="n">nlons</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">rootgrp</span><span class="o">.</span><span class="n">dimensions</span><span class="p">[</span><span class="s2">&quot;lon&quot;</span><span class="p">])</span>
1749 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;temp shape before adding data = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">temp</span><span class="o">.</span><span class="n">shape</span><span class="p">))</span>
1750 <span class="n">temp</span> <span class="n">shape</span> <span class="n">before</span> <span class="n">adding</span> <span class="n">data</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
1751 <span class="o">&gt;&gt;&gt;</span>
1752 <span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">numpy.random</span> <span class="kn">import</span> <span class="n">uniform</span>
1753 <span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">,</span> <span class="p">:,</span> <span class="p">:]</span> <span class="o">=</span> <span class="n">uniform</span><span class="p">(</span><span class="n">size</span><span class="o">=</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="n">nlats</span><span class="p">,</span> <span class="n">nlons</span><span class="p">))</span>
1754 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;temp shape after adding data = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">temp</span><span class="o">.</span><span class="n">shape</span><span class="p">))</span>
1755 <span class="n">temp</span> <span class="n">shape</span> <span class="n">after</span> <span class="n">adding</span> <span class="n">data</span> <span class="o">=</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">73</span><span class="p">,</span> <span class="mi">144</span><span class="p">)</span>
1756 <span class="o">&gt;&gt;&gt;</span>
1757 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># levels have grown, but no values yet assigned.</span>
1758 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;levels shape after adding pressure data = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">levels</span><span class="o">.</span><span class="n">shape</span><span class="p">))</span>
1759 <span class="n">levels</span> <span class="n">shape</span> <span class="n">after</span> <span class="n">adding</span> <span class="n">pressure</span> <span class="n">data</span> <span class="o">=</span> <span class="p">(</span><span class="mi">10</span><span class="p">,)</span>
1760 </code></pre></div>
1761
1762
1763 <p>Note that the size of the levels variable grows when data is appended
1764 along the <code>level</code> dimension of the variable <code>temp</code>, even though no
1765 data has yet been assigned to levels.</p>
1766 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># now, assign data to levels dimension variable.</span>
1767 <span class="o">&gt;&gt;&gt;</span> <span class="n">levels</span><span class="p">[:]</span> <span class="o">=</span> <span class="p">[</span><span class="mf">1000.</span><span class="p">,</span><span class="mf">850.</span><span class="p">,</span><span class="mf">700.</span><span class="p">,</span><span class="mf">500.</span><span class="p">,</span><span class="mf">300.</span><span class="p">,</span><span class="mf">250.</span><span class="p">,</span><span class="mf">200.</span><span class="p">,</span><span class="mf">150.</span><span class="p">,</span><span class="mf">100.</span><span class="p">,</span><span class="mf">50.</span><span class="p">]</span>
1768 </code></pre></div>
1769
1770
1771 <p>However, that there are some differences between NumPy and netCDF
1772 variable slicing rules. Slices behave as usual, being specified as a
1773 <code>start:stop:step</code> triplet. Using a scalar integer index <code>i</code> takes the ith
1774 element and reduces the rank of the output array by one. Boolean array and
1775 integer sequence indexing behaves differently for netCDF variables
1776 than for numpy arrays. Only 1-d boolean arrays and integer sequences are
1777 allowed, and these indices work independently along each dimension (similar
1778 to the way vector subscripts work in fortran). This means that</p>
1779 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">]]</span><span class="o">.</span><span class="n">shape</span>
1780 <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span>
1781 </code></pre></div>
1782
1783
1784 <p>returns an array of shape (4,4) when slicing a netCDF variable, but for a
1785 numpy array it returns an array of shape (4,).
1786 Similarly, a netCDF variable of shape <code>(2,3,4,5)</code> indexed
1787 with <code>[0, array([True, False, True]), array([False, True, True, True]), :]</code>
1788 would return a <code>(2, 3, 5)</code> array. In NumPy, this would raise an error since
1789 it would be equivalent to <code>[0, [0,1], [1,2,3], :]</code>. When slicing with integer
1790 sequences, the indices <strong><em>need not be sorted</em></strong> and <strong><em>may contain
1791 duplicates</em></strong> (both of these are new features in version 1.2.1).
1792 While this behaviour may cause some confusion for those used to NumPy's 'fancy indexing' rules,
1793 it provides a very powerful way to extract data from multidimensional netCDF
1794 variables by using logical operations on the dimension arrays to create slices.</p>
1795 <p>For example,</p>
1796 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">tempdat</span> <span class="o">=</span> <span class="n">temp</span><span class="p">[::</span><span class="mi">2</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">6</span><span class="p">],</span> <span class="n">lats</span><span class="o">&gt;</span><span class="mi">0</span><span class="p">,</span> <span class="n">lons</span><span class="o">&gt;</span><span class="mi">0</span><span class="p">]</span>
1797 </code></pre></div>
1798
1799
1800 <p>will extract time indices 0,2 and 4, pressure levels
1801 850, 500 and 200 hPa, all Northern Hemisphere latitudes and Eastern
1802 Hemisphere longitudes, resulting in a numpy array of shape (3, 3, 36, 71).</p>
1803 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;shape of fancy temp slice = </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">tempdat</span><span class="o">.</span><span class="n">shape</span><span class="p">))</span>
1804 <span class="n">shape</span> <span class="n">of</span> <span class="n">fancy</span> <span class="n">temp</span> <span class="nb">slice</span> <span class="o">=</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">36</span><span class="p">,</span> <span class="mi">71</span><span class="p">)</span>
1805 </code></pre></div>
1806
1807
1808 <p><strong><em>Special note for scalar variables</em></strong>: To extract data from a scalar variable
1809 <code>v</code> with no associated dimensions, use <code>numpy.asarray(v)</code> or <code>v[...]</code>.
1810 The result will be a numpy scalar array.</p>
1811 <p>By default, netcdf4-python returns numpy masked arrays with values equal to the
1812 <code>missing_value</code> or <code>_FillValue</code> variable attributes masked. The
1813 <a href="#netCDF4.Dataset.set_auto_mask"><code>set_auto_mask</code></a> <a href="#netCDF4.Dataset"><code>Dataset</code></a> and <a href="#netCDF4.Variable"><code>Variable</code></a> methods
1814 can be used to disable this feature so that
1815 numpy arrays are always returned, with the missing values included. Prior to
1816 version 1.4.0 the default behavior was to only return masked arrays when the
1817 requested slice contained missing values. This behavior can be recovered
1818 using the <a href="#netCDF4.Dataset.set_always_mask"><code>set_always_mask</code></a> method. If a masked array is
1819 written to a netCDF variable, the masked elements are filled with the
1820 value specified by the <code>missing_value</code> attribute. If the variable has
1821 no <code>missing_value</code>, the <code>_FillValue</code> is used instead.</p>
1822 <h2><div id='section7'>7) Dealing with time coordinates.</h2>
1823 <p>Time coordinate values pose a special challenge to netCDF users. Most
1824 metadata standards (such as CF) specify that time should be
1825 measure relative to a fixed date using a certain calendar, with units
1826 specified like <code>hours since YY-MM-DD hh:mm:ss</code>. These units can be
1827 awkward to deal with, without a utility to convert the values to and
1828 from calendar dates. The function called <a href="#netCDF4.num2date"><code>num2date</code></a> and <a href="#netCDF4.date2num"><code>date2num</code></a> are
1829 provided with this package to do just that (starting with version 1.4.0, the
1830 <a href="https://unidata.github.io/cftime">cftime</a> package must be installed
1831 separately). Here's an example of how they
1832 can be used:</p>
1833 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># fill in times.</span>
1834 <span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">timedelta</span>
1835 <span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">num2date</span><span class="p">,</span> <span class="n">date2num</span>
1836 <span class="o">&gt;&gt;&gt;</span> <span class="n">dates</span> <span class="o">=</span> <span class="p">[</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span><span class="o">+</span><span class="n">n</span><span class="o">*</span><span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">12</span><span class="p">)</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">temp</span><span class="o">.</span><span class="n">shape</span><span class="p">[</span><span class="mi">0</span><span class="p">])]</span>
1837 <span class="o">&gt;&gt;&gt;</span> <span class="n">times</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">date2num</span><span class="p">(</span><span class="n">dates</span><span class="p">,</span><span class="n">units</span><span class="o">=</span><span class="n">times</span><span class="o">.</span><span class="n">units</span><span class="p">,</span><span class="n">calendar</span><span class="o">=</span><span class="n">times</span><span class="o">.</span><span class="n">calendar</span><span class="p">)</span>
1838 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;time values (in units </span><span class="si">{}</span><span class="s2">):</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">times</span><span class="o">.</span><span class="n">units</span><span class="p">,</span> <span class="n">times</span><span class="p">[:]))</span>
1839 <span class="n">time</span> <span class="n">values</span> <span class="p">(</span><span class="ow">in</span> <span class="n">units</span> <span class="n">hours</span> <span class="n">since</span> <span class="mi">0001</span><span class="o">-</span><span class="mi">01</span><span class="o">-</span><span class="mi">01</span> <span class="mi">00</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mf">00.0</span><span class="p">):</span>
1840 <span class="p">[</span><span class="mf">17533104.</span> <span class="mf">17533116.</span> <span class="mf">17533128.</span> <span class="mf">17533140.</span> <span class="mf">17533152.</span><span class="p">]</span>
1841 <span class="o">&gt;&gt;&gt;</span> <span class="n">dates</span> <span class="o">=</span> <span class="n">num2date</span><span class="p">(</span><span class="n">times</span><span class="p">[:],</span><span class="n">units</span><span class="o">=</span><span class="n">times</span><span class="o">.</span><span class="n">units</span><span class="p">,</span><span class="n">calendar</span><span class="o">=</span><span class="n">times</span><span class="o">.</span><span class="n">calendar</span><span class="p">)</span>
1842 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;dates corresponding to time values:</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">dates</span><span class="p">))</span>
1843 <span class="n">dates</span> <span class="n">corresponding</span> <span class="n">to</span> <span class="n">time</span> <span class="n">values</span><span class="p">:</span>
1844 <span class="p">[</span><span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
1845 <span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
1846 <span class="n">real_datetime</span><span class="p">(</span><span class="mi">2001</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)]</span>
1847 </code></pre></div>
1848
1849
1850 <p><a href="#netCDF4.num2date"><code>num2date</code></a> converts numeric values of time in the specified <code>units</code>
1851 and <code>calendar</code> to datetime objects, and <a href="#netCDF4.date2num"><code>date2num</code></a> does the reverse.
1852 All the calendars currently defined in the
1853 <a href="http://cfconventions.org">CF metadata convention</a> are supported.
1854 A function called <a href="#netCDF4.date2index"><code>date2index</code></a> is also provided which returns the indices
1855 of a netCDF time variable corresponding to a sequence of datetime instances.</p>
1856 <h2><div id='section8'>8) Reading data from a multi-file netCDF dataset.</h2>
1857 <p>If you want to read data from a variable that spans multiple netCDF files,
1858 you can use the <a href="#netCDF4.MFDataset"><code>MFDataset</code></a> class to read the data as if it were
1859 contained in a single file. Instead of using a single filename to create
1860 a <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance, create a <a href="#netCDF4.MFDataset"><code>MFDataset</code></a> instance with either a list
1861 of filenames, or a string with a wildcard (which is then converted to
1862 a sorted list of files using the python glob module).
1863 Variables in the list of files that share the same unlimited
1864 dimension are aggregated together, and can be sliced across multiple
1865 files. To illustrate this, let's first create a bunch of netCDF files with
1866 the same variable (with the same unlimited dimension). The files
1867 must in be in <code>NETCDF3_64BIT_OFFSET</code>, <code>NETCDF3_64BIT_DATA</code>, <code>NETCDF3_CLASSIC</code> or
1868 <code>NETCDF4_CLASSIC</code> format (<code>NETCDF4</code> formatted multi-file
1869 datasets are not supported).</p>
1870 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">nf</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
1871 <span class="o">...</span> <span class="k">with</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;mftest</span><span class="si">%s</span><span class="s2">.nc&quot;</span> <span class="o">%</span> <span class="n">nf</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s2">&quot;NETCDF4_CLASSIC&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
1872 <span class="o">...</span> <span class="n">_</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1873 <span class="o">...</span> <span class="n">x</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="s2">&quot;i&quot;</span><span class="p">,(</span><span class="s2">&quot;x&quot;</span><span class="p">,))</span>
1874 <span class="o">...</span> <span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">nf</span><span class="o">*</span><span class="mi">10</span><span class="p">,</span><span class="mi">10</span><span class="o">*</span><span class="p">(</span><span class="n">nf</span><span class="o">+</span><span class="mi">1</span><span class="p">))</span>
1875 </code></pre></div>
1876
1877
1878 <p>Now read all the files back in at once with <a href="#netCDF4.MFDataset"><code>MFDataset</code></a></p>
1879 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">MFDataset</span>
1880 <span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">MFDataset</span><span class="p">(</span><span class="s2">&quot;mftest*nc&quot;</span><span class="p">)</span>
1881 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;x&quot;</span><span class="p">][:])</span>
1882 <span class="p">[</span> <span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span> <span class="mi">5</span> <span class="mi">6</span> <span class="mi">7</span> <span class="mi">8</span> <span class="mi">9</span> <span class="mi">10</span> <span class="mi">11</span> <span class="mi">12</span> <span class="mi">13</span> <span class="mi">14</span> <span class="mi">15</span> <span class="mi">16</span> <span class="mi">17</span> <span class="mi">18</span> <span class="mi">19</span> <span class="mi">20</span> <span class="mi">21</span> <span class="mi">22</span> <span class="mi">23</span>
1883 <span class="mi">24</span> <span class="mi">25</span> <span class="mi">26</span> <span class="mi">27</span> <span class="mi">28</span> <span class="mi">29</span> <span class="mi">30</span> <span class="mi">31</span> <span class="mi">32</span> <span class="mi">33</span> <span class="mi">34</span> <span class="mi">35</span> <span class="mi">36</span> <span class="mi">37</span> <span class="mi">38</span> <span class="mi">39</span> <span class="mi">40</span> <span class="mi">41</span> <span class="mi">42</span> <span class="mi">43</span> <span class="mi">44</span> <span class="mi">45</span> <span class="mi">46</span> <span class="mi">47</span>
1884 <span class="mi">48</span> <span class="mi">49</span> <span class="mi">50</span> <span class="mi">51</span> <span class="mi">52</span> <span class="mi">53</span> <span class="mi">54</span> <span class="mi">55</span> <span class="mi">56</span> <span class="mi">57</span> <span class="mi">58</span> <span class="mi">59</span> <span class="mi">60</span> <span class="mi">61</span> <span class="mi">62</span> <span class="mi">63</span> <span class="mi">64</span> <span class="mi">65</span> <span class="mi">66</span> <span class="mi">67</span> <span class="mi">68</span> <span class="mi">69</span> <span class="mi">70</span> <span class="mi">71</span>
1885 <span class="mi">72</span> <span class="mi">73</span> <span class="mi">74</span> <span class="mi">75</span> <span class="mi">76</span> <span class="mi">77</span> <span class="mi">78</span> <span class="mi">79</span> <span class="mi">80</span> <span class="mi">81</span> <span class="mi">82</span> <span class="mi">83</span> <span class="mi">84</span> <span class="mi">85</span> <span class="mi">86</span> <span class="mi">87</span> <span class="mi">88</span> <span class="mi">89</span> <span class="mi">90</span> <span class="mi">91</span> <span class="mi">92</span> <span class="mi">93</span> <span class="mi">94</span> <span class="mi">95</span>
1886 <span class="mi">96</span> <span class="mi">97</span> <span class="mi">98</span> <span class="mi">99</span><span class="p">]</span>
1887 </code></pre></div>
1888
1889
1890 <p>Note that <a href="#netCDF4.MFDataset"><code>MFDataset</code></a> can only be used to read, not write, multi-file
1891 datasets.</p>
1892 <h2><div id='section9'>9) Efficient compression of netCDF variables.</h2>
1893 <p>Data stored in netCDF 4 <a href="#netCDF4.Variable"><code>Variable</code></a> objects can be compressed and
1894 decompressed on the fly. The parameters for the compression are
1895 determined by the <code>zlib</code>, <code>complevel</code> and <code>shuffle</code> keyword arguments
1896 to the <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> method. To turn on
1897 compression, set <code>zlib=True</code>. The <code>complevel</code> keyword regulates the
1898 speed and efficiency of the compression (1 being fastest, but lowest
1899 compression ratio, 9 being slowest but best compression ratio). The
1900 default value of <code>complevel</code> is 4. Setting <code>shuffle=False</code> will turn
1901 off the HDF5 shuffle filter, which de-interlaces a block of data before
1902 compression by reordering the bytes. The shuffle filter can
1903 significantly improve compression ratios, and is on by default. Setting
1904 <code>fletcher32</code> keyword argument to
1905 <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> to <code>True</code> (it's <code>False</code> by
1906 default) enables the Fletcher32 checksum algorithm for error detection.
1907 It's also possible to set the HDF5 chunking parameters and endian-ness
1908 of the binary data stored in the HDF5 file with the <code>chunksizes</code>
1909 and <code>endian</code> keyword arguments to
1910 <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a>. These keyword arguments only
1911 are relevant for <code>NETCDF4</code> and <code>NETCDF4_CLASSIC</code> files (where the
1912 underlying file format is HDF5) and are silently ignored if the file
1913 format is <code>NETCDF3_CLASSIC</code>, <code>NETCDF3_64BIT_OFFSET</code> or <code>NETCDF3_64BIT_DATA</code>.</p>
1914 <p>If your data only has a certain number of digits of precision (say for
1915 example, it is temperature data that was measured with a precision of
1916 0.1 degrees), you can dramatically improve zlib compression by
1917 quantizing (or truncating) the data using the <code>least_significant_digit</code>
1918 keyword argument to <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a>. The least
1919 significant digit is the power of ten of the smallest decimal place in
1920 the data that is a reliable value. For example if the data has a
1921 precision of 0.1, then setting <code>least_significant_digit=1</code> will cause
1922 data the data to be quantized using <code>numpy.around(scale*data)/scale</code>, where
1923 scale = 2**bits, and bits is determined so that a precision of 0.1 is
1924 retained (in this case bits=4). Effectively, this makes the compression
1925 'lossy' instead of 'lossless', that is some precision in the data is
1926 sacrificed for the sake of disk space.</p>
1927 <p>In our example, try replacing the line</p>
1928 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,))</span>
1929 </code></pre></div>
1930
1931
1932 <p>with</p>
1933 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,),</span><span class="n">zlib</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
1934 </code></pre></div>
1935
1936
1937 <p>and then</p>
1938 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">temp</span> <span class="o">=</span> <span class="n">rootgrp</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;temp&quot;</span><span class="p">,</span><span class="s2">&quot;f4&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;level&quot;</span><span class="p">,</span><span class="s2">&quot;lat&quot;</span><span class="p">,</span><span class="s2">&quot;lon&quot;</span><span class="p">,),</span><span class="n">zlib</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span><span class="n">least_significant_digit</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
1939 </code></pre></div>
1940
1941
1942 <p>and see how much smaller the resulting files are.</p>
1943 <h2><div id='section10'>10) Beyond homogeneous arrays of a fixed type - compound data types.</h2>
1944 <p>Compound data types map directly to numpy structured (a.k.a 'record')
1945 arrays. Structured arrays are akin to C structs, or derived types
1946 in Fortran. They allow for the construction of table-like structures
1947 composed of combinations of other data types, including other
1948 compound types. Compound types might be useful for representing multiple
1949 parameter values at each point on a grid, or at each time and space
1950 location for scattered (point) data. You can then access all the
1951 information for a point by reading one variable, instead of reading
1952 different parameters from different variables. Compound data types
1953 are created from the corresponding numpy data type using the
1954 <a href="#netCDF4.Dataset.createCompoundType"><code>createCompoundType</code></a> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance.
1955 Since there is no native complex data type in netcdf, compound types are handy
1956 for storing numpy complex arrays. Here's an example:</p>
1957 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;complex.nc&quot;</span><span class="p">,</span><span class="s2">&quot;w&quot;</span><span class="p">)</span>
1958 <span class="o">&gt;&gt;&gt;</span> <span class="n">size</span> <span class="o">=</span> <span class="mi">3</span> <span class="c1"># length of 1-d complex array</span>
1959 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create sample complex data.</span>
1960 <span class="o">&gt;&gt;&gt;</span> <span class="n">datac</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">exp</span><span class="p">(</span><span class="mi">1</span><span class="n">j</span><span class="o">*</span><span class="p">(</span><span class="mf">1.</span><span class="o">+</span><span class="n">numpy</span><span class="o">.</span><span class="n">linspace</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">numpy</span><span class="o">.</span><span class="n">pi</span><span class="p">,</span> <span class="n">size</span><span class="p">)))</span>
1961 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create complex128 compound data type.</span>
1962 <span class="o">&gt;&gt;&gt;</span> <span class="n">complex128</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">dtype</span><span class="p">([(</span><span class="s2">&quot;real&quot;</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">float64</span><span class="p">),(</span><span class="s2">&quot;imag&quot;</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">float64</span><span class="p">)])</span>
1963 <span class="o">&gt;&gt;&gt;</span> <span class="n">complex128_t</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createCompoundType</span><span class="p">(</span><span class="n">complex128</span><span class="p">,</span><span class="s2">&quot;complex128&quot;</span><span class="p">)</span>
1964 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a variable with this data type, write some data to it.</span>
1965 <span class="o">&gt;&gt;&gt;</span> <span class="n">x_dim</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;x_dim&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
1966 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;cmplx_var&quot;</span><span class="p">,</span><span class="n">complex128_t</span><span class="p">,</span><span class="s2">&quot;x_dim&quot;</span><span class="p">)</span>
1967 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="n">size</span><span class="p">,</span><span class="n">complex128</span><span class="p">)</span> <span class="c1"># numpy structured array</span>
1968 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span><span class="p">[</span><span class="s2">&quot;real&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datac</span><span class="o">.</span><span class="n">real</span><span class="p">;</span> <span class="n">data</span><span class="p">[</span><span class="s2">&quot;imag&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datac</span><span class="o">.</span><span class="n">imag</span>
1969 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span> <span class="c1"># write numpy structured array to netcdf compound var</span>
1970 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># close and reopen the file, check the contents.</span>
1971 <span class="o">&gt;&gt;&gt;</span> <span class="n">f</span><span class="o">.</span><span class="n">close</span><span class="p">();</span> <span class="n">f</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;complex.nc&quot;</span><span class="p">)</span>
1972 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;cmplx_var&quot;</span><span class="p">]</span>
1973 <span class="o">&gt;&gt;&gt;</span> <span class="n">datain</span> <span class="o">=</span> <span class="n">v</span><span class="p">[:]</span> <span class="c1"># read in all the data into a numpy structured array</span>
1974 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create an empty numpy complex array</span>
1975 <span class="o">&gt;&gt;&gt;</span> <span class="n">datac2</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="n">datain</span><span class="o">.</span><span class="n">shape</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">complex128</span><span class="p">)</span>
1976 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># .. fill it with contents of structured array.</span>
1977 <span class="o">&gt;&gt;&gt;</span> <span class="n">datac2</span><span class="o">.</span><span class="n">real</span> <span class="o">=</span> <span class="n">datain</span><span class="p">[</span><span class="s2">&quot;real&quot;</span><span class="p">];</span> <span class="n">datac2</span><span class="o">.</span><span class="n">imag</span> <span class="o">=</span> <span class="n">datain</span><span class="p">[</span><span class="s2">&quot;imag&quot;</span><span class="p">]</span>
1978 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">{}</span><span class="s1">: </span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">datac</span><span class="o">.</span><span class="n">dtype</span><span class="p">,</span> <span class="n">datac</span><span class="p">))</span> <span class="c1"># original data</span>
1979 <span class="n">complex128</span><span class="p">:</span> <span class="p">[</span> <span class="mf">0.54030231</span><span class="o">+</span><span class="mf">0.84147098</span><span class="n">j</span> <span class="o">-</span><span class="mf">0.84147098</span><span class="o">+</span><span class="mf">0.54030231</span><span class="n">j</span> <span class="o">-</span><span class="mf">0.54030231</span><span class="o">-</span><span class="mf">0.84147098</span><span class="n">j</span><span class="p">]</span>
1980 <span class="o">&gt;&gt;&gt;</span>
1981 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">{}</span><span class="s1">: </span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">datac2</span><span class="o">.</span><span class="n">dtype</span><span class="p">,</span> <span class="n">datac2</span><span class="p">))</span> <span class="c1"># data from file</span>
1982 <span class="n">complex128</span><span class="p">:</span> <span class="p">[</span> <span class="mf">0.54030231</span><span class="o">+</span><span class="mf">0.84147098</span><span class="n">j</span> <span class="o">-</span><span class="mf">0.84147098</span><span class="o">+</span><span class="mf">0.54030231</span><span class="n">j</span> <span class="o">-</span><span class="mf">0.54030231</span><span class="o">-</span><span class="mf">0.84147098</span><span class="n">j</span><span class="p">]</span>
1983 </code></pre></div>
1984
1985
1986 <p>Compound types can be nested, but you must create the 'inner'
1987 ones first. All possible numpy structured arrays cannot be
1988 represented as Compound variables - an error message will be
1989 raise if you try to create one that is not supported.
1990 All of the compound types defined for a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> are stored
1991 in a Python dictionary, just like variables and dimensions. As always, printing
1992 objects gives useful summary information in an interactive session:</p>
1993 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
1994 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
1995 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
1996 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x_dim</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
1997 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="p">{</span><span class="s1">&#39;names&#39;</span><span class="p">:[</span><span class="s1">&#39;real&#39;</span><span class="p">,</span><span class="s1">&#39;imag&#39;</span><span class="p">],</span> <span class="s1">&#39;formats&#39;</span><span class="p">:[</span><span class="s1">&#39;&lt;f8&#39;</span><span class="p">,</span><span class="s1">&#39;&lt;f8&#39;</span><span class="p">],</span> <span class="s1">&#39;offsets&#39;</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">8</span><span class="p">],</span> <span class="s1">&#39;itemsize&#39;</span><span class="p">:</span><span class="mi">16</span><span class="p">,</span> <span class="s1">&#39;aligned&#39;</span><span class="p">:</span><span class="kc">True</span><span class="p">}</span> <span class="n">cmplx_var</span><span class="p">(</span><span class="n">x_dim</span><span class="p">)</span>
1998 <span class="n">groups</span><span class="p">:</span>
1999 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;cmplx_var&quot;</span><span class="p">])</span>
2000 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
2001 <span class="n">compound</span> <span class="n">cmplx_var</span><span class="p">(</span><span class="n">x_dim</span><span class="p">)</span>
2002 <span class="n">compound</span> <span class="n">data</span> <span class="nb">type</span><span class="p">:</span> <span class="p">{</span><span class="s1">&#39;names&#39;</span><span class="p">:[</span><span class="s1">&#39;real&#39;</span><span class="p">,</span><span class="s1">&#39;imag&#39;</span><span class="p">],</span> <span class="s1">&#39;formats&#39;</span><span class="p">:[</span><span class="s1">&#39;&lt;f8&#39;</span><span class="p">,</span><span class="s1">&#39;&lt;f8&#39;</span><span class="p">],</span> <span class="s1">&#39;offsets&#39;</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">8</span><span class="p">],</span> <span class="s1">&#39;itemsize&#39;</span><span class="p">:</span><span class="mi">16</span><span class="p">,</span> <span class="s1">&#39;aligned&#39;</span><span class="p">:</span><span class="kc">True</span><span class="p">}</span>
2003 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">x_dim</span>
2004 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">3</span><span class="p">,)</span>
2005 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">cmptypes</span><span class="p">)</span>
2006 <span class="p">{</span><span class="s1">&#39;complex128&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">CompoundType</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">complex128</span><span class="s1">&#39;, numpy dtype = {&#39;</span><span class="n">names</span><span class="s1">&#39;:[&#39;</span><span class="n">real</span><span class="s1">&#39;,&#39;</span><span class="n">imag</span><span class="s1">&#39;], &#39;</span><span class="n">formats</span><span class="s1">&#39;:[&#39;</span><span class="o">&lt;</span><span class="n">f8</span><span class="s1">&#39;,&#39;</span><span class="o">&lt;</span><span class="n">f8</span><span class="s1">&#39;], &#39;</span><span class="n">offsets</span><span class="s1">&#39;:[0,8], &#39;</span><span class="n">itemsize</span><span class="s1">&#39;:16, &#39;</span><span class="n">aligned</span><span class="s1">&#39;:True}}</span>
2007 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">cmptypes</span><span class="p">[</span><span class="s2">&quot;complex128&quot;</span><span class="p">])</span>
2008 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">CompoundType</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">complex128</span><span class="s1">&#39;, numpy dtype = {&#39;</span><span class="n">names</span><span class="s1">&#39;:[&#39;</span><span class="n">real</span><span class="s1">&#39;,&#39;</span><span class="n">imag</span><span class="s1">&#39;], &#39;</span><span class="n">formats</span><span class="s1">&#39;:[&#39;</span><span class="o">&lt;</span><span class="n">f8</span><span class="s1">&#39;,&#39;</span><span class="o">&lt;</span><span class="n">f8</span><span class="s1">&#39;], &#39;</span><span class="n">offsets</span><span class="s1">&#39;:[0,8], &#39;</span><span class="n">itemsize</span><span class="s1">&#39;:16, &#39;</span><span class="n">aligned</span><span class="s1">&#39;:True}</span>
2009 </code></pre></div>
2010
2011
2012 <h2><div id='section11'>11) Variable-length (vlen) data types.</h2>
2013 <p>NetCDF 4 has support for variable-length or "ragged" arrays. These are arrays
2014 of variable length sequences having the same type. To create a variable-length
2015 data type, use the <a href="#netCDF4.Dataset.createVLType"><code>createVLType</code></a> method
2016 method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance.</p>
2017 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;tst_vlen.nc&quot;</span><span class="p">,</span><span class="s2">&quot;w&quot;</span><span class="p">)</span>
2018 <span class="o">&gt;&gt;&gt;</span> <span class="n">vlen_t</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVLType</span><span class="p">(</span><span class="n">numpy</span><span class="o">.</span><span class="n">int32</span><span class="p">,</span> <span class="s2">&quot;phony_vlen&quot;</span><span class="p">)</span>
2019 </code></pre></div>
2020
2021
2022 <p>The numpy datatype of the variable-length sequences and the name of the
2023 new datatype must be specified. Any of the primitive datatypes can be
2024 used (signed and unsigned integers, 32 and 64 bit floats, and characters),
2025 but compound data types cannot.
2026 A new variable can then be created using this datatype.</p>
2027 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">x</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span>
2028 <span class="o">&gt;&gt;&gt;</span> <span class="n">y</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;y&quot;</span><span class="p">,</span><span class="mi">4</span><span class="p">)</span>
2029 <span class="o">&gt;&gt;&gt;</span> <span class="n">vlvar</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;phony_vlen_var&quot;</span><span class="p">,</span> <span class="n">vlen_t</span><span class="p">,</span> <span class="p">(</span><span class="s2">&quot;y&quot;</span><span class="p">,</span><span class="s2">&quot;x&quot;</span><span class="p">))</span>
2030 </code></pre></div>
2031
2032
2033 <p>Since there is no native vlen datatype in numpy, vlen arrays are represented
2034 in python as object arrays (arrays of dtype <code>object</code>). These are arrays whose
2035 elements are Python object pointers, and can contain any type of python object.
2036 For this application, they must contain 1-D numpy arrays all of the same type
2037 but of varying length.
2038 In this case, they contain 1-D numpy <code>int32</code> arrays of random length between
2039 1 and 10.</p>
2040 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">random</span>
2041 <span class="o">&gt;&gt;&gt;</span> <span class="n">random</span><span class="o">.</span><span class="n">seed</span><span class="p">(</span><span class="mi">54321</span><span class="p">)</span>
2042 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">y</span><span class="p">)</span><span class="o">*</span><span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">),</span><span class="nb">object</span><span class="p">)</span>
2043 <span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">y</span><span class="p">)</span><span class="o">*</span><span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">)):</span>
2044 <span class="o">...</span> <span class="n">data</span><span class="p">[</span><span class="n">n</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">10</span><span class="p">),</span><span class="n">dtype</span><span class="o">=</span><span class="s2">&quot;int32&quot;</span><span class="p">)</span><span class="o">+</span><span class="mi">1</span>
2045 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">reshape</span><span class="p">(</span><span class="n">data</span><span class="p">,(</span><span class="nb">len</span><span class="p">(</span><span class="n">y</span><span class="p">),</span><span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">)))</span>
2046 <span class="o">&gt;&gt;&gt;</span> <span class="n">vlvar</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span>
2047 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;vlen variable =</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">vlvar</span><span class="p">[:]))</span>
2048 <span class="n">vlen</span> <span class="n">variable</span> <span class="o">=</span>
2049 <span class="p">[[</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span> <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
2050 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)]</span>
2051 <span class="p">[</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
2052 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
2053 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)]</span>
2054 <span class="p">[</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span> <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
2055 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)]</span>
2056 <span class="p">[</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span>
2057 <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)</span> <span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="n">int32</span><span class="p">)]]</span>
2058 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
2059 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
2060 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
2061 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="n">y</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>
2062 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">phony_vlen_var</span><span class="p">(</span><span class="n">y</span><span class="p">,</span><span class="n">x</span><span class="p">)</span>
2063 <span class="n">groups</span><span class="p">:</span>
2064 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;phony_vlen_var&quot;</span><span class="p">])</span>
2065 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
2066 <span class="n">vlen</span> <span class="n">phony_vlen_var</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span>
2067 <span class="n">vlen</span> <span class="n">data</span> <span class="nb">type</span><span class="p">:</span> <span class="n">int32</span>
2068 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span>
2069 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
2070 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">vltypes</span><span class="p">[</span><span class="s2">&quot;phony_vlen&quot;</span><span class="p">])</span>
2071 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">VLType</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">phony_vlen</span><span class="s1">&#39;, numpy dtype = int32</span>
2072 </code></pre></div>
2073
2074
2075 <p>Numpy object arrays containing python strings can also be written as vlen
2076 variables, For vlen strings, you don't need to create a vlen data type.
2077 Instead, simply use the python <code>str</code> builtin (or a numpy string datatype
2078 with fixed length greater than 1) when calling the
2079 <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> method.</p>
2080 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">z</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;z&quot;</span><span class="p">,</span><span class="mi">10</span><span class="p">)</span>
2081 <span class="o">&gt;&gt;&gt;</span> <span class="n">strvar</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;strvar&quot;</span><span class="p">,</span> <span class="nb">str</span><span class="p">,</span> <span class="s2">&quot;z&quot;</span><span class="p">)</span>
2082 </code></pre></div>
2083
2084
2085 <p>In this example, an object array is filled with random python strings with
2086 random lengths between 2 and 12 characters, and the data in the object
2087 array is assigned to the vlen string variable.</p>
2088 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">chars</span> <span class="o">=</span> <span class="s2">&quot;1234567890aabcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ&quot;</span>
2089 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="s2">&quot;O&quot;</span><span class="p">)</span>
2090 <span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
2091 <span class="o">...</span> <span class="n">stringlen</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">12</span><span class="p">)</span>
2092 <span class="o">...</span> <span class="n">data</span><span class="p">[</span><span class="n">n</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">chars</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">stringlen</span><span class="p">)])</span>
2093 <span class="o">&gt;&gt;&gt;</span> <span class="n">strvar</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span>
2094 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;variable-length string variable:</span><span class="se">\n</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">strvar</span><span class="p">[:]))</span>
2095 <span class="n">variable</span><span class="o">-</span><span class="n">length</span> <span class="n">string</span> <span class="n">variable</span><span class="p">:</span>
2096 <span class="p">[</span><span class="s1">&#39;Lh&#39;</span> <span class="s1">&#39;25F8wBbMI&#39;</span> <span class="s1">&#39;53rmM&#39;</span> <span class="s1">&#39;vvjnb3t63ao&#39;</span> <span class="s1">&#39;qjRBQk6w&#39;</span> <span class="s1">&#39;aJh&#39;</span> <span class="s1">&#39;QF&#39;</span>
2097 <span class="s1">&#39;jtIJbJACaQk4&#39;</span> <span class="s1">&#39;3Z5&#39;</span> <span class="s1">&#39;bftIIq&#39;</span><span class="p">]</span>
2098 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
2099 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
2100 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
2101 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="n">y</span><span class="p">(</span><span class="mi">4</span><span class="p">),</span> <span class="n">z</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
2102 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">phony_vlen_var</span><span class="p">(</span><span class="n">y</span><span class="p">,</span><span class="n">x</span><span class="p">),</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">str</span><span class="s1">&#39;&gt; strvar(z)</span>
2103 <span class="n">groups</span><span class="p">:</span>
2104 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;strvar&quot;</span><span class="p">])</span>
2105 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
2106 <span class="n">vlen</span> <span class="n">strvar</span><span class="p">(</span><span class="n">z</span><span class="p">)</span>
2107 <span class="n">vlen</span> <span class="n">data</span> <span class="nb">type</span><span class="p">:</span> <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">str</span><span class="s1">&#39;&gt;</span>
2108 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span>
2109 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">10</span><span class="p">,)</span>
2110 </code></pre></div>
2111
2112
2113 <p>It is also possible to set contents of vlen string variables with numpy arrays
2114 of any string or unicode data type. Note, however, that accessing the contents
2115 of such variables will always return numpy arrays with dtype <code>object</code>.</p>
2116 <h2><div id='section12'>12) Enum data type.</h2>
2117 <p>netCDF4 has an enumerated data type, which is an integer datatype that is
2118 restricted to certain named values. Since Enums don't map directly to
2119 a numpy data type, they are read and written as integer arrays.</p>
2120 <p>Here's an example of using an Enum type to hold cloud type data.
2121 The base integer data type and a python dictionary describing the allowed
2122 values and their names are used to define an Enum data type using
2123 <a href="#netCDF4.Dataset.createEnumType"><code>createEnumType</code></a>.</p>
2124 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;clouds.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">)</span>
2125 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># python dict with allowed values and their names.</span>
2126 <span class="o">&gt;&gt;&gt;</span> <span class="n">enum_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;Altocumulus&#39;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span> <span class="s1">&#39;Missing&#39;</span><span class="p">:</span> <span class="mi">255</span><span class="p">,</span>
2127 <span class="o">...</span> <span class="s1">&#39;Stratus&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;Clear&#39;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
2128 <span class="o">...</span> <span class="s1">&#39;Nimbostratus&#39;</span><span class="p">:</span> <span class="mi">6</span><span class="p">,</span> <span class="s1">&#39;Cumulus&#39;</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span> <span class="s1">&#39;Altostratus&#39;</span><span class="p">:</span> <span class="mi">5</span><span class="p">,</span>
2129 <span class="o">...</span> <span class="s1">&#39;Cumulonimbus&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;Stratocumulus&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">}</span>
2130 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create the Enum type called &#39;cloud_t&#39;.</span>
2131 <span class="o">&gt;&gt;&gt;</span> <span class="n">cloud_type</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createEnumType</span><span class="p">(</span><span class="n">numpy</span><span class="o">.</span><span class="n">uint8</span><span class="p">,</span><span class="s1">&#39;cloud_t&#39;</span><span class="p">,</span><span class="n">enum_dict</span><span class="p">)</span>
2132 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">cloud_type</span><span class="p">)</span>
2133 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">EnumType</span><span class="s1">&#39;&gt;: name = &#39;</span><span class="n">cloud_t</span><span class="s1">&#39;, numpy dtype = uint8, fields/values ={&#39;</span><span class="n">Altocumulus</span><span class="s1">&#39;: 7, &#39;</span><span class="n">Missing</span><span class="s1">&#39;: 255, &#39;</span><span class="n">Stratus</span><span class="s1">&#39;: 2, &#39;</span><span class="n">Clear</span><span class="s1">&#39;: 0, &#39;</span><span class="n">Nimbostratus</span><span class="s1">&#39;: 6, &#39;</span><span class="n">Cumulus</span><span class="s1">&#39;: 4, &#39;</span><span class="n">Altostratus</span><span class="s1">&#39;: 5, &#39;</span><span class="n">Cumulonimbus</span><span class="s1">&#39;: 1, &#39;</span><span class="n">Stratocumulus</span><span class="s1">&#39;: 3}</span>
2134 </code></pre></div>
2135
2136
2137 <p>A new variable can be created in the usual way using this data type.
2138 Integer data is written to the variable that represents the named
2139 cloud types in enum_dict. A <code>ValueError</code> will be raised if an attempt
2140 is made to write an integer value not associated with one of the
2141 specified names.</p>
2142 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">time</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;time&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
2143 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a 1d variable of type &#39;cloud_type&#39;.</span>
2144 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># The fill_value is set to the &#39;Missing&#39; named value.</span>
2145 <span class="o">&gt;&gt;&gt;</span> <span class="n">cloud_var</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;primary_cloud&#39;</span><span class="p">,</span><span class="n">cloud_type</span><span class="p">,</span><span class="s1">&#39;time&#39;</span><span class="p">,</span>
2146 <span class="o">...</span> <span class="n">fill_value</span><span class="o">=</span><span class="n">enum_dict</span><span class="p">[</span><span class="s1">&#39;Missing&#39;</span><span class="p">])</span>
2147 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># write some data to the variable.</span>
2148 <span class="o">&gt;&gt;&gt;</span> <span class="n">cloud_var</span><span class="p">[:]</span> <span class="o">=</span> <span class="p">[</span><span class="n">enum_dict</span><span class="p">[</span><span class="n">k</span><span class="p">]</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">&#39;Clear&#39;</span><span class="p">,</span> <span class="s1">&#39;Stratus&#39;</span><span class="p">,</span> <span class="s1">&#39;Cumulus&#39;</span><span class="p">,</span>
2149 <span class="o">...</span> <span class="s1">&#39;Missing&#39;</span><span class="p">,</span> <span class="s1">&#39;Cumulonimbus&#39;</span><span class="p">]]</span>
2150 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
2151 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># reopen the file, read the data.</span>
2152 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;clouds.nc&#39;</span><span class="p">)</span>
2153 <span class="o">&gt;&gt;&gt;</span> <span class="n">cloud_var</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s1">&#39;primary_cloud&#39;</span><span class="p">]</span>
2154 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">cloud_var</span><span class="p">)</span>
2155 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Variable</span><span class="s1">&#39;&gt;</span>
2156 <span class="n">enum</span> <span class="n">primary_cloud</span><span class="p">(</span><span class="n">time</span><span class="p">)</span>
2157 <span class="n">_FillValue</span><span class="p">:</span> <span class="mi">255</span>
2158 <span class="n">enum</span> <span class="n">data</span> <span class="nb">type</span><span class="p">:</span> <span class="n">uint8</span>
2159 <span class="n">unlimited</span> <span class="n">dimensions</span><span class="p">:</span> <span class="n">time</span>
2160 <span class="n">current</span> <span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">5</span><span class="p">,)</span>
2161 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">cloud_var</span><span class="o">.</span><span class="n">datatype</span><span class="o">.</span><span class="n">enum_dict</span><span class="p">)</span>
2162 <span class="p">{</span><span class="s1">&#39;Altocumulus&#39;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span> <span class="s1">&#39;Missing&#39;</span><span class="p">:</span> <span class="mi">255</span><span class="p">,</span> <span class="s1">&#39;Stratus&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;Clear&#39;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s1">&#39;Nimbostratus&#39;</span><span class="p">:</span> <span class="mi">6</span><span class="p">,</span> <span class="s1">&#39;Cumulus&#39;</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span> <span class="s1">&#39;Altostratus&#39;</span><span class="p">:</span> <span class="mi">5</span><span class="p">,</span> <span class="s1">&#39;Cumulonimbus&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;Stratocumulus&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">}</span>
2163 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">cloud_var</span><span class="p">[:])</span>
2164 <span class="p">[</span><span class="mi">0</span> <span class="mi">2</span> <span class="mi">4</span> <span class="o">--</span> <span class="mi">1</span><span class="p">]</span>
2165 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
2166 </code></pre></div>
2167
2168
2169 <h2><div id='section13'>13) Parallel IO.</h2>
2170 <p>If MPI parallel enabled versions of netcdf and hdf5 or pnetcdf are detected,
2171 and <a href="https://mpi4py.scipy.org">mpi4py</a> is installed, netcdf4-python will
2172 be built with parallel IO capabilities enabled. Parallel IO of NETCDF4 or
2173 NETCDF4_CLASSIC formatted files is only available if the MPI parallel HDF5
2174 library is available. Parallel IO of classic netcdf-3 file formats is only
2175 available if the <a href="https://parallel-netcdf.github.io/">PnetCDF</a> library is
2176 available. To use parallel IO, your program must be running in an MPI
2177 environment using <a href="https://mpi4py.scipy.org">mpi4py</a>.</p>
2178 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">mpi4py</span> <span class="kn">import</span> <span class="n">MPI</span>
2179 <span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
2180 <span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">Dataset</span>
2181 <span class="o">&gt;&gt;&gt;</span> <span class="n">rank</span> <span class="o">=</span> <span class="n">MPI</span><span class="o">.</span><span class="n">COMM_WORLD</span><span class="o">.</span><span class="n">rank</span> <span class="c1"># The process ID (integer 0-3 for 4-process run)</span>
2182 </code></pre></div>
2183
2184
2185 <p>To run an MPI-based parallel program like this, you must use <code>mpiexec</code> to launch several
2186 parallel instances of Python (for example, using <code>mpiexec -np 4 python mpi_example.py</code>).
2187 The parallel features of netcdf4-python are mostly transparent -
2188 when a new dataset is created or an existing dataset is opened,
2189 use the <code>parallel</code> keyword to enable parallel access.</p>
2190 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;parallel_test.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">,</span><span class="n">parallel</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
2191 </code></pre></div>
2192
2193
2194 <p>The optional <code>comm</code> keyword may be used to specify a particular
2195 MPI communicator (<code>MPI_COMM_WORLD</code> is used by default). Each process (or rank)
2196 can now write to the file indepedently. In this example the process rank is
2197 written to a different variable index on each task</p>
2198 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">d</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;dim&#39;</span><span class="p">,</span><span class="mi">4</span><span class="p">)</span>
2199 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;var&#39;</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">int</span><span class="p">,</span> <span class="s1">&#39;dim&#39;</span><span class="p">)</span>
2200 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[</span><span class="n">rank</span><span class="p">]</span> <span class="o">=</span> <span class="n">rank</span>
2201 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
2202
2203 <span class="o">%</span> <span class="n">ncdump</span> <span class="n">parallel_test</span><span class="o">.</span><span class="n">nc</span>
2204 <span class="n">netcdf</span> <span class="n">parallel_test</span> <span class="p">{</span>
2205 <span class="n">dimensions</span><span class="p">:</span>
2206 <span class="n">dim</span> <span class="o">=</span> <span class="mi">4</span> <span class="p">;</span>
2207 <span class="n">variables</span><span class="p">:</span>
2208 <span class="n">int64</span> <span class="n">var</span><span class="p">(</span><span class="n">dim</span><span class="p">)</span> <span class="p">;</span>
2209 <span class="n">data</span><span class="p">:</span>
2210
2211 <span class="n">var</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span> <span class="p">;</span>
2212 <span class="p">}</span>
2213 </code></pre></div>
2214
2215
2216 <p>There are two types of parallel IO, independent (the default) and collective.
2217 Independent IO means that each process can do IO independently. It should not
2218 depend on or be affected by other processes. Collective IO is a way of doing
2219 IO defined in the MPI-IO standard; unlike independent IO, all processes must
2220 participate in doing IO. To toggle back and forth between
2221 the two types of IO, use the <a href="#netCDF4.Variable.set_collective"><code>set_collective</code></a>
2222 <a href="#netCDF4.Variable"><code>Variable</code></a>method. All metadata
2223 operations (such as creation of groups, types, variables, dimensions, or attributes)
2224 are collective. There are a couple of important limitations of parallel IO:</p>
2225 <ul>
2226 <li>parallel IO for NETCDF4 or NETCDF4_CLASSIC formatted files is only available
2227 if the netcdf library was compiled with MPI enabled HDF5.</li>
2228 <li>parallel IO for all classic netcdf-3 file formats is only available if the
2229 netcdf library was compiled with PnetCDF.</li>
2230 <li>If a variable has an unlimited dimension, appending data must be done in collective mode.
2231 If the write is done in independent mode, the operation will fail with a
2232 a generic "HDF Error".</li>
2233 <li>You cannot write compressed data in parallel (although
2234 you can read it).</li>
2235 <li>You cannot use variable-length (VLEN) data types.</li>
2236 </ul>
2237 <h2><div id='section14'>14) Dealing with strings.</h2>
2238 <p>The most flexible way to store arrays of strings is with the
2239 <a href="#section11">Variable-length (vlen) string data type</a>. However, this requires
2240 the use of the NETCDF4 data model, and the vlen type does not map very well
2241 numpy arrays (you have to use numpy arrays of dtype=<code>object</code>, which are arrays of
2242 arbitrary python objects). numpy does have a fixed-width string array
2243 data type, but unfortunately the netCDF data model does not.
2244 Instead fixed-width byte strings are typically stored as <a href="https://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.html#bp_Strings-and-Variables-of-type-char">arrays of 8-bit
2245 characters</a>.
2246 To perform the conversion to and from character arrays to fixed-width numpy string arrays, the
2247 following convention is followed by the python interface.
2248 If the <code>_Encoding</code> special attribute is set for a character array
2249 (dtype <code>S1</code>) variable, the <a href="#netCDF4.chartostring"><code>chartostring</code></a> utility function is used to convert the array of
2250 characters to an array of strings with one less dimension (the last dimension is
2251 interpreted as the length of each string) when reading the data. The character
2252 set (usually ascii) is specified by the <code>_Encoding</code> attribute. If <code>_Encoding</code>
2253 is 'none' or 'bytes', then the character array is converted to a numpy
2254 fixed-width byte string array (dtype <code>S#</code>), otherwise a numpy unicode (dtype
2255 <code>U#</code>) array is created. When writing the data,
2256 <a href="#netCDF4.stringtochar"><code>stringtochar</code></a> is used to convert the numpy string array to an array of
2257 characters with one more dimension. For example,</p>
2258 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">stringtochar</span>
2259 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;stringtest.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">,</span><span class="nb">format</span><span class="o">=</span><span class="s1">&#39;NETCDF4_CLASSIC&#39;</span><span class="p">)</span>
2260 <span class="o">&gt;&gt;&gt;</span> <span class="n">_</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;nchars&#39;</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span>
2261 <span class="o">&gt;&gt;&gt;</span> <span class="n">_</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;nstrings&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
2262 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;strings&#39;</span><span class="p">,</span><span class="s1">&#39;S1&#39;</span><span class="p">,(</span><span class="s1">&#39;nstrings&#39;</span><span class="p">,</span><span class="s1">&#39;nchars&#39;</span><span class="p">))</span>
2263 <span class="o">&gt;&gt;&gt;</span> <span class="n">datain</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span><span class="s1">&#39;bar&#39;</span><span class="p">],</span><span class="n">dtype</span><span class="o">=</span><span class="s1">&#39;S3&#39;</span><span class="p">)</span>
2264 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">stringtochar</span><span class="p">(</span><span class="n">datain</span><span class="p">)</span> <span class="c1"># manual conversion to char array</span>
2265 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">v</span><span class="p">[:])</span> <span class="c1"># data returned as char array</span>
2266 <span class="p">[[</span><span class="sa">b</span><span class="s1">&#39;f&#39;</span> <span class="sa">b</span><span class="s1">&#39;o&#39;</span> <span class="sa">b</span><span class="s1">&#39;o&#39;</span><span class="p">]</span>
2267 <span class="p">[</span><span class="sa">b</span><span class="s1">&#39;b&#39;</span> <span class="sa">b</span><span class="s1">&#39;a&#39;</span> <span class="sa">b</span><span class="s1">&#39;r&#39;</span><span class="p">]]</span>
2268 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="o">.</span><span class="n">_Encoding</span> <span class="o">=</span> <span class="s1">&#39;ascii&#39;</span> <span class="c1"># this enables automatic conversion</span>
2269 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">datain</span> <span class="c1"># conversion to char array done internally</span>
2270 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">v</span><span class="p">[:])</span> <span class="c1"># data returned in numpy string array</span>
2271 <span class="p">[</span><span class="s1">&#39;foo&#39;</span> <span class="s1">&#39;bar&#39;</span><span class="p">]</span>
2272 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
2273 </code></pre></div>
2274
2275
2276 <p>Even if the <code>_Encoding</code> attribute is set, the automatic conversion of char
2277 arrays to/from string arrays can be disabled with
2278 <a href="#netCDF4.Variable.set_auto_chartostring"><code>set_auto_chartostring</code></a>.</p>
2279 <p>A similar situation is often encountered with numpy structured arrays with subdtypes
2280 containing fixed-wdith byte strings (dtype=<code>S#</code>). Since there is no native fixed-length string
2281 netCDF datatype, these numpy structure arrays are mapped onto netCDF compound
2282 types with character array elements. In this case the string &lt;-&gt; char array
2283 conversion is handled automatically (without the need to set the <code>_Encoding</code>
2284 attribute) using <a href="https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.view.html">numpy
2285 views</a>.
2286 The structured array dtype (including the string elements) can even be used to
2287 define the compound data type - the string dtype will be converted to
2288 character array dtype under the hood when creating the netcdf compound type.
2289 Here's an example:</p>
2290 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;compoundstring_example.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">)</span>
2291 <span class="o">&gt;&gt;&gt;</span> <span class="n">dtype</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">dtype</span><span class="p">([(</span><span class="s1">&#39;observation&#39;</span><span class="p">,</span> <span class="s1">&#39;f4&#39;</span><span class="p">),</span>
2292 <span class="o">...</span> <span class="p">(</span><span class="s1">&#39;station_name&#39;</span><span class="p">,</span><span class="s1">&#39;S10&#39;</span><span class="p">)])</span>
2293 <span class="o">&gt;&gt;&gt;</span> <span class="n">station_data_t</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createCompoundType</span><span class="p">(</span><span class="n">dtype</span><span class="p">,</span><span class="s1">&#39;station_data&#39;</span><span class="p">)</span>
2294 <span class="o">&gt;&gt;&gt;</span> <span class="n">_</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;station&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
2295 <span class="o">&gt;&gt;&gt;</span> <span class="n">statdat</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;station_obs&#39;</span><span class="p">,</span> <span class="n">station_data_t</span><span class="p">,</span> <span class="p">(</span><span class="s1">&#39;station&#39;</span><span class="p">,))</span>
2296 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="n">dtype</span><span class="p">)</span>
2297 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span><span class="p">[</span><span class="s1">&#39;observation&#39;</span><span class="p">][:]</span> <span class="o">=</span> <span class="p">(</span><span class="mf">123.</span><span class="p">,</span><span class="mf">3.14</span><span class="p">)</span>
2298 <span class="o">&gt;&gt;&gt;</span> <span class="n">data</span><span class="p">[</span><span class="s1">&#39;station_name&#39;</span><span class="p">][:]</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;Boulder&#39;</span><span class="p">,</span><span class="s1">&#39;New York&#39;</span><span class="p">)</span>
2299 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">statdat</span><span class="o">.</span><span class="n">dtype</span><span class="p">)</span> <span class="c1"># strings actually stored as character arrays</span>
2300 <span class="p">{</span><span class="s1">&#39;names&#39;</span><span class="p">:[</span><span class="s1">&#39;observation&#39;</span><span class="p">,</span><span class="s1">&#39;station_name&#39;</span><span class="p">],</span> <span class="s1">&#39;formats&#39;</span><span class="p">:[</span><span class="s1">&#39;&lt;f4&#39;</span><span class="p">,(</span><span class="s1">&#39;S1&#39;</span><span class="p">,</span> <span class="p">(</span><span class="mi">10</span><span class="p">,))],</span> <span class="s1">&#39;offsets&#39;</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">],</span> <span class="s1">&#39;itemsize&#39;</span><span class="p">:</span><span class="mi">16</span><span class="p">,</span> <span class="s1">&#39;aligned&#39;</span><span class="p">:</span><span class="kc">True</span><span class="p">}</span>
2301 <span class="o">&gt;&gt;&gt;</span> <span class="n">statdat</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span> <span class="c1"># strings converted to character arrays internally</span>
2302 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">statdat</span><span class="p">[:])</span> <span class="c1"># character arrays converted back to strings</span>
2303 <span class="p">[(</span><span class="mf">123.</span> <span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;Boulder&#39;</span><span class="p">)</span> <span class="p">(</span> <span class="mf">3.14</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;New York&#39;</span><span class="p">)]</span>
2304 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">statdat</span><span class="p">[:]</span><span class="o">.</span><span class="n">dtype</span><span class="p">)</span>
2305 <span class="p">{</span><span class="s1">&#39;names&#39;</span><span class="p">:[</span><span class="s1">&#39;observation&#39;</span><span class="p">,</span><span class="s1">&#39;station_name&#39;</span><span class="p">],</span> <span class="s1">&#39;formats&#39;</span><span class="p">:[</span><span class="s1">&#39;&lt;f4&#39;</span><span class="p">,</span><span class="s1">&#39;S10&#39;</span><span class="p">],</span> <span class="s1">&#39;offsets&#39;</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">],</span> <span class="s1">&#39;itemsize&#39;</span><span class="p">:</span><span class="mi">16</span><span class="p">,</span> <span class="s1">&#39;aligned&#39;</span><span class="p">:</span><span class="kc">True</span><span class="p">}</span>
2306 <span class="o">&gt;&gt;&gt;</span> <span class="n">statdat</span><span class="o">.</span><span class="n">set_auto_chartostring</span><span class="p">(</span><span class="kc">False</span><span class="p">)</span> <span class="c1"># turn off auto-conversion</span>
2307 <span class="o">&gt;&gt;&gt;</span> <span class="n">statdat</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">view</span><span class="p">(</span><span class="n">dtype</span><span class="o">=</span><span class="p">[(</span><span class="s1">&#39;observation&#39;</span><span class="p">,</span> <span class="s1">&#39;f4&#39;</span><span class="p">),(</span><span class="s1">&#39;station_name&#39;</span><span class="p">,</span><span class="s1">&#39;S1&#39;</span><span class="p">,</span><span class="mi">10</span><span class="p">)])</span>
2308 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">statdat</span><span class="p">[:])</span> <span class="c1"># now structured array with char array subtype is returned</span>
2309 <span class="p">[(</span><span class="mf">123.</span> <span class="p">,</span> <span class="p">[</span><span class="sa">b</span><span class="s1">&#39;B&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;o&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;u&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;l&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;d&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;e&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;r&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">])</span>
2310 <span class="p">(</span> <span class="mf">3.14</span><span class="p">,</span> <span class="p">[</span><span class="sa">b</span><span class="s1">&#39;N&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;e&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39; &#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;Y&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;o&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;r&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;k&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">])]</span>
2311 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
2312 </code></pre></div>
2313
2314
2315 <p>Note that there is currently no support for mapping numpy structured arrays with
2316 unicode elements (dtype <code>U#</code>) onto netCDF compound types, nor is there support
2317 for netCDF compound types with vlen string components.</p>
2318 <h2><div id='section15'>15) In-memory (diskless) Datasets.</h2>
2319 <p>You can create netCDF Datasets whose content is held in memory
2320 instead of in a disk file. There are two ways to do this. If you
2321 don't need access to the memory buffer containing the Dataset from
2322 within python, the best way is to use the <code>diskless=True</code> keyword
2323 argument when creating the Dataset. If you want to save the Dataset
2324 to disk when you close it, also set <code>persist=True</code>. If you want to
2325 create a new read-only Dataset from an existing python memory buffer, use the
2326 <code>memory</code> keyword argument to pass the memory buffer when creating the Dataset.
2327 If you want to create a new in-memory Dataset, and then access the memory buffer
2328 directly from Python, use the <code>memory</code> keyword argument to specify the
2329 estimated size of the Dataset in bytes when creating the Dataset with
2330 <code>mode='w'</code>. Then, the <code>Dataset.close</code> method will return a python memoryview
2331 object representing the Dataset. Below are examples illustrating both
2332 approaches.</p>
2333 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a diskless (in-memory) Dataset,</span>
2334 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># and persist the file to disk when it is closed.</span>
2335 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;diskless_example.nc&#39;</span><span class="p">,</span><span class="s1">&#39;w&#39;</span><span class="p">,</span><span class="n">diskless</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span><span class="n">persist</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
2336 <span class="o">&gt;&gt;&gt;</span> <span class="n">d</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;x&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
2337 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;v&#39;</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">int32</span><span class="p">,</span><span class="s1">&#39;x&#39;</span><span class="p">)</span>
2338 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
2339 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">)</span>
2340 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
2341 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
2342 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
2343 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">v</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
2344 <span class="n">groups</span><span class="p">:</span>
2345 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">[</span><span class="s1">&#39;v&#39;</span><span class="p">][:])</span>
2346 <span class="p">[</span><span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">]</span>
2347 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="c1"># file saved to disk</span>
2348 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create an in-memory dataset from an existing python</span>
2349 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># python memory buffer.</span>
2350 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># read the newly created netcdf file into a python</span>
2351 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># bytes object.</span>
2352 <span class="o">&gt;&gt;&gt;</span> <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;diskless_example.nc&#39;</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
2353 <span class="o">...</span> <span class="n">nc_bytes</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
2354 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a netCDF in-memory dataset from the bytes object.</span>
2355 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;inmemory.nc&#39;</span><span class="p">,</span> <span class="n">memory</span><span class="o">=</span><span class="n">nc_bytes</span><span class="p">)</span>
2356 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">)</span>
2357 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
2358 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
2359 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
2360 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">v</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
2361 <span class="n">groups</span><span class="p">:</span>
2362 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">[</span><span class="s1">&#39;v&#39;</span><span class="p">][:])</span>
2363 <span class="p">[</span><span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">]</span>
2364 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
2365 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create an in-memory Dataset and retrieve memory buffer</span>
2366 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># estimated size is 1028 bytes - this is actually only</span>
2367 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># used if format is NETCDF3</span>
2368 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># (ignored for NETCDF4/HDF5 files).</span>
2369 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;inmemory.nc&#39;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;w&#39;</span><span class="p">,</span><span class="n">memory</span><span class="o">=</span><span class="mi">1028</span><span class="p">)</span>
2370 <span class="o">&gt;&gt;&gt;</span> <span class="n">d</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s1">&#39;x&#39;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
2371 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s1">&#39;v&#39;</span><span class="p">,</span><span class="n">numpy</span><span class="o">.</span><span class="n">int32</span><span class="p">,</span><span class="s1">&#39;x&#39;</span><span class="p">)</span>
2372 <span class="o">&gt;&gt;&gt;</span> <span class="n">v</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
2373 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc_buf</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="c1"># close returns memoryview</span>
2374 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="nb">type</span><span class="p">(</span><span class="n">nc_buf</span><span class="p">))</span>
2375 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">memoryview</span><span class="s1">&#39;&gt;</span>
2376 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># save nc_buf to disk, read it back in and check.</span>
2377 <span class="o">&gt;&gt;&gt;</span> <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;inmemory.nc&#39;</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
2378 <span class="o">...</span> <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">nc_buf</span><span class="p">)</span>
2379 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;inmemory.nc&#39;</span><span class="p">)</span>
2380 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">)</span>
2381 <span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">netCDF4</span><span class="o">.</span><span class="n">_netCDF4</span><span class="o">.</span><span class="n">Dataset</span><span class="s1">&#39;&gt;</span>
2382 <span class="n">root</span> <span class="n">group</span> <span class="p">(</span><span class="n">NETCDF4</span> <span class="n">data</span> <span class="n">model</span><span class="p">,</span> <span class="n">file</span> <span class="nb">format</span> <span class="n">HDF5</span><span class="p">):</span>
2383 <span class="n">dimensions</span><span class="p">(</span><span class="n">sizes</span><span class="p">):</span> <span class="n">x</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
2384 <span class="n">variables</span><span class="p">(</span><span class="n">dimensions</span><span class="p">):</span> <span class="n">int32</span> <span class="n">v</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
2385 <span class="n">groups</span><span class="p">:</span>
2386 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">nc</span><span class="p">[</span><span class="s1">&#39;v&#39;</span><span class="p">][:])</span>
2387 <span class="p">[</span><span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">]</span>
2388 <span class="o">&gt;&gt;&gt;</span> <span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
2389 </code></pre></div>
2390
2391
2392 <p>All of the code in this tutorial is available in <code>examples/tutorial.py</code>, except
2393 the parallel IO example, which is in <code>examples/mpi_example.py</code>.
2394 Unit tests are in the <code>test</code> directory.</p>
2395 <p><strong>contact</strong>: Jeffrey Whitaker <a href="&#109;&#97;&#105;&#108;&#116;&#111;&#58;&#106;&#101;&#102;&#102;&#114;&#101;&#121;&#46;&#115;&#46;&#119;&#104;&#105;&#116;&#97;&#107;&#101;&#114;&#64;&#110;&#111;&#97;&#97;&#46;&#103;&#111;&#118;">&#106;&#101;&#102;&#102;&#114;&#101;&#121;&#46;&#115;&#46;&#119;&#104;&#105;&#116;&#97;&#107;&#101;&#114;&#64;&#110;&#111;&#97;&#97;&#46;&#103;&#111;&#118;</a></p>
2396 <p><strong>copyright</strong>: 2008 by Jeffrey Whitaker.</p>
2397 <p><strong>license</strong>: Permission to use, copy, modify, and distribute this software and
2398 its documentation for any purpose and without fee is hereby granted,
2399 provided that the above copyright notice appear in all copies and that
2400 both the copyright notice and this permission notice appear in
2401 supporting documentation.
2402 THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
2403 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
2404 EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
2405 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
2406 USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
2407 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
2408 PERFORMANCE OF THIS SOFTWARE.</p>
2409 <hr />
2410
2411
2412 </header>
2413
2414 <section id="section-items">
2415
2416 <h2 class="section-title" id="header-functions">Functions</h2>
2417
2418 <div class="item">
2419 <div class="name def" id="netCDF4.chartostring">
2420 <p>def <span class="ident">chartostring</span>(</p><p>b,encoding=&#39;utf-8&#39;)</p>
2421 </div>
2422
2423
2424
2425
2426 <div class="desc"><p>convert a character array to a string array with one less dimension.</p>
2427 <p><strong><code>b</code></strong>: Input character array (numpy datatype <code>'S1'</code> or <code>'U1'</code>).
2428 Will be converted to a array of strings, where each string has a fixed
2429 length of <code>b.shape[-1]</code> characters.</p>
2430 <p>optional kwarg <code>encoding</code> can be used to specify character encoding (default
2431 <code>utf-8</code>). If <code>encoding</code> is 'none' or 'bytes', a <code>numpy.string_</code> btye array is
2432 returned.</p>
2433 <p>returns a numpy string array with datatype <code>'UN'</code> (or <code>'SN'</code>) and shape
2434 <code>b.shape[:-1]</code> where where <code>N=b.shape[-1]</code>.</p></div>
2435 <div class="source_cont">
2436 </div>
2437
2438 </div>
2439
2440
2441 <div class="item">
2442 <div class="name def" id="netCDF4.date2index">
2443 <p>def <span class="ident">date2index</span>(</p><p>...)</p>
2444 </div>
2445
2446
2447
2448
2449 <div class="desc"><p>date2index(dates, nctime, calendar=None, select='exact')</p>
2450 <p>Return indices of a netCDF time variable corresponding to the given dates.</p>
2451 <p><strong>dates</strong>: A datetime object or a sequence of datetime objects.
2452 The datetime objects should not include a time-zone offset.</p>
2453 <p><strong>nctime</strong>: A netCDF time variable object. The nctime object must have a
2454 <strong>units</strong> attribute.</p>
2455 <p><strong>calendar</strong>: describes the calendar used in the time calculations.
2456 All the values currently defined in the
2457 <a href="http://cfconventions.org">CF metadata convention</a>
2458 Valid calendars <strong>'standard', 'gregorian', 'proleptic_gregorian'
2459 'noleap', '365_day', '360_day', 'julian', 'all_leap', '366_day'</strong>.
2460 Default is <strong>'standard'</strong>, which is a mixed Julian/Gregorian calendar.
2461 If <strong>calendar</strong> is None, its value is given by <strong>nctime.calendar</strong> or
2462 <strong>standard</strong> if no such attribute exists.</p>
2463 <p><strong>select</strong>: <strong>'exact', 'before', 'after', 'nearest'</strong>
2464 The index selection method. <strong>exact</strong> will return the indices perfectly
2465 matching the dates given. <strong>before</strong> and <strong>after</strong> will return the indices
2466 corresponding to the dates just before or just after the given dates if
2467 an exact match cannot be found. <strong>nearest</strong> will return the indices that
2468 correspond to the closest dates.</p>
2469 <p>returns an index (indices) of the netCDF time variable corresponding
2470 to the given datetime object(s).</p></div>
2471 <div class="source_cont">
2472 </div>
2473
2474 </div>
2475
2476
2477 <div class="item">
2478 <div class="name def" id="netCDF4.date2num">
2479 <p>def <span class="ident">date2num</span>(</p><p>...)</p>
2480 </div>
2481
2482
2483
2484
2485 <div class="desc"><p>date2num(dates, units, calendar=None)</p>
2486 <p>Return numeric time values given datetime objects. The units
2487 of the numeric time values are described by the <strong>units</strong> argument
2488 and the <strong>calendar</strong> keyword. The datetime objects must
2489 be in UTC with no time-zone offset. If there is a
2490 time-zone offset in <strong>units</strong>, it will be applied to the
2491 returned numeric values.</p>
2492 <p><strong>dates</strong>: A datetime object or a sequence of datetime objects.
2493 The datetime objects should not include a time-zone offset. They
2494 can be either native python datetime instances (which use
2495 the proleptic gregorian calendar) or cftime.datetime instances.</p>
2496 <p><strong>units</strong>: a string of the form <strong><time units> since <reference time></strong>
2497 describing the time units. <strong><time units></strong> can be days, hours, minutes,
2498 seconds, milliseconds or microseconds. <strong><reference time></strong> is the time
2499 origin. <strong>months_since</strong> is allowed <em>only</em> for the <strong>360_day</strong> calendar.</p>
2500 <p><strong>calendar</strong>: describes the calendar to be used in the time calculations.
2501 All the values currently defined in the
2502 <a href="http://cfconventions.org">CF metadata convention</a>
2503 Valid calendars <strong>'standard', 'gregorian', 'proleptic_gregorian'
2504 'noleap', '365_day', '360_day', 'julian', 'all_leap', '366_day'</strong>.
2505 Default is <code>None</code> which means the calendar associated with the rist
2506 input datetime instance will be used.</p>
2507 <p>returns a numeric time value, or an array of numeric time values
2508 with approximately 1 microsecond accuracy.</p></div>
2509 <div class="source_cont">
2510 </div>
2511
2512 </div>
2513
2514
2515 <div class="item">
2516 <div class="name def" id="netCDF4.get_chunk_cache">
2517 <p>def <span class="ident">get_chunk_cache</span>(</p><p>)</p>
2518 </div>
2519
2520
2521
2522
2523 <div class="desc"><p>return current netCDF chunk cache information in a tuple (size,nelems,preemption).
2524 See netcdf C library documentation for <code>nc_get_chunk_cache</code> for
2525 details. Values can be reset with <a href="#netCDF4.set_chunk_cache"><code>set_chunk_cache</code></a>.</p></div>
2526 <div class="source_cont">
2527 </div>
2528
2529 </div>
2530
2531
2532 <div class="item">
2533 <div class="name def" id="netCDF4.getlibversion">
2534 <p>def <span class="ident">getlibversion</span>(</p><p>)</p>
2535 </div>
2536
2537
2538
2539
2540 <div class="desc"><p>returns a string describing the version of the netcdf library
2541 used to build the module, and when it was built.</p></div>
2542 <div class="source_cont">
2543 </div>
2544
2545 </div>
2546
2547
2548 <div class="item">
2549 <div class="name def" id="netCDF4.num2date">
2550 <p>def <span class="ident">num2date</span>(</p><p>...)</p>
2551 </div>
2552
2553
2554
2555
2556 <div class="desc"><p>num2date(times, units, calendar='standard', only_use_cftime_datetimes=True, only_use_python_datetimes=False)</p>
2557 <p>Return datetime objects given numeric time values. The units
2558 of the numeric time values are described by the <strong>units</strong> argument
2559 and the <strong>calendar</strong> keyword. The returned datetime objects represent
2560 UTC with no time-zone offset, even if the specified
2561 <strong>units</strong> contain a time-zone offset.</p>
2562 <p><strong>times</strong>: numeric time values.</p>
2563 <p><strong>units</strong>: a string of the form <strong><time units> since <reference time></strong>
2564 describing the time units. <strong><time units></strong> can be days, hours, minutes,
2565 seconds, milliseconds or microseconds. <strong><reference time></strong> is the time
2566 origin. <strong>months_since</strong> is allowed <em>only</em> for the <strong>360_day</strong> calendar.</p>
2567 <p><strong>calendar</strong>: describes the calendar used in the time calculations.
2568 All the values currently defined in the
2569 <a href="http://cfconventions.org">CF metadata convention</a>
2570 Valid calendars <strong>'standard', 'gregorian', 'proleptic_gregorian'
2571 'noleap', '365_day', '360_day', 'julian', 'all_leap', '366_day'</strong>.
2572 Default is <strong>'standard'</strong>, which is a mixed Julian/Gregorian calendar.</p>
2573 <p><strong>only_use_cftime_datetimes</strong>: if False, python datetime.datetime
2574 objects are returned from num2date where possible; if True dates which
2575 subclass cftime.datetime are returned for all calendars. Default <strong>True</strong>.</p>
2576 <p><strong>only_use_python_datetimes</strong>: always return python datetime.datetime
2577 objects and raise an error if this is not possible. Ignored unless
2578 <strong>only_use_cftime_datetimes=False</strong>. Default <strong>False</strong>.</p>
2579 <p>returns a datetime instance, or an array of datetime instances with
2580 microsecond accuracy, if possible.</p>
2581 <p><strong><em>Note</em></strong>: If only_use_cftime_datetimes=False and
2582 use_only_python_datetimes=False, the datetime instances
2583 returned are 'real' python datetime
2584 objects if <strong>calendar='proleptic_gregorian'</strong>, or
2585 <strong>calendar='standard'</strong> or <strong>'gregorian'</strong>
2586 and the date is after the breakpoint between the Julian and
2587 Gregorian calendars (1582-10-15). Otherwise, they are ctime.datetime
2588 objects which support some but not all the methods of native python
2589 datetime objects. The datetime instances
2590 do not contain a time-zone offset, even if the specified <strong>units</strong>
2591 contains one.</p></div>
2592 <div class="source_cont">
2593 </div>
2594
2595 </div>
2596
2597
2598 <div class="item">
2599 <div class="name def" id="netCDF4.set_chunk_cache">
2600 <p>def <span class="ident">set_chunk_cache</span>(</p><p>self,size=None,nelems=None,preemption=None)</p>
2601 </div>
2602
2603
2604
2605
2606 <div class="desc"><p>change netCDF4 chunk cache settings.
2607 See netcdf C library documentation for <code>nc_set_chunk_cache</code> for
2608 details.</p></div>
2609 <div class="source_cont">
2610 </div>
2611
2612 </div>
2613
2614
2615 <div class="item">
2616 <div class="name def" id="netCDF4.stringtoarr">
2617 <p>def <span class="ident">stringtoarr</span>(</p><p>a, NUMCHARS,dtype=&#39;S&#39;)</p>
2618 </div>
2619
2620
2621
2622
2623 <div class="desc"><p>convert a string to a character array of length <code>NUMCHARS</code></p>
2624 <p><strong><code>a</code></strong>: Input python string.</p>
2625 <p><strong><code>NUMCHARS</code></strong>: number of characters used to represent string
2626 (if len(a) &lt; <code>NUMCHARS</code>, it will be padded on the right with blanks).</p>
2627 <p><strong><code>dtype</code></strong>: type of numpy array to return. Default is <code>'S'</code>, which
2628 means an array of dtype <code>'S1'</code> will be returned. If dtype=<code>'U'</code>, a
2629 unicode array (dtype = <code>'U1'</code>) will be returned.</p>
2630 <p>returns a rank 1 numpy character array of length NUMCHARS with datatype <code>'S1'</code>
2631 (default) or <code>'U1'</code> (if dtype=<code>'U'</code>)</p></div>
2632 <div class="source_cont">
2633 </div>
2634
2635 </div>
2636
2637
2638 <div class="item">
2639 <div class="name def" id="netCDF4.stringtochar">
2640 <p>def <span class="ident">stringtochar</span>(</p><p>a,encoding=&#39;utf-8&#39;)</p>
2641 </div>
2642
2643
2644
2645
2646 <div class="desc"><p>convert a string array to a character array with one extra dimension</p>
2647 <p><strong><code>a</code></strong>: Input numpy string array with numpy datatype <code>'SN'</code> or <code>'UN'</code>, where N
2648 is the number of characters in each string. Will be converted to
2649 an array of characters (datatype <code>'S1'</code> or <code>'U1'</code>) of shape <code>a.shape + (N,)</code>.</p>
2650 <p>optional kwarg <code>encoding</code> can be used to specify character encoding (default
2651 <code>utf-8</code>). If <code>encoding</code> is 'none' or 'bytes', a <code>numpy.string_</code> the input array
2652 is treated a raw byte strings (<code>numpy.string_</code>).</p>
2653 <p>returns a numpy character array with datatype <code>'S1'</code> or <code>'U1'</code>
2654 and shape <code>a.shape + (N,)</code>, where N is the length of each string in a.</p></div>
2655 <div class="source_cont">
2656 </div>
2657
2658 </div>
2659
2660
2661 <h2 class="section-title" id="header-classes">Classes</h2>
2662
2663 <div class="item">
2664 <p id="netCDF4.CompoundType" class="name">class <span class="ident">CompoundType</span></p>
2665
2666
2667 <div class="desc"><p>A <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> instance is used to describe a compound data
2668 type, and can be passed to the the <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> method of
2669 a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance.
2670 Compound data types map to numpy structured arrays.
2671 See <a href="#netCDF4.CompoundType.__init__"><code>__init__</code></a> for more details.</p>
2672 <p>The instance variables <code>dtype</code> and <code>name</code> should not be modified by
2673 the user.</p></div>
2674 <div class="source_cont">
2675 </div>
2676
2677
2678 <div class="class">
2679 <h3>Ancestors (in MRO)</h3>
2680 <ul class="class_list">
2681 <li><a href="#netCDF4.CompoundType">CompoundType</a></li>
2682 <li>builtins.object</li>
2683 </ul>
2684 <h3>Class variables</h3>
2685 <div class="item">
2686 <p id="netCDF4.CompoundType.dtype" class="name">var <span class="ident">dtype</span></p>
2687
2688
2689
2690
2691 <div class="desc"><p>A numpy dtype object describing the compound data type.</p></div>
2692 <div class="source_cont">
2693 </div>
2694
2695 </div>
2696 <div class="item">
2697 <p id="netCDF4.CompoundType.dtype_view" class="name">var <span class="ident">dtype_view</span></p>
2698
2699
2700
2701
2702 <div class="source_cont">
2703 </div>
2704
2705 </div>
2706 <div class="item">
2707 <p id="netCDF4.CompoundType.name" class="name">var <span class="ident">name</span></p>
2708
2709
2710
2711
2712 <div class="desc"><p>String name.</p></div>
2713 <div class="source_cont">
2714 </div>
2715
2716 </div>
2717 <h3>Static methods</h3>
2718
2719 <div class="item">
2720 <div class="name def" id="netCDF4.CompoundType.__init__">
2721 <p>def <span class="ident">__init__</span>(</p><p>group, datatype, datatype_name)</p>
2722 </div>
2723
2724
2725
2726
2727 <div class="desc"><p>CompoundType constructor.</p>
2728 <p><strong><code>group</code></strong>: <a href="#netCDF4.Group"><code>Group</code></a> instance to associate with the compound datatype.</p>
2729 <p><strong><code>datatype</code></strong>: A numpy dtype object describing a structured (a.k.a record)
2730 array. Can be composed of homogeneous numeric or character data types, or
2731 other structured array data types.</p>
2732 <p><strong><code>datatype_name</code></strong>: a Python string containing a description of the
2733 compound data type.</p>
2734 <p><strong><em>Note 1</em></strong>: When creating nested compound data types,
2735 the inner compound data types must already be associated with CompoundType
2736 instances (so create CompoundType instances for the innermost structures
2737 first).</p>
2738 <p><strong><em>Note 2</em></strong>: <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> instances should be created using the
2739 <a href="#netCDF4.Dataset.createCompoundType"><code>createCompoundType</code></a>
2740 method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance, not using this class directly.</p></div>
2741 <div class="source_cont">
2742 </div>
2743
2744 </div>
2745
2746 </div>
2747 </div>
2748
2749 <div class="item">
2750 <p id="netCDF4.Dataset" class="name">class <span class="ident">Dataset</span></p>
2751
2752
2753 <div class="desc"><p>A netCDF <a href="#netCDF4.Dataset"><code>Dataset</code></a> is a collection of dimensions, groups, variables and
2754 attributes. Together they describe the meaning of data and relations among
2755 data fields stored in a netCDF file. See <a href="#netCDF4.Dataset.__init__"><code>__init__</code></a> for more
2756 details.</p>
2757 <p>A list of attribute names corresponding to global netCDF attributes
2758 defined for the <a href="#netCDF4.Dataset"><code>Dataset</code></a> can be obtained with the
2759 <a href="#netCDF4.Dataset.ncattrs"><code>ncattrs</code></a> method.
2760 These attributes can be created by assigning to an attribute of the
2761 <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance. A dictionary containing all the netCDF attribute
2762 name/value pairs is provided by the <code>__dict__</code> attribute of a
2763 <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance.</p>
2764 <p>The following class variables are read-only and should not be
2765 modified by the user.</p>
2766 <p><strong><code>dimensions</code></strong>: The <code>dimensions</code> dictionary maps the names of
2767 dimensions defined for the <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> to instances of the
2768 <a href="#netCDF4.Dimension"><code>Dimension</code></a> class.</p>
2769 <p><strong><code>variables</code></strong>: The <code>variables</code> dictionary maps the names of variables
2770 defined for this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> to instances of the
2771 <a href="#netCDF4.Variable"><code>Variable</code></a> class.</p>
2772 <p><strong><code>groups</code></strong>: The groups dictionary maps the names of groups created for
2773 this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> to instances of the <a href="#netCDF4.Group"><code>Group</code></a> class (the
2774 <a href="#netCDF4.Dataset"><code>Dataset</code></a> class is simply a special case of the <a href="#netCDF4.Group"><code>Group</code></a> class which
2775 describes the root group in the netCDF4 file).</p>
2776 <p><strong><code>cmptypes</code></strong>: The <code>cmptypes</code> dictionary maps the names of
2777 compound types defined for the <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> to instances of the
2778 <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> class.</p>
2779 <p><strong><code>vltypes</code></strong>: The <code>vltypes</code> dictionary maps the names of
2780 variable-length types defined for the <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> to instances
2781 of the <a href="#netCDF4.VLType"><code>VLType</code></a> class.</p>
2782 <p><strong><code>enumtypes</code></strong>: The <code>enumtypes</code> dictionary maps the names of
2783 Enum types defined for the <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> to instances
2784 of the <a href="#netCDF4.EnumType"><code>EnumType</code></a> class.</p>
2785 <p><strong><code>data_model</code></strong>: <code>data_model</code> describes the netCDF
2786 data model version, one of <code>NETCDF3_CLASSIC</code>, <code>NETCDF4</code>,
2787 <code>NETCDF4_CLASSIC</code>, <code>NETCDF3_64BIT_OFFSET</code> or <code>NETCDF3_64BIT_DATA</code>.</p>
2788 <p><strong><code>file_format</code></strong>: same as <code>data_model</code>, retained for backwards compatibility.</p>
2789 <p><strong><code>disk_format</code></strong>: <code>disk_format</code> describes the underlying
2790 file format, one of <code>NETCDF3</code>, <code>HDF5</code>, <code>HDF4</code>,
2791 <code>PNETCDF</code>, <code>DAP2</code>, <code>DAP4</code> or <code>UNDEFINED</code>. Only available if using
2792 netcdf C library version &gt;= 4.3.1, otherwise will always return
2793 <code>UNDEFINED</code>.</p>
2794 <p><strong><code>parent</code></strong>: <code>parent</code> is a reference to the parent
2795 <a href="#netCDF4.Group"><code>Group</code></a> instance. <code>None</code> for the root group or <a href="#netCDF4.Dataset"><code>Dataset</code></a>
2796 instance.</p>
2797 <p><strong><code>path</code></strong>: <code>path</code> shows the location of the <a href="#netCDF4.Group"><code>Group</code></a> in
2798 the <a href="#netCDF4.Dataset"><code>Dataset</code></a> in a unix directory format (the names of groups in the
2799 hierarchy separated by backslashes). A <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance is the root
2800 group, so the path is simply <code>'/'</code>.</p>
2801 <p><strong><code>keepweakref</code></strong>: If <code>True</code>, child Dimension and Variables objects only keep weak
2802 references to the parent Dataset or Group.</p>
2803 <p><strong><code>_ncstring_attrs__</code></strong>: If <code>True</code>, all text attributes will be written as variable-length
2804 strings.</p></div>
2805 <div class="source_cont">
2806 </div>
2807
2808
2809 <div class="class">
2810 <h3>Ancestors (in MRO)</h3>
2811 <ul class="class_list">
2812 <li><a href="#netCDF4.Dataset">Dataset</a></li>
2813 <li>builtins.object</li>
2814 </ul>
2815 <h3>Class variables</h3>
2816 <div class="item">
2817 <p id="netCDF4.Dataset.cmptypes" class="name">var <span class="ident">cmptypes</span></p>
2818
2819
2820
2821
2822 <div class="desc"><p>The <code>cmptypes</code> dictionary maps the names of
2823 compound types defined for the <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> to instances of the
2824 <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> class.</p></div>
2825 <div class="source_cont">
2826 </div>
2827
2828 </div>
2829 <div class="item">
2830 <p id="netCDF4.Dataset.data_model" class="name">var <span class="ident">data_model</span></p>
2831
2832
2833
2834
2835 <div class="desc"><p><code>data_model</code> describes the netCDF
2836 data model version, one of <code>NETCDF3_CLASSIC</code>, <code>NETCDF4</code>,
2837 <code>NETCDF4_CLASSIC</code>, <code>NETCDF3_64BIT_OFFSET</code> or <code>NETCDF3_64BIT_DATA</code>.</p></div>
2838 <div class="source_cont">
2839 </div>
2840
2841 </div>
2842 <div class="item">
2843 <p id="netCDF4.Dataset.dimensions" class="name">var <span class="ident">dimensions</span></p>
2844
2845
2846
2847
2848 <div class="desc"><p>The <code>dimensions</code> dictionary maps the names of
2849 dimensions defined for the <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> to instances of the
2850 <a href="#netCDF4.Dimension"><code>Dimension</code></a> class.</p></div>
2851 <div class="source_cont">
2852 </div>
2853
2854 </div>
2855 <div class="item">
2856 <p id="netCDF4.Dataset.disk_format" class="name">var <span class="ident">disk_format</span></p>
2857
2858
2859
2860
2861 <div class="desc"><p><code>disk_format</code> describes the underlying
2862 file format, one of <code>NETCDF3</code>, <code>HDF5</code>, <code>HDF4</code>,
2863 <code>PNETCDF</code>, <code>DAP2</code>, <code>DAP4</code> or <code>UNDEFINED</code>. Only available if using
2864 netcdf C library version &gt;= 4.3.1, otherwise will always return
2865 <code>UNDEFINED</code>.</p></div>
2866 <div class="source_cont">
2867 </div>
2868
2869 </div>
2870 <div class="item">
2871 <p id="netCDF4.Dataset.enumtypes" class="name">var <span class="ident">enumtypes</span></p>
2872
2873
2874
2875
2876 <div class="desc"><p>The <code>enumtypes</code> dictionary maps the names of
2877 Enum types defined for the <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> to instances of the
2878 <a href="#netCDF4.EnumType"><code>EnumType</code></a> class.</p></div>
2879 <div class="source_cont">
2880 </div>
2881
2882 </div>
2883 <div class="item">
2884 <p id="netCDF4.Dataset.file_format" class="name">var <span class="ident">file_format</span></p>
2885
2886
2887
2888
2889 <div class="desc"><p>same as <code>data_model</code>, retained for backwards compatibility.</p></div>
2890 <div class="source_cont">
2891 </div>
2892
2893 </div>
2894 <div class="item">
2895 <p id="netCDF4.Dataset.groups" class="name">var <span class="ident">groups</span></p>
2896
2897
2898
2899
2900 <div class="desc"><p>The groups dictionary maps the names of groups created for
2901 this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> to instances of the <a href="#netCDF4.Group"><code>Group</code></a> class (the
2902 <a href="#netCDF4.Dataset"><code>Dataset</code></a> class is simply a special case of the <a href="#netCDF4.Group"><code>Group</code></a> class which
2903 describes the root group in the netCDF4 file).</p></div>
2904 <div class="source_cont">
2905 </div>
2906
2907 </div>
2908 <div class="item">
2909 <p id="netCDF4.Dataset.keepweakref" class="name">var <span class="ident">keepweakref</span></p>
2910
2911
2912
2913
2914 <div class="desc"><p>If <code>True</code>, child Dimension and Variables objects only keep weak references to
2915 the parent Dataset or Group.</p></div>
2916 <div class="source_cont">
2917 </div>
2918
2919 </div>
2920 <div class="item">
2921 <p id="netCDF4.Dataset.name" class="name">var <span class="ident">name</span></p>
2922
2923
2924
2925
2926 <div class="source_cont">
2927 </div>
2928
2929 </div>
2930 <div class="item">
2931 <p id="netCDF4.Dataset.parent" class="name">var <span class="ident">parent</span></p>
2932
2933
2934
2935
2936 <div class="desc"><p><code>parent</code> is a reference to the parent
2937 <a href="#netCDF4.Group"><code>Group</code></a> instance. <code>None</code> for the root group or <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance</p></div>
2938 <div class="source_cont">
2939 </div>
2940
2941 </div>
2942 <div class="item">
2943 <p id="netCDF4.Dataset.path" class="name">var <span class="ident">path</span></p>
2944
2945
2946
2947
2948 <div class="desc"><p><code>path</code> shows the location of the <a href="#netCDF4.Group"><code>Group</code></a> in
2949 the <a href="#netCDF4.Dataset"><code>Dataset</code></a> in a unix directory format (the names of groups in the
2950 hierarchy separated by backslashes). A <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance is the root
2951 group, so the path is simply <code>'/'</code>.</p></div>
2952 <div class="source_cont">
2953 </div>
2954
2955 </div>
2956 <div class="item">
2957 <p id="netCDF4.Dataset.variables" class="name">var <span class="ident">variables</span></p>
2958
2959
2960
2961
2962 <div class="desc"><p>The <code>variables</code> dictionary maps the names of variables
2963 defined for this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> to instances of the <a href="#netCDF4.Variable"><code>Variable</code></a>
2964 class.</p></div>
2965 <div class="source_cont">
2966 </div>
2967
2968 </div>
2969 <div class="item">
2970 <p id="netCDF4.Dataset.vltypes" class="name">var <span class="ident">vltypes</span></p>
2971
2972
2973
2974
2975 <div class="desc"><p>The <code>vltypes</code> dictionary maps the names of
2976 variable-length types defined for the <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> to instances of the
2977 <a href="#netCDF4.VLType"><code>VLType</code></a> class.</p></div>
2978 <div class="source_cont">
2979 </div>
2980
2981 </div>
2982 <h3>Static methods</h3>
2983
2984 <div class="item">
2985 <div class="name def" id="netCDF4.Dataset.__init__">
2986 <p>def <span class="ident">__init__</span>(</p><p>self, filename, mode=&#34;r&#34;, clobber=True, diskless=False, persist=False, keepweakref=False, memory=None, encoding=None, parallel=False, comm=None, info=None, format=&#39;NETCDF4&#39;)</p>
2987 </div>
2988
2989
2990
2991
2992 <div class="desc"><p><a href="#netCDF4.Dataset"><code>Dataset</code></a> constructor.</p>
2993 <p><strong><code>filename</code></strong>: Name of netCDF file to hold dataset. Can also
2994 be a python 3 pathlib instance or the URL of an OpenDAP dataset. When memory is
2995 set this is just used to set the <code>filepath()</code>.</p>
2996 <p><strong><code>mode</code></strong>: access mode. <code>r</code> means read-only; no data can be
2997 modified. <code>w</code> means write; a new file is created, an existing file with
2998 the same name is deleted. <code>a</code> and <code>r+</code> mean append (in analogy with
2999 serial files); an existing file is opened for reading and writing.
3000 Appending <code>s</code> to modes <code>r</code>, <code>w</code>, <code>r+</code> or <code>a</code> will enable unbuffered shared
3001 access to <code>NETCDF3_CLASSIC</code>, <code>NETCDF3_64BIT_OFFSET</code> or
3002 <code>NETCDF3_64BIT_DATA</code> formatted files.
3003 Unbuffered access may be useful even if you don't need shared
3004 access, since it may be faster for programs that don't access data
3005 sequentially. This option is ignored for <code>NETCDF4</code> and <code>NETCDF4_CLASSIC</code>
3006 formatted files.</p>
3007 <p><strong><code>clobber</code></strong>: if <code>True</code> (default), opening a file with <code>mode='w'</code>
3008 will clobber an existing file with the same name. if <code>False</code>, an
3009 exception will be raised if a file with the same name already exists.</p>
3010 <p><strong><code>format</code></strong>: underlying file format (one of <code>'NETCDF4',
3011 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC'</code>, <code>'NETCDF3_64BIT_OFFSET'</code> or
3012 <code>'NETCDF3_64BIT_DATA'</code>.
3013 Only relevant if <code>mode = 'w'</code> (if <code>mode = 'r','a'</code> or <code>'r+'</code> the file format
3014 is automatically detected). Default <code>'NETCDF4'</code>, which means the data is
3015 stored in an HDF5 file, using netCDF 4 API features. Setting
3016 <code>format='NETCDF4_CLASSIC'</code> will create an HDF5 file, using only netCDF 3
3017 compatible API features. netCDF 3 clients must be recompiled and linked
3018 against the netCDF 4 library to read files in <code>NETCDF4_CLASSIC</code> format.
3019 <code>'NETCDF3_CLASSIC'</code> is the classic netCDF 3 file format that does not
3020 handle 2+ Gb files. <code>'NETCDF3_64BIT_OFFSET'</code> is the 64-bit offset
3021 version of the netCDF 3 file format, which fully supports 2+ GB files, but
3022 is only compatible with clients linked against netCDF version 3.6.0 or
3023 later. <code>'NETCDF3_64BIT_DATA'</code> is the 64-bit data version of the netCDF 3
3024 file format, which supports 64-bit dimension sizes plus unsigned and
3025 64 bit integer data types, but is only compatible with clients linked against
3026 netCDF version 4.4.0 or later.</p>
3027 <p><strong><code>diskless</code></strong>: If <code>True</code>, create diskless (in-core) file.
3028 This is a feature added to the C library after the
3029 netcdf-4.2 release. If you need to access the memory buffer directly,
3030 use the in-memory feature instead (see <code>memory</code> kwarg).</p>
3031 <p><strong><code>persist</code></strong>: if <code>diskless=True</code>, persist file to disk when closed
3032 (default <code>False</code>).</p>
3033 <p><strong><code>keepweakref</code></strong>: if <code>True</code>, child Dimension and Variable instances will keep weak
3034 references to the parent Dataset or Group object. Default is <code>False</code>, which
3035 means strong references will be kept. Having Dimension and Variable instances
3036 keep a strong reference to the parent Dataset instance, which in turn keeps a
3037 reference to child Dimension and Variable instances, creates circular references.
3038 Circular references complicate garbage collection, which may mean increased
3039 memory usage for programs that create may Dataset instances with lots of
3040 Variables. It also will result in the Dataset object never being deleted, which
3041 means it may keep open files alive as well. Setting <code>keepweakref=True</code> allows
3042 Dataset instances to be garbage collected as soon as they go out of scope, potentially
3043 reducing memory usage and open file handles. However, in many cases this is not
3044 desirable, since the associated Variable instances may still be needed, but are
3045 rendered unusable when the parent Dataset instance is garbage collected.</p>
3046 <p><strong><code>memory</code></strong>: if not <code>None</code>, create or open an in-memory Dataset.
3047 If mode = 'r', the memory kwarg must contain a memory buffer object
3048 (an object that supports the python buffer interface).
3049 The Dataset will then be created with contents taken from this block of memory.
3050 If mode = 'w', the memory kwarg should contain the anticipated size
3051 of the Dataset in bytes (used only for NETCDF3 files). A memory
3052 buffer containing a copy of the Dataset is returned by the
3053 <code>Dataset.close</code> method. Requires netcdf-c version 4.4.1 for mode='r,
3054 netcdf-c 4.6.2 for mode='w'. To persist the file to disk, the raw
3055 bytes from the returned buffer can be written into a binary file.
3056 The Dataset can also be re-opened using this memory buffer.</p>
3057 <p><strong><code>encoding</code></strong>: encoding used to encode filename string into bytes.
3058 Default is None (<code>sys.getdefaultfileencoding()</code> is used).</p>
3059 <p><strong><code>parallel</code></strong>: open for parallel access using MPI (requires mpi4py and
3060 parallel-enabled netcdf-c and hdf5 libraries). Default is <code>False</code>. If
3061 <code>True</code>, <code>comm</code> and <code>info</code> kwargs may also be specified.</p>
3062 <p><strong><code>comm</code></strong>: MPI_Comm object for parallel access. Default <code>None</code>, which
3063 means MPI_COMM_WORLD will be used. Ignored if <code>parallel=False</code>.</p>
3064 <p><strong><code>info</code></strong>: MPI_Info object for parallel access. Default <code>None</code>, which
3065 means MPI_INFO_NULL will be used. Ignored if <code>parallel=False</code>.</p></div>
3066 <div class="source_cont">
3067 </div>
3068
3069 </div>
3070
3071
3072 <div class="item">
3073 <div class="name def" id="netCDF4.Dataset.close">
3074 <p>def <span class="ident">close</span>(</p><p>self)</p>
3075 </div>
3076
3077
3078
3079
3080 <div class="desc"><p>Close the Dataset.</p></div>
3081 <div class="source_cont">
3082 </div>
3083
3084 </div>
3085
3086
3087 <div class="item">
3088 <div class="name def" id="netCDF4.Dataset.createCompoundType">
3089 <p>def <span class="ident">createCompoundType</span>(</p><p>self, datatype, datatype_name)</p>
3090 </div>
3091
3092
3093
3094
3095 <div class="desc"><p>Creates a new compound data type named <code>datatype_name</code> from the numpy
3096 dtype object <code>datatype</code>.</p>
3097 <p><strong><em>Note</em></strong>: If the new compound data type contains other compound data types
3098 (i.e. it is a 'nested' compound type, where not all of the elements
3099 are homogeneous numeric data types), then the 'inner' compound types <strong>must</strong> be
3100 created first.</p>
3101 <p>The return value is the <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> class instance describing the new
3102 datatype.</p></div>
3103 <div class="source_cont">
3104 </div>
3105
3106 </div>
3107
3108
3109 <div class="item">
3110 <div class="name def" id="netCDF4.Dataset.createDimension">
3111 <p>def <span class="ident">createDimension</span>(</p><p>self, dimname, size=None)</p>
3112 </div>
3113
3114
3115
3116
3117 <div class="desc"><p>Creates a new dimension with the given <code>dimname</code> and <code>size</code>.</p>
3118 <p><code>size</code> must be a positive integer or <code>None</code>, which stands for
3119 "unlimited" (default is <code>None</code>). Specifying a size of 0 also
3120 results in an unlimited dimension. The return value is the <a href="#netCDF4.Dimension"><code>Dimension</code></a>
3121 class instance describing the new dimension. To determine the current
3122 maximum size of the dimension, use the <code>len</code> function on the <a href="#netCDF4.Dimension"><code>Dimension</code></a>
3123 instance. To determine if a dimension is 'unlimited', use the
3124 <a href="#netCDF4.Dimension.isunlimited"><code>isunlimited</code></a> method of the <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance.</p></div>
3125 <div class="source_cont">
3126 </div>
3127
3128 </div>
3129
3130
3131 <div class="item">
3132 <div class="name def" id="netCDF4.Dataset.createEnumType">
3133 <p>def <span class="ident">createEnumType</span>(</p><p>self, datatype, datatype_name, enum_dict)</p>
3134 </div>
3135
3136
3137
3138
3139 <div class="desc"><p>Creates a new Enum data type named <code>datatype_name</code> from a numpy
3140 integer dtype object <code>datatype</code>, and a python dictionary
3141 defining the enum fields and values.</p>
3142 <p>The return value is the <a href="#netCDF4.EnumType"><code>EnumType</code></a> class instance describing the new
3143 datatype.</p></div>
3144 <div class="source_cont">
3145 </div>
3146
3147 </div>
3148
3149
3150 <div class="item">
3151 <div class="name def" id="netCDF4.Dataset.createGroup">
3152 <p>def <span class="ident">createGroup</span>(</p><p>self, groupname)</p>
3153 </div>
3154
3155
3156
3157
3158 <div class="desc"><p>Creates a new <a href="#netCDF4.Group"><code>Group</code></a> with the given <code>groupname</code>.</p>
3159 <p>If <code>groupname</code> is specified as a path, using forward slashes as in unix to
3160 separate components, then intermediate groups will be created as necessary
3161 (analogous to <code>mkdir -p</code> in unix). For example,
3162 <code>createGroup('/GroupA/GroupB/GroupC')</code> will create <code>GroupA</code>,
3163 <code>GroupA/GroupB</code>, and <code>GroupA/GroupB/GroupC</code>, if they don't already exist.
3164 If the specified path describes a group that already exists, no error is
3165 raised.</p>
3166 <p>The return value is a <a href="#netCDF4.Group"><code>Group</code></a> class instance.</p></div>
3167 <div class="source_cont">
3168 </div>
3169
3170 </div>
3171
3172
3173 <div class="item">
3174 <div class="name def" id="netCDF4.Dataset.createVLType">
3175 <p>def <span class="ident">createVLType</span>(</p><p>self, datatype, datatype_name)</p>
3176 </div>
3177
3178
3179
3180
3181 <div class="desc"><p>Creates a new VLEN data type named <code>datatype_name</code> from a numpy
3182 dtype object <code>datatype</code>.</p>
3183 <p>The return value is the <a href="#netCDF4.VLType"><code>VLType</code></a> class instance describing the new
3184 datatype.</p></div>
3185 <div class="source_cont">
3186 </div>
3187
3188 </div>
3189
3190
3191 <div class="item">
3192 <div class="name def" id="netCDF4.Dataset.createVariable">
3193 <p>def <span class="ident">createVariable</span>(</p><p>self, varname, datatype, dimensions=(), zlib=False, complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None, endian=&#39;native&#39;, least_significant_digit=None, fill_value=None, chunk_cache=None)</p>
3194 </div>
3195
3196
3197
3198
3199 <div class="desc"><p>Creates a new variable with the given <code>varname</code>, <code>datatype</code>, and
3200 <code>dimensions</code>. If dimensions are not given, the variable is assumed to be
3201 a scalar.</p>
3202 <p>If <code>varname</code> is specified as a path, using forward slashes as in unix to
3203 separate components, then intermediate groups will be created as necessary
3204 For example, <code>createVariable('/GroupA/GroupB/VarC', float, ('x','y'))</code> will create groups <code>GroupA</code>
3205 and <code>GroupA/GroupB</code>, plus the variable <code>GroupA/GroupB/VarC</code>, if the preceding
3206 groups don't already exist.</p>
3207 <p>The <code>datatype</code> can be a numpy datatype object, or a string that describes
3208 a numpy dtype object (like the <code>dtype.str</code> attribute of a numpy array).
3209 Supported specifiers include: <code>'S1' or 'c' (NC_CHAR), 'i1' or 'b' or 'B'
3210 (NC_BYTE), 'u1' (NC_UBYTE), 'i2' or 'h' or 's' (NC_SHORT), 'u2'
3211 (NC_USHORT), 'i4' or 'i' or 'l' (NC_INT), 'u4' (NC_UINT), 'i8' (NC_INT64),
3212 'u8' (NC_UINT64), 'f4' or 'f' (NC_FLOAT), 'f8' or 'd' (NC_DOUBLE)</code>.
3213 <code>datatype</code> can also be a <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> instance
3214 (for a structured, or compound array), a <a href="#netCDF4.VLType"><code>VLType</code></a> instance
3215 (for a variable-length array), or the python <code>str</code> builtin
3216 (for a variable-length string array). Numpy string and unicode datatypes with
3217 length greater than one are aliases for <code>str</code>.</p>
3218 <p>Data from netCDF variables is presented to python as numpy arrays with
3219 the corresponding data type.</p>
3220 <p><code>dimensions</code> must be a tuple containing dimension names (strings) that
3221 have been defined previously using <a href="#netCDF4.Dataset.createDimension"><code>createDimension</code></a>. The default value
3222 is an empty tuple, which means the variable is a scalar.</p>
3223 <p>If the optional keyword <code>zlib</code> is <code>True</code>, the data will be compressed in
3224 the netCDF file using gzip compression (default <code>False</code>).</p>
3225 <p>The optional keyword <code>complevel</code> is an integer between 1 and 9 describing
3226 the level of compression desired (default 4). Ignored if <code>zlib=False</code>.</p>
3227 <p>If the optional keyword <code>shuffle</code> is <code>True</code>, the HDF5 shuffle filter
3228 will be applied before compressing the data (default <code>True</code>). This
3229 significantly improves compression. Default is <code>True</code>. Ignored if
3230 <code>zlib=False</code>.</p>
3231 <p>If the optional keyword <code>fletcher32</code> is <code>True</code>, the Fletcher32 HDF5
3232 checksum algorithm is activated to detect errors. Default <code>False</code>.</p>
3233 <p>If the optional keyword <code>contiguous</code> is <code>True</code>, the variable data is
3234 stored contiguously on disk. Default <code>False</code>. Setting to <code>True</code> for
3235 a variable with an unlimited dimension will trigger an error.</p>
3236 <p>The optional keyword <code>chunksizes</code> can be used to manually specify the
3237 HDF5 chunksizes for each dimension of the variable. A detailed
3238 discussion of HDF chunking and I/O performance is available
3239 <a href="http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html">here</a>.
3240 Basically, you want the chunk size for each dimension to match as
3241 closely as possible the size of the data block that users will read
3242 from the file. <code>chunksizes</code> cannot be set if <code>contiguous=True</code>.</p>
3243 <p>The optional keyword <code>endian</code> can be used to control whether the
3244 data is stored in little or big endian format on disk. Possible
3245 values are <code>little, big</code> or <code>native</code> (default). The library
3246 will automatically handle endian conversions when the data is read,
3247 but if the data is always going to be read on a computer with the
3248 opposite format as the one used to create the file, there may be
3249 some performance advantage to be gained by setting the endian-ness.</p>
3250 <p>The <code>zlib, complevel, shuffle, fletcher32, contiguous, chunksizes</code> and <code>endian</code>
3251 keywords are silently ignored for netCDF 3 files that do not use HDF5.</p>
3252 <p>The optional keyword <code>fill_value</code> can be used to override the default
3253 netCDF <code>_FillValue</code> (the value that the variable gets filled with before
3254 any data is written to it, defaults given in <code>netCDF4.default_fillvals</code>).
3255 If fill_value is set to <code>False</code>, then the variable is not pre-filled.</p>
3256 <p>If the optional keyword parameter <code>least_significant_digit</code> is
3257 specified, variable data will be truncated (quantized). In conjunction
3258 with <code>zlib=True</code> this produces 'lossy', but significantly more
3259 efficient compression. For example, if <code>least_significant_digit=1</code>,
3260 data will be quantized using <code>numpy.around(scale*data)/scale</code>, where
3261 scale = 2**bits, and bits is determined so that a precision of 0.1 is
3262 retained (in this case bits=4). From the
3263 <a href="http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml">PSD metadata conventions</a>:
3264 "least_significant_digit -- power of ten of the smallest decimal place
3265 in unpacked data that is a reliable value." Default is <code>None</code>, or no
3266 quantization, or 'lossless' compression.</p>
3267 <p>When creating variables in a <code>NETCDF4</code> or <code>NETCDF4_CLASSIC</code> formatted file,
3268 HDF5 creates something called a 'chunk cache' for each variable. The
3269 default size of the chunk cache may be large enough to completely fill
3270 available memory when creating thousands of variables. The optional
3271 keyword <code>chunk_cache</code> allows you to reduce (or increase) the size of
3272 the default chunk cache when creating a variable. The setting only
3273 persists as long as the Dataset is open - you can use the set_var_chunk_cache
3274 method to change it the next time the Dataset is opened.
3275 Warning - messing with this parameter can seriously degrade performance.</p>
3276 <p>The return value is the <a href="#netCDF4.Variable"><code>Variable</code></a> class instance describing the new
3277 variable.</p>
3278 <p>A list of names corresponding to netCDF variable attributes can be
3279 obtained with the <a href="#netCDF4.Variable"><code>Variable</code></a> method <a href="#netCDF4.Variable.ncattrs"><code>ncattrs</code></a>. A dictionary
3280 containing all the netCDF attribute name/value pairs is provided by
3281 the <code>__dict__</code> attribute of a <a href="#netCDF4.Variable"><code>Variable</code></a> instance.</p>
3282 <p><a href="#netCDF4.Variable"><code>Variable</code></a> instances behave much like array objects. Data can be
3283 assigned to or retrieved from a variable with indexing and slicing
3284 operations on the <a href="#netCDF4.Variable"><code>Variable</code></a> instance. A <a href="#netCDF4.Variable"><code>Variable</code></a> instance has six
3285 Dataset standard attributes: <code>dimensions, dtype, shape, ndim, name</code> and
3286 <code>least_significant_digit</code>. Application programs should never modify
3287 these attributes. The <code>dimensions</code> attribute is a tuple containing the
3288 names of the dimensions associated with this variable. The <code>dtype</code>
3289 attribute is a string describing the variable's data type (<code>i4, f8,
3290 S1,</code> etc). The <code>shape</code> attribute is a tuple describing the current
3291 sizes of all the variable's dimensions. The <code>name</code> attribute is a
3292 string containing the name of the Variable instance.
3293 The <code>least_significant_digit</code>
3294 attributes describes the power of ten of the smallest decimal place in
3295 the data the contains a reliable value. assigned to the <a href="#netCDF4.Variable"><code>Variable</code></a>
3296 instance. If <code>None</code>, the data is not truncated. The <code>ndim</code> attribute
3297 is the number of variable dimensions.</p></div>
3298 <div class="source_cont">
3299 </div>
3300
3301 </div>
3302
3303
3304 <div class="item">
3305 <div class="name def" id="netCDF4.Dataset.delncattr">
3306 <p>def <span class="ident">delncattr</span>(</p><p>self,name,value)</p>
3307 </div>
3308
3309
3310
3311
3312 <div class="desc"><p>delete a netCDF dataset or group attribute. Use if you need to delete a
3313 netCDF attribute with the same name as one of the reserved python
3314 attributes.</p></div>
3315 <div class="source_cont">
3316 </div>
3317
3318 </div>
3319
3320
3321 <div class="item">
3322 <div class="name def" id="netCDF4.Dataset.filepath">
3323 <p>def <span class="ident">filepath</span>(</p><p>self,encoding=None)</p>
3324 </div>
3325
3326
3327
3328
3329 <div class="desc"><p>Get the file system path (or the opendap URL) which was used to
3330 open/create the Dataset. Requires netcdf &gt;= 4.1.2. The path
3331 is decoded into a string using <code>sys.getfilesystemencoding()</code> by default, this can be
3332 changed using the <code>encoding</code> kwarg.</p></div>
3333 <div class="source_cont">
3334 </div>
3335
3336 </div>
3337
3338
3339 <div class="item">
3340 <div class="name def" id="netCDF4.Dataset.get_variables_by_attributes">
3341 <p>def <span class="ident">get_variables_by_attributes</span>(</p><p>...)</p>
3342 </div>
3343
3344
3345
3346
3347 <div class="desc"><p>Returns a list of variables that match specific conditions.</p>
3348 <p>Can pass in key=value parameters and variables are returned that
3349 contain all of the matches. For example,</p>
3350 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables with x-axis attribute.</span>
3351 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="s1">&#39;X&#39;</span><span class="p">)</span>
3352 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables with matching &quot;standard_name&quot; attribute</span>
3353 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">standard_name</span><span class="o">=</span><span class="s1">&#39;northward_sea_water_velocity&#39;</span><span class="p">)</span>
3354 </code></pre></div>
3355
3356
3357 <p>Can pass in key=callable parameter and variables are returned if the
3358 callable returns True. The callable should accept a single parameter,
3359 the attribute value. None is given as the attribute value when the
3360 attribute does not exist on the variable. For example,</p>
3361 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get Axis variables</span>
3362 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">&#39;X&#39;</span><span class="p">,</span> <span class="s1">&#39;Y&#39;</span><span class="p">,</span> <span class="s1">&#39;Z&#39;</span><span class="p">,</span> <span class="s1">&#39;T&#39;</span><span class="p">])</span>
3363 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables that don&#39;t have an &quot;axis&quot; attribute</span>
3364 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">)</span>
3365 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables that have a &quot;grid_mapping&quot; attribute</span>
3366 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">grid_mapping</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">)</span>
3367 </code></pre></div></div>
3368 <div class="source_cont">
3369 </div>
3370
3371 </div>
3372
3373
3374 <div class="item">
3375 <div class="name def" id="netCDF4.Dataset.getncattr">
3376 <p>def <span class="ident">getncattr</span>(</p><p>self,name)</p>
3377 </div>
3378
3379
3380
3381
3382 <div class="desc"><p>retrieve a netCDF dataset or group attribute.
3383 Use if you need to get a netCDF attribute with the same
3384 name as one of the reserved python attributes.</p>
3385 <p>option kwarg <code>encoding</code> can be used to specify the
3386 character encoding of a string attribute (default is <code>utf-8</code>).</p></div>
3387 <div class="source_cont">
3388 </div>
3389
3390 </div>
3391
3392
3393 <div class="item">
3394 <div class="name def" id="netCDF4.Dataset.isopen">
3395 <p>def <span class="ident">isopen</span>(</p><p>...)</p>
3396 </div>
3397
3398
3399
3400
3401 <div class="desc"><p>is the Dataset open or closed?</p></div>
3402 <div class="source_cont">
3403 </div>
3404
3405 </div>
3406
3407
3408 <div class="item">
3409 <div class="name def" id="netCDF4.Dataset.ncattrs">
3410 <p>def <span class="ident">ncattrs</span>(</p><p>self)</p>
3411 </div>
3412
3413
3414
3415
3416 <div class="desc"><p>return netCDF global attribute names for this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> in a list.</p></div>
3417 <div class="source_cont">
3418 </div>
3419
3420 </div>
3421
3422
3423 <div class="item">
3424 <div class="name def" id="netCDF4.Dataset.renameAttribute">
3425 <p>def <span class="ident">renameAttribute</span>(</p><p>self, oldname, newname)</p>
3426 </div>
3427
3428
3429
3430
3431 <div class="desc"><p>rename a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> attribute named <code>oldname</code> to <code>newname</code>.</p></div>
3432 <div class="source_cont">
3433 </div>
3434
3435 </div>
3436
3437
3438 <div class="item">
3439 <div class="name def" id="netCDF4.Dataset.renameDimension">
3440 <p>def <span class="ident">renameDimension</span>(</p><p>self, oldname, newname)</p>
3441 </div>
3442
3443
3444
3445
3446 <div class="desc"><p>rename a <a href="#netCDF4.Dimension"><code>Dimension</code></a> named <code>oldname</code> to <code>newname</code>.</p></div>
3447 <div class="source_cont">
3448 </div>
3449
3450 </div>
3451
3452
3453 <div class="item">
3454 <div class="name def" id="netCDF4.Dataset.renameGroup">
3455 <p>def <span class="ident">renameGroup</span>(</p><p>self, oldname, newname)</p>
3456 </div>
3457
3458
3459
3460
3461 <div class="desc"><p>rename a <a href="#netCDF4.Group"><code>Group</code></a> named <code>oldname</code> to <code>newname</code> (requires netcdf &gt;= 4.3.1).</p></div>
3462 <div class="source_cont">
3463 </div>
3464
3465 </div>
3466
3467
3468 <div class="item">
3469 <div class="name def" id="netCDF4.Dataset.renameVariable">
3470 <p>def <span class="ident">renameVariable</span>(</p><p>self, oldname, newname)</p>
3471 </div>
3472
3473
3474
3475
3476 <div class="desc"><p>rename a <a href="#netCDF4.Variable"><code>Variable</code></a> named <code>oldname</code> to <code>newname</code></p></div>
3477 <div class="source_cont">
3478 </div>
3479
3480 </div>
3481
3482
3483 <div class="item">
3484 <div class="name def" id="netCDF4.Dataset.set_always_mask">
3485 <p>def <span class="ident">set_always_mask</span>(</p><p>self, True_or_False)</p>
3486 </div>
3487
3488
3489
3490
3491 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_always_mask"><code>set_always_mask</code></a> for all variables contained in
3492 this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all
3493 variables in all its subgroups.</p>
3494 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion of
3495 masked arrays with no missing values to regular numpy arrays shall be
3496 applied for all variables. Default True. Set to False to restore the default behaviour
3497 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
3498 otherwise masked array returned).</p>
3499 <p><strong><em>Note</em></strong>: Calling this function only affects existing
3500 variables. Variables created after calling this function will follow
3501 the default behaviour.</p></div>
3502 <div class="source_cont">
3503 </div>
3504
3505 </div>
3506
3507
3508 <div class="item">
3509 <div class="name def" id="netCDF4.Dataset.set_auto_chartostring">
3510 <p>def <span class="ident">set_auto_chartostring</span>(</p><p>self, True_or_False)</p>
3511 </div>
3512
3513
3514
3515
3516 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_chartostring"><code>set_auto_chartostring</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
3517 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
3518 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion of
3519 all character arrays &lt;--&gt; string arrays should be performed for
3520 character variables (variables of type <code>NC_CHAR</code> or <code>S1</code>) with the
3521 <code>_Encoding</code> attribute set.</p>
3522 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
3523 after calling this function will follow the default behaviour.</p></div>
3524 <div class="source_cont">
3525 </div>
3526
3527 </div>
3528
3529
3530 <div class="item">
3531 <div class="name def" id="netCDF4.Dataset.set_auto_mask">
3532 <p>def <span class="ident">set_auto_mask</span>(</p><p>self, True_or_False)</p>
3533 </div>
3534
3535
3536
3537
3538 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_mask"><code>set_auto_mask</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
3539 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
3540 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion to masked arrays
3541 shall be applied for all variables.</p>
3542 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
3543 after calling this function will follow the default behaviour.</p></div>
3544 <div class="source_cont">
3545 </div>
3546
3547 </div>
3548
3549
3550 <div class="item">
3551 <div class="name def" id="netCDF4.Dataset.set_auto_maskandscale">
3552 <p>def <span class="ident">set_auto_maskandscale</span>(</p><p>self, True_or_False)</p>
3553 </div>
3554
3555
3556
3557
3558 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_maskandscale"><code>set_auto_maskandscale</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
3559 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
3560 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion to masked arrays
3561 and variable scaling shall be applied for all variables.</p>
3562 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
3563 after calling this function will follow the default behaviour.</p></div>
3564 <div class="source_cont">
3565 </div>
3566
3567 </div>
3568
3569
3570 <div class="item">
3571 <div class="name def" id="netCDF4.Dataset.set_auto_scale">
3572 <p>def <span class="ident">set_auto_scale</span>(</p><p>self, True_or_False)</p>
3573 </div>
3574
3575
3576
3577
3578 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_scale"><code>set_auto_scale</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
3579 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
3580 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic variable scaling
3581 shall be applied for all variables.</p>
3582 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
3583 after calling this function will follow the default behaviour.</p></div>
3584 <div class="source_cont">
3585 </div>
3586
3587 </div>
3588
3589
3590 <div class="item">
3591 <div class="name def" id="netCDF4.Dataset.set_fill_off">
3592 <p>def <span class="ident">set_fill_off</span>(</p><p>self)</p>
3593 </div>
3594
3595
3596
3597
3598 <div class="desc"><p>Sets the fill mode for a <a href="#netCDF4.Dataset"><code>Dataset</code></a> open for writing to <code>off</code>.</p>
3599 <p>This will prevent the data from being pre-filled with fill values, which
3600 may result in some performance improvements. However, you must then make
3601 sure the data is actually written before being read.</p></div>
3602 <div class="source_cont">
3603 </div>
3604
3605 </div>
3606
3607
3608 <div class="item">
3609 <div class="name def" id="netCDF4.Dataset.set_fill_on">
3610 <p>def <span class="ident">set_fill_on</span>(</p><p>self)</p>
3611 </div>
3612
3613
3614
3615
3616 <div class="desc"><p>Sets the fill mode for a <a href="#netCDF4.Dataset"><code>Dataset</code></a> open for writing to <code>on</code>.</p>
3617 <p>This causes data to be pre-filled with fill values. The fill values can be
3618 controlled by the variable's <code>_Fill_Value</code> attribute, but is usually
3619 sufficient to the use the netCDF default <code>_Fill_Value</code> (defined
3620 separately for each variable type). The default behavior of the netCDF
3621 library corresponds to <code>set_fill_on</code>. Data which are equal to the
3622 <code>_Fill_Value</code> indicate that the variable was created, but never written
3623 to.</p></div>
3624 <div class="source_cont">
3625 </div>
3626
3627 </div>
3628
3629
3630 <div class="item">
3631 <div class="name def" id="netCDF4.Dataset.set_ncstring_attrs">
3632 <p>def <span class="ident">set_ncstring_attrs</span>(</p><p>self, True_or_False)</p>
3633 </div>
3634
3635
3636
3637
3638 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_ncstring_attrs"><code>set_ncstring_attrs</code></a> for all variables contained in
3639 this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all its
3640 subgroups and their variables.</p>
3641 <p><strong><code>True_or_False</code></strong>: Boolean determining if all string attributes are
3642 created as variable-length NC_STRINGs, (if True), or if ascii text
3643 attributes are stored as NC_CHARs (if False; default)</p>
3644 <p><strong><em>Note</em></strong>: Calling this function only affects newly created attributes
3645 of existing (sub-) groups and their variables.</p></div>
3646 <div class="source_cont">
3647 </div>
3648
3649 </div>
3650
3651
3652 <div class="item">
3653 <div class="name def" id="netCDF4.Dataset.setncattr">
3654 <p>def <span class="ident">setncattr</span>(</p><p>self,name,value)</p>
3655 </div>
3656
3657
3658
3659
3660 <div class="desc"><p>set a netCDF dataset or group attribute using name,value pair.
3661 Use if you need to set a netCDF attribute with the
3662 with the same name as one of the reserved python attributes.</p></div>
3663 <div class="source_cont">
3664 </div>
3665
3666 </div>
3667
3668
3669 <div class="item">
3670 <div class="name def" id="netCDF4.Dataset.setncattr_string">
3671 <p>def <span class="ident">setncattr_string</span>(</p><p>self,name,value)</p>
3672 </div>
3673
3674
3675
3676
3677 <div class="desc"><p>set a netCDF dataset or group string attribute using name,value pair.
3678 Use if you need to ensure that a netCDF attribute is created with type
3679 <code>NC_STRING</code> if the file format is <code>NETCDF4</code>.</p></div>
3680 <div class="source_cont">
3681 </div>
3682
3683 </div>
3684
3685
3686 <div class="item">
3687 <div class="name def" id="netCDF4.Dataset.setncatts">
3688 <p>def <span class="ident">setncatts</span>(</p><p>self,attdict)</p>
3689 </div>
3690
3691
3692
3693
3694 <div class="desc"><p>set a bunch of netCDF dataset or group attributes at once using a python dictionary.
3695 This may be faster when setting a lot of attributes for a <code>NETCDF3</code>
3696 formatted file, since nc_redef/nc_enddef is not called in between setting
3697 each attribute</p></div>
3698 <div class="source_cont">
3699 </div>
3700
3701 </div>
3702
3703
3704 <div class="item">
3705 <div class="name def" id="netCDF4.Dataset.sync">
3706 <p>def <span class="ident">sync</span>(</p><p>self)</p>
3707 </div>
3708
3709
3710
3711
3712 <div class="desc"><p>Writes all buffered data in the <a href="#netCDF4.Dataset"><code>Dataset</code></a> to the disk file.</p></div>
3713 <div class="source_cont">
3714 </div>
3715
3716 </div>
3717
3718 </div>
3719 </div>
3720
3721 <div class="item">
3722 <p id="netCDF4.Dimension" class="name">class <span class="ident">Dimension</span></p>
3723
3724
3725 <div class="desc"><p>A netCDF <a href="#netCDF4.Dimension"><code>Dimension</code></a> is used to describe the coordinates of a <a href="#netCDF4.Variable"><code>Variable</code></a>.
3726 See <a href="#netCDF4.Dimension.__init__"><code>__init__</code></a> for more details.</p>
3727 <p>The current maximum size of a <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance can be obtained by
3728 calling the python <code>len</code> function on the <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance. The
3729 <a href="#netCDF4.Dimension.isunlimited"><code>isunlimited</code></a> method of a <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance can be used to
3730 determine if the dimension is unlimited.</p>
3731 <p>Read-only class variables:</p>
3732 <p><strong><code>name</code></strong>: String name, used when creating a <a href="#netCDF4.Variable"><code>Variable</code></a> with
3733 <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a>.</p>
3734 <p><strong><code>size</code></strong>: Current <a href="#netCDF4.Dimension"><code>Dimension</code></a> size (same as <code>len(d)</code>, where <code>d</code> is a
3735 <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance).</p></div>
3736 <div class="source_cont">
3737 </div>
3738
3739
3740 <div class="class">
3741 <h3>Ancestors (in MRO)</h3>
3742 <ul class="class_list">
3743 <li><a href="#netCDF4.Dimension">Dimension</a></li>
3744 <li>builtins.object</li>
3745 </ul>
3746 <h3>Class variables</h3>
3747 <div class="item">
3748 <p id="netCDF4.Dimension.name" class="name">var <span class="ident">name</span></p>
3749
3750
3751
3752
3753 <div class="desc"><p>A string describing the name of the <a href="#netCDF4.Dimension"><code>Dimension</code></a> - used when creating a
3754 <a href="#netCDF4.Variable"><code>Variable</code></a> instance with <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a>.</p></div>
3755 <div class="source_cont">
3756 </div>
3757
3758 </div>
3759 <div class="item">
3760 <p id="netCDF4.Dimension.size" class="name">var <span class="ident">size</span></p>
3761
3762
3763
3764
3765 <div class="source_cont">
3766 </div>
3767
3768 </div>
3769 <h3>Static methods</h3>
3770
3771 <div class="item">
3772 <div class="name def" id="netCDF4.Dimension.__init__">
3773 <p>def <span class="ident">__init__</span>(</p><p>self, group, name, size=None)</p>
3774 </div>
3775
3776
3777
3778
3779 <div class="desc"><p><a href="#netCDF4.Dimension"><code>Dimension</code></a> constructor.</p>
3780 <p><strong><code>group</code></strong>: <a href="#netCDF4.Group"><code>Group</code></a> instance to associate with dimension.</p>
3781 <p><strong><code>name</code></strong>: Name of the dimension.</p>
3782 <p><strong><code>size</code></strong>: Size of the dimension. <code>None</code> or 0 means unlimited. (Default <code>None</code>).</p>
3783 <p><strong><em>Note</em></strong>: <a href="#netCDF4.Dimension"><code>Dimension</code></a> instances should be created using the
3784 <a href="#netCDF4.Dataset.createDimension"><code>createDimension</code></a> method of a <a href="#netCDF4.Group"><code>Group</code></a> or
3785 <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance, not using <a href="#netCDF4.Dimension.__init__"><code>__init__</code></a> directly.</p></div>
3786 <div class="source_cont">
3787 </div>
3788
3789 </div>
3790
3791
3792 <div class="item">
3793 <div class="name def" id="netCDF4.Dimension.group">
3794 <p>def <span class="ident">group</span>(</p><p>self)</p>
3795 </div>
3796
3797
3798
3799
3800 <div class="desc"><p>return the group that this <a href="#netCDF4.Dimension"><code>Dimension</code></a> is a member of.</p></div>
3801 <div class="source_cont">
3802 </div>
3803
3804 </div>
3805
3806
3807 <div class="item">
3808 <div class="name def" id="netCDF4.Dimension.isunlimited">
3809 <p>def <span class="ident">isunlimited</span>(</p><p>self)</p>
3810 </div>
3811
3812
3813
3814
3815 <div class="desc"><p>returns <code>True</code> if the <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance is unlimited, <code>False</code> otherwise.</p></div>
3816 <div class="source_cont">
3817 </div>
3818
3819 </div>
3820
3821 </div>
3822 </div>
3823
3824 <div class="item">
3825 <p id="netCDF4.EnumType" class="name">class <span class="ident">EnumType</span></p>
3826
3827
3828 <div class="desc"><p>A <a href="#netCDF4.EnumType"><code>EnumType</code></a> instance is used to describe an Enum data
3829 type, and can be passed to the the <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> method of
3830 a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance. See
3831 <a href="#netCDF4.EnumType.__init__"><code>__init__</code></a> for more details.</p>
3832 <p>The instance variables <code>dtype</code>, <code>name</code> and <code>enum_dict</code> should not be modified by
3833 the user.</p></div>
3834 <div class="source_cont">
3835 </div>
3836
3837
3838 <div class="class">
3839 <h3>Ancestors (in MRO)</h3>
3840 <ul class="class_list">
3841 <li><a href="#netCDF4.EnumType">EnumType</a></li>
3842 <li>builtins.object</li>
3843 </ul>
3844 <h3>Class variables</h3>
3845 <div class="item">
3846 <p id="netCDF4.EnumType.dtype" class="name">var <span class="ident">dtype</span></p>
3847
3848
3849
3850
3851 <div class="desc"><p>A numpy integer dtype object describing the base type for the Enum.</p></div>
3852 <div class="source_cont">
3853 </div>
3854
3855 </div>
3856 <div class="item">
3857 <p id="netCDF4.EnumType.enum_dict" class="name">var <span class="ident">enum_dict</span></p>
3858
3859
3860
3861
3862 <div class="desc"><p>A python dictionary describing the enum fields and values.</p></div>
3863 <div class="source_cont">
3864 </div>
3865
3866 </div>
3867 <div class="item">
3868 <p id="netCDF4.EnumType.name" class="name">var <span class="ident">name</span></p>
3869
3870
3871
3872
3873 <div class="desc"><p>String name.</p></div>
3874 <div class="source_cont">
3875 </div>
3876
3877 </div>
3878 <h3>Static methods</h3>
3879
3880 <div class="item">
3881 <div class="name def" id="netCDF4.EnumType.__init__">
3882 <p>def <span class="ident">__init__</span>(</p><p>group, datatype, datatype_name, enum_dict)</p>
3883 </div>
3884
3885
3886
3887
3888 <div class="desc"><p>EnumType constructor.</p>
3889 <p><strong><code>group</code></strong>: <a href="#netCDF4.Group"><code>Group</code></a> instance to associate with the VLEN datatype.</p>
3890 <p><strong><code>datatype</code></strong>: An numpy integer dtype object describing the base type
3891 for the Enum.</p>
3892 <p><strong><code>datatype_name</code></strong>: a Python string containing a description of the
3893 Enum data type.</p>
3894 <p><strong><code>enum_dict</code></strong>: a Python dictionary containing the Enum field/value
3895 pairs.</p>
3896 <p><strong><em><code>Note</code></em></strong>: <a href="#netCDF4.EnumType"><code>EnumType</code></a> instances should be created using the
3897 <a href="#netCDF4.Dataset.createEnumType"><code>createEnumType</code></a>
3898 method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance, not using this class directly.</p></div>
3899 <div class="source_cont">
3900 </div>
3901
3902 </div>
3903
3904 </div>
3905 </div>
3906
3907 <div class="item">
3908 <p id="netCDF4.Group" class="name">class <span class="ident">Group</span></p>
3909
3910
3911 <div class="desc"><p>Groups define a hierarchical namespace within a netCDF file. They are
3912 analogous to directories in a unix filesystem. Each <a href="#netCDF4.Group"><code>Group</code></a> behaves like
3913 a <a href="#netCDF4.Dataset"><code>Dataset</code></a> within a Dataset, and can contain it's own variables,
3914 dimensions and attributes (and other Groups). See <a href="#netCDF4.Group.__init__"><code>__init__</code></a>
3915 for more details.</p>
3916 <p><a href="#netCDF4.Group"><code>Group</code></a> inherits from <a href="#netCDF4.Dataset"><code>Dataset</code></a>, so all the
3917 <a href="#netCDF4.Dataset"><code>Dataset</code></a> class methods and variables are available
3918 to a <a href="#netCDF4.Group"><code>Group</code></a> instance (except the <code>close</code> method).</p>
3919 <p>Additional read-only class variables:</p>
3920 <p><strong><code>name</code></strong>: String describing the group name.</p></div>
3921 <div class="source_cont">
3922 </div>
3923
3924
3925 <div class="class">
3926 <h3>Ancestors (in MRO)</h3>
3927 <ul class="class_list">
3928 <li><a href="#netCDF4.Group">Group</a></li>
3929 <li><a href="#netCDF4.Dataset">Dataset</a></li>
3930 <li>builtins.object</li>
3931 </ul>
3932 <h3>Class variables</h3>
3933 <div class="item">
3934 <p id="netCDF4.Group.cmptypes" class="name">var <span class="ident">cmptypes</span></p>
3935
3936
3937
3938
3939 <div class="source_cont">
3940 </div>
3941
3942 </div>
3943 <div class="item">
3944 <p id="netCDF4.Group.data_model" class="name">var <span class="ident">data_model</span></p>
3945
3946
3947
3948
3949 <div class="source_cont">
3950 </div>
3951
3952 </div>
3953 <div class="item">
3954 <p id="netCDF4.Group.dimensions" class="name">var <span class="ident">dimensions</span></p>
3955
3956
3957
3958
3959 <div class="source_cont">
3960 </div>
3961
3962 </div>
3963 <div class="item">
3964 <p id="netCDF4.Group.disk_format" class="name">var <span class="ident">disk_format</span></p>
3965
3966
3967
3968
3969 <div class="source_cont">
3970 </div>
3971
3972 </div>
3973 <div class="item">
3974 <p id="netCDF4.Group.enumtypes" class="name">var <span class="ident">enumtypes</span></p>
3975
3976
3977
3978
3979 <div class="source_cont">
3980 </div>
3981
3982 </div>
3983 <div class="item">
3984 <p id="netCDF4.Group.file_format" class="name">var <span class="ident">file_format</span></p>
3985
3986
3987
3988
3989 <div class="source_cont">
3990 </div>
3991
3992 </div>
3993 <div class="item">
3994 <p id="netCDF4.Group.groups" class="name">var <span class="ident">groups</span></p>
3995
3996
3997
3998
3999 <div class="source_cont">
4000 </div>
4001
4002 </div>
4003 <div class="item">
4004 <p id="netCDF4.Group.keepweakref" class="name">var <span class="ident">keepweakref</span></p>
4005
4006
4007
4008
4009 <div class="source_cont">
4010 </div>
4011
4012 </div>
4013 <div class="item">
4014 <p id="netCDF4.Group.name" class="name">var <span class="ident">name</span></p>
4015
4016
4017
4018
4019 <div class="desc"><p>A string describing the name of the <a href="#netCDF4.Group"><code>Group</code></a>.</p></div>
4020 <div class="source_cont">
4021 </div>
4022
4023 </div>
4024 <div class="item">
4025 <p id="netCDF4.Group.parent" class="name">var <span class="ident">parent</span></p>
4026
4027
4028
4029
4030 <div class="source_cont">
4031 </div>
4032
4033 </div>
4034 <div class="item">
4035 <p id="netCDF4.Group.path" class="name">var <span class="ident">path</span></p>
4036
4037
4038
4039
4040 <div class="source_cont">
4041 </div>
4042
4043 </div>
4044 <div class="item">
4045 <p id="netCDF4.Group.variables" class="name">var <span class="ident">variables</span></p>
4046
4047
4048
4049
4050 <div class="source_cont">
4051 </div>
4052
4053 </div>
4054 <div class="item">
4055 <p id="netCDF4.Group.vltypes" class="name">var <span class="ident">vltypes</span></p>
4056
4057
4058
4059
4060 <div class="source_cont">
4061 </div>
4062
4063 </div>
4064 <h3>Static methods</h3>
4065
4066 <div class="item">
4067 <div class="name def" id="netCDF4.Group.__init__">
4068 <p>def <span class="ident">__init__</span>(</p><p>self, parent, name)</p>
4069 </div>
4070
4071 <p class="inheritance">
4072 <strong>Inheritance:</strong>
4073 <code><a href="#netCDF4.Dataset">Dataset</a></code>.<code><a href="#netCDF4.Dataset.__init__">__init__</a></code>
4074 </p>
4075
4076
4077
4078 <div class="desc"><p><a href="#netCDF4.Group"><code>Group</code></a> constructor.</p>
4079 <p><strong><code>parent</code></strong>: <a href="#netCDF4.Group"><code>Group</code></a> instance for the parent group. If being created
4080 in the root group, use a <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance.</p>
4081 <p><strong><code>name</code></strong>: - Name of the group.</p>
4082 <p><strong><em>Note</em></strong>: <a href="#netCDF4.Group"><code>Group</code></a> instances should be created using the
4083 <a href="#netCDF4.Dataset.createGroup"><code>createGroup</code></a> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance, or
4084 another <a href="#netCDF4.Group"><code>Group</code></a> instance, not using this class directly.</p></div>
4085 <div class="source_cont">
4086 </div>
4087
4088 </div>
4089
4090
4091 <div class="item">
4092 <div class="name def" id="netCDF4.Group.close">
4093 <p>def <span class="ident">close</span>(</p><p>self)</p>
4094 </div>
4095
4096
4097
4098
4099 <div class="desc"><p>overrides <a href="#netCDF4.Dataset"><code>Dataset</code></a> close method which does not apply to <a href="#netCDF4.Group"><code>Group</code></a>
4100 instances, raises IOError.</p></div>
4101 <div class="source_cont">
4102 </div>
4103
4104 </div>
4105
4106
4107 <div class="item">
4108 <div class="name def" id="netCDF4.Group.createCompoundType">
4109 <p>def <span class="ident">createCompoundType</span>(</p><p>self, datatype, datatype_name)</p>
4110 </div>
4111
4112
4113
4114
4115 <div class="desc"><p>Creates a new compound data type named <code>datatype_name</code> from the numpy
4116 dtype object <code>datatype</code>.</p>
4117 <p><strong><em>Note</em></strong>: If the new compound data type contains other compound data types
4118 (i.e. it is a 'nested' compound type, where not all of the elements
4119 are homogeneous numeric data types), then the 'inner' compound types <strong>must</strong> be
4120 created first.</p>
4121 <p>The return value is the <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> class instance describing the new
4122 datatype.</p></div>
4123 <div class="source_cont">
4124 </div>
4125
4126 </div>
4127
4128
4129 <div class="item">
4130 <div class="name def" id="netCDF4.Group.createDimension">
4131 <p>def <span class="ident">createDimension</span>(</p><p>self, dimname, size=None)</p>
4132 </div>
4133
4134
4135
4136
4137 <div class="desc"><p>Creates a new dimension with the given <code>dimname</code> and <code>size</code>.</p>
4138 <p><code>size</code> must be a positive integer or <code>None</code>, which stands for
4139 "unlimited" (default is <code>None</code>). Specifying a size of 0 also
4140 results in an unlimited dimension. The return value is the <a href="#netCDF4.Dimension"><code>Dimension</code></a>
4141 class instance describing the new dimension. To determine the current
4142 maximum size of the dimension, use the <code>len</code> function on the <a href="#netCDF4.Dimension"><code>Dimension</code></a>
4143 instance. To determine if a dimension is 'unlimited', use the
4144 <a href="#netCDF4.Dimension.isunlimited"><code>isunlimited</code></a> method of the <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance.</p></div>
4145 <div class="source_cont">
4146 </div>
4147
4148 </div>
4149
4150
4151 <div class="item">
4152 <div class="name def" id="netCDF4.Group.createEnumType">
4153 <p>def <span class="ident">createEnumType</span>(</p><p>self, datatype, datatype_name, enum_dict)</p>
4154 </div>
4155
4156
4157
4158
4159 <div class="desc"><p>Creates a new Enum data type named <code>datatype_name</code> from a numpy
4160 integer dtype object <code>datatype</code>, and a python dictionary
4161 defining the enum fields and values.</p>
4162 <p>The return value is the <a href="#netCDF4.EnumType"><code>EnumType</code></a> class instance describing the new
4163 datatype.</p></div>
4164 <div class="source_cont">
4165 </div>
4166
4167 </div>
4168
4169
4170 <div class="item">
4171 <div class="name def" id="netCDF4.Group.createGroup">
4172 <p>def <span class="ident">createGroup</span>(</p><p>self, groupname)</p>
4173 </div>
4174
4175
4176
4177
4178 <div class="desc"><p>Creates a new <a href="#netCDF4.Group"><code>Group</code></a> with the given <code>groupname</code>.</p>
4179 <p>If <code>groupname</code> is specified as a path, using forward slashes as in unix to
4180 separate components, then intermediate groups will be created as necessary
4181 (analogous to <code>mkdir -p</code> in unix). For example,
4182 <code>createGroup('/GroupA/GroupB/GroupC')</code> will create <code>GroupA</code>,
4183 <code>GroupA/GroupB</code>, and <code>GroupA/GroupB/GroupC</code>, if they don't already exist.
4184 If the specified path describes a group that already exists, no error is
4185 raised.</p>
4186 <p>The return value is a <a href="#netCDF4.Group"><code>Group</code></a> class instance.</p></div>
4187 <div class="source_cont">
4188 </div>
4189
4190 </div>
4191
4192
4193 <div class="item">
4194 <div class="name def" id="netCDF4.Group.createVLType">
4195 <p>def <span class="ident">createVLType</span>(</p><p>self, datatype, datatype_name)</p>
4196 </div>
4197
4198
4199
4200
4201 <div class="desc"><p>Creates a new VLEN data type named <code>datatype_name</code> from a numpy
4202 dtype object <code>datatype</code>.</p>
4203 <p>The return value is the <a href="#netCDF4.VLType"><code>VLType</code></a> class instance describing the new
4204 datatype.</p></div>
4205 <div class="source_cont">
4206 </div>
4207
4208 </div>
4209
4210
4211 <div class="item">
4212 <div class="name def" id="netCDF4.Group.createVariable">
4213 <p>def <span class="ident">createVariable</span>(</p><p>self, varname, datatype, dimensions=(), zlib=False, complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None, endian=&#39;native&#39;, least_significant_digit=None, fill_value=None, chunk_cache=None)</p>
4214 </div>
4215
4216
4217
4218
4219 <div class="desc"><p>Creates a new variable with the given <code>varname</code>, <code>datatype</code>, and
4220 <code>dimensions</code>. If dimensions are not given, the variable is assumed to be
4221 a scalar.</p>
4222 <p>If <code>varname</code> is specified as a path, using forward slashes as in unix to
4223 separate components, then intermediate groups will be created as necessary
4224 For example, <code>createVariable('/GroupA/GroupB/VarC', float, ('x','y'))</code> will create groups <code>GroupA</code>
4225 and <code>GroupA/GroupB</code>, plus the variable <code>GroupA/GroupB/VarC</code>, if the preceding
4226 groups don't already exist.</p>
4227 <p>The <code>datatype</code> can be a numpy datatype object, or a string that describes
4228 a numpy dtype object (like the <code>dtype.str</code> attribute of a numpy array).
4229 Supported specifiers include: <code>'S1' or 'c' (NC_CHAR), 'i1' or 'b' or 'B'
4230 (NC_BYTE), 'u1' (NC_UBYTE), 'i2' or 'h' or 's' (NC_SHORT), 'u2'
4231 (NC_USHORT), 'i4' or 'i' or 'l' (NC_INT), 'u4' (NC_UINT), 'i8' (NC_INT64),
4232 'u8' (NC_UINT64), 'f4' or 'f' (NC_FLOAT), 'f8' or 'd' (NC_DOUBLE)</code>.
4233 <code>datatype</code> can also be a <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> instance
4234 (for a structured, or compound array), a <a href="#netCDF4.VLType"><code>VLType</code></a> instance
4235 (for a variable-length array), or the python <code>str</code> builtin
4236 (for a variable-length string array). Numpy string and unicode datatypes with
4237 length greater than one are aliases for <code>str</code>.</p>
4238 <p>Data from netCDF variables is presented to python as numpy arrays with
4239 the corresponding data type.</p>
4240 <p><code>dimensions</code> must be a tuple containing dimension names (strings) that
4241 have been defined previously using <a href="#netCDF4.Dataset.createDimension"><code>createDimension</code></a>. The default value
4242 is an empty tuple, which means the variable is a scalar.</p>
4243 <p>If the optional keyword <code>zlib</code> is <code>True</code>, the data will be compressed in
4244 the netCDF file using gzip compression (default <code>False</code>).</p>
4245 <p>The optional keyword <code>complevel</code> is an integer between 1 and 9 describing
4246 the level of compression desired (default 4). Ignored if <code>zlib=False</code>.</p>
4247 <p>If the optional keyword <code>shuffle</code> is <code>True</code>, the HDF5 shuffle filter
4248 will be applied before compressing the data (default <code>True</code>). This
4249 significantly improves compression. Default is <code>True</code>. Ignored if
4250 <code>zlib=False</code>.</p>
4251 <p>If the optional keyword <code>fletcher32</code> is <code>True</code>, the Fletcher32 HDF5
4252 checksum algorithm is activated to detect errors. Default <code>False</code>.</p>
4253 <p>If the optional keyword <code>contiguous</code> is <code>True</code>, the variable data is
4254 stored contiguously on disk. Default <code>False</code>. Setting to <code>True</code> for
4255 a variable with an unlimited dimension will trigger an error.</p>
4256 <p>The optional keyword <code>chunksizes</code> can be used to manually specify the
4257 HDF5 chunksizes for each dimension of the variable. A detailed
4258 discussion of HDF chunking and I/O performance is available
4259 <a href="http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html">here</a>.
4260 Basically, you want the chunk size for each dimension to match as
4261 closely as possible the size of the data block that users will read
4262 from the file. <code>chunksizes</code> cannot be set if <code>contiguous=True</code>.</p>
4263 <p>The optional keyword <code>endian</code> can be used to control whether the
4264 data is stored in little or big endian format on disk. Possible
4265 values are <code>little, big</code> or <code>native</code> (default). The library
4266 will automatically handle endian conversions when the data is read,
4267 but if the data is always going to be read on a computer with the
4268 opposite format as the one used to create the file, there may be
4269 some performance advantage to be gained by setting the endian-ness.</p>
4270 <p>The <code>zlib, complevel, shuffle, fletcher32, contiguous, chunksizes</code> and <code>endian</code>
4271 keywords are silently ignored for netCDF 3 files that do not use HDF5.</p>
4272 <p>The optional keyword <code>fill_value</code> can be used to override the default
4273 netCDF <code>_FillValue</code> (the value that the variable gets filled with before
4274 any data is written to it, defaults given in <code>netCDF4.default_fillvals</code>).
4275 If fill_value is set to <code>False</code>, then the variable is not pre-filled.</p>
4276 <p>If the optional keyword parameter <code>least_significant_digit</code> is
4277 specified, variable data will be truncated (quantized). In conjunction
4278 with <code>zlib=True</code> this produces 'lossy', but significantly more
4279 efficient compression. For example, if <code>least_significant_digit=1</code>,
4280 data will be quantized using <code>numpy.around(scale*data)/scale</code>, where
4281 scale = 2**bits, and bits is determined so that a precision of 0.1 is
4282 retained (in this case bits=4). From the
4283 <a href="http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml">PSD metadata conventions</a>:
4284 "least_significant_digit -- power of ten of the smallest decimal place
4285 in unpacked data that is a reliable value." Default is <code>None</code>, or no
4286 quantization, or 'lossless' compression.</p>
4287 <p>When creating variables in a <code>NETCDF4</code> or <code>NETCDF4_CLASSIC</code> formatted file,
4288 HDF5 creates something called a 'chunk cache' for each variable. The
4289 default size of the chunk cache may be large enough to completely fill
4290 available memory when creating thousands of variables. The optional
4291 keyword <code>chunk_cache</code> allows you to reduce (or increase) the size of
4292 the default chunk cache when creating a variable. The setting only
4293 persists as long as the Dataset is open - you can use the set_var_chunk_cache
4294 method to change it the next time the Dataset is opened.
4295 Warning - messing with this parameter can seriously degrade performance.</p>
4296 <p>The return value is the <a href="#netCDF4.Variable"><code>Variable</code></a> class instance describing the new
4297 variable.</p>
4298 <p>A list of names corresponding to netCDF variable attributes can be
4299 obtained with the <a href="#netCDF4.Variable"><code>Variable</code></a> method <a href="#netCDF4.Variable.ncattrs"><code>ncattrs</code></a>. A dictionary
4300 containing all the netCDF attribute name/value pairs is provided by
4301 the <code>__dict__</code> attribute of a <a href="#netCDF4.Variable"><code>Variable</code></a> instance.</p>
4302 <p><a href="#netCDF4.Variable"><code>Variable</code></a> instances behave much like array objects. Data can be
4303 assigned to or retrieved from a variable with indexing and slicing
4304 operations on the <a href="#netCDF4.Variable"><code>Variable</code></a> instance. A <a href="#netCDF4.Variable"><code>Variable</code></a> instance has six
4305 Dataset standard attributes: <code>dimensions, dtype, shape, ndim, name</code> and
4306 <code>least_significant_digit</code>. Application programs should never modify
4307 these attributes. The <code>dimensions</code> attribute is a tuple containing the
4308 names of the dimensions associated with this variable. The <code>dtype</code>
4309 attribute is a string describing the variable's data type (<code>i4, f8,
4310 S1,</code> etc). The <code>shape</code> attribute is a tuple describing the current
4311 sizes of all the variable's dimensions. The <code>name</code> attribute is a
4312 string containing the name of the Variable instance.
4313 The <code>least_significant_digit</code>
4314 attributes describes the power of ten of the smallest decimal place in
4315 the data the contains a reliable value. assigned to the <a href="#netCDF4.Variable"><code>Variable</code></a>
4316 instance. If <code>None</code>, the data is not truncated. The <code>ndim</code> attribute
4317 is the number of variable dimensions.</p></div>
4318 <div class="source_cont">
4319 </div>
4320
4321 </div>
4322
4323
4324 <div class="item">
4325 <div class="name def" id="netCDF4.Group.delncattr">
4326 <p>def <span class="ident">delncattr</span>(</p><p>self,name,value)</p>
4327 </div>
4328
4329
4330
4331
4332 <div class="desc"><p>delete a netCDF dataset or group attribute. Use if you need to delete a
4333 netCDF attribute with the same name as one of the reserved python
4334 attributes.</p></div>
4335 <div class="source_cont">
4336 </div>
4337
4338 </div>
4339
4340
4341 <div class="item">
4342 <div class="name def" id="netCDF4.Group.filepath">
4343 <p>def <span class="ident">filepath</span>(</p><p>self,encoding=None)</p>
4344 </div>
4345
4346
4347
4348
4349 <div class="desc"><p>Get the file system path (or the opendap URL) which was used to
4350 open/create the Dataset. Requires netcdf &gt;= 4.1.2. The path
4351 is decoded into a string using <code>sys.getfilesystemencoding()</code> by default, this can be
4352 changed using the <code>encoding</code> kwarg.</p></div>
4353 <div class="source_cont">
4354 </div>
4355
4356 </div>
4357
4358
4359 <div class="item">
4360 <div class="name def" id="netCDF4.Group.get_variables_by_attributes">
4361 <p>def <span class="ident">get_variables_by_attributes</span>(</p><p>...)</p>
4362 </div>
4363
4364
4365
4366
4367 <div class="desc"><p>Returns a list of variables that match specific conditions.</p>
4368 <p>Can pass in key=value parameters and variables are returned that
4369 contain all of the matches. For example,</p>
4370 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables with x-axis attribute.</span>
4371 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="s1">&#39;X&#39;</span><span class="p">)</span>
4372 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables with matching &quot;standard_name&quot; attribute</span>
4373 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">standard_name</span><span class="o">=</span><span class="s1">&#39;northward_sea_water_velocity&#39;</span><span class="p">)</span>
4374 </code></pre></div>
4375
4376
4377 <p>Can pass in key=callable parameter and variables are returned if the
4378 callable returns True. The callable should accept a single parameter,
4379 the attribute value. None is given as the attribute value when the
4380 attribute does not exist on the variable. For example,</p>
4381 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get Axis variables</span>
4382 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">&#39;X&#39;</span><span class="p">,</span> <span class="s1">&#39;Y&#39;</span><span class="p">,</span> <span class="s1">&#39;Z&#39;</span><span class="p">,</span> <span class="s1">&#39;T&#39;</span><span class="p">])</span>
4383 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables that don&#39;t have an &quot;axis&quot; attribute</span>
4384 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">)</span>
4385 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables that have a &quot;grid_mapping&quot; attribute</span>
4386 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">grid_mapping</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">)</span>
4387 </code></pre></div></div>
4388 <div class="source_cont">
4389 </div>
4390
4391 </div>
4392
4393
4394 <div class="item">
4395 <div class="name def" id="netCDF4.Group.getncattr">
4396 <p>def <span class="ident">getncattr</span>(</p><p>self,name)</p>
4397 </div>
4398
4399
4400
4401
4402 <div class="desc"><p>retrieve a netCDF dataset or group attribute.
4403 Use if you need to get a netCDF attribute with the same
4404 name as one of the reserved python attributes.</p>
4405 <p>option kwarg <code>encoding</code> can be used to specify the
4406 character encoding of a string attribute (default is <code>utf-8</code>).</p></div>
4407 <div class="source_cont">
4408 </div>
4409
4410 </div>
4411
4412
4413 <div class="item">
4414 <div class="name def" id="netCDF4.Group.isopen">
4415 <p>def <span class="ident">isopen</span>(</p><p>...)</p>
4416 </div>
4417
4418
4419
4420
4421 <div class="desc"><p>is the Dataset open or closed?</p></div>
4422 <div class="source_cont">
4423 </div>
4424
4425 </div>
4426
4427
4428 <div class="item">
4429 <div class="name def" id="netCDF4.Group.ncattrs">
4430 <p>def <span class="ident">ncattrs</span>(</p><p>self)</p>
4431 </div>
4432
4433
4434
4435
4436 <div class="desc"><p>return netCDF global attribute names for this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> in a list.</p></div>
4437 <div class="source_cont">
4438 </div>
4439
4440 </div>
4441
4442
4443 <div class="item">
4444 <div class="name def" id="netCDF4.Group.renameAttribute">
4445 <p>def <span class="ident">renameAttribute</span>(</p><p>self, oldname, newname)</p>
4446 </div>
4447
4448
4449
4450
4451 <div class="desc"><p>rename a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> attribute named <code>oldname</code> to <code>newname</code>.</p></div>
4452 <div class="source_cont">
4453 </div>
4454
4455 </div>
4456
4457
4458 <div class="item">
4459 <div class="name def" id="netCDF4.Group.renameDimension">
4460 <p>def <span class="ident">renameDimension</span>(</p><p>self, oldname, newname)</p>
4461 </div>
4462
4463
4464
4465
4466 <div class="desc"><p>rename a <a href="#netCDF4.Dimension"><code>Dimension</code></a> named <code>oldname</code> to <code>newname</code>.</p></div>
4467 <div class="source_cont">
4468 </div>
4469
4470 </div>
4471
4472
4473 <div class="item">
4474 <div class="name def" id="netCDF4.Group.renameGroup">
4475 <p>def <span class="ident">renameGroup</span>(</p><p>self, oldname, newname)</p>
4476 </div>
4477
4478
4479
4480
4481 <div class="desc"><p>rename a <a href="#netCDF4.Group"><code>Group</code></a> named <code>oldname</code> to <code>newname</code> (requires netcdf &gt;= 4.3.1).</p></div>
4482 <div class="source_cont">
4483 </div>
4484
4485 </div>
4486
4487
4488 <div class="item">
4489 <div class="name def" id="netCDF4.Group.renameVariable">
4490 <p>def <span class="ident">renameVariable</span>(</p><p>self, oldname, newname)</p>
4491 </div>
4492
4493
4494
4495
4496 <div class="desc"><p>rename a <a href="#netCDF4.Variable"><code>Variable</code></a> named <code>oldname</code> to <code>newname</code></p></div>
4497 <div class="source_cont">
4498 </div>
4499
4500 </div>
4501
4502
4503 <div class="item">
4504 <div class="name def" id="netCDF4.Group.set_always_mask">
4505 <p>def <span class="ident">set_always_mask</span>(</p><p>self, True_or_False)</p>
4506 </div>
4507
4508
4509
4510
4511 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_always_mask"><code>set_always_mask</code></a> for all variables contained in
4512 this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all
4513 variables in all its subgroups.</p>
4514 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion of
4515 masked arrays with no missing values to regular numpy arrays shall be
4516 applied for all variables. Default True. Set to False to restore the default behaviour
4517 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
4518 otherwise masked array returned).</p>
4519 <p><strong><em>Note</em></strong>: Calling this function only affects existing
4520 variables. Variables created after calling this function will follow
4521 the default behaviour.</p></div>
4522 <div class="source_cont">
4523 </div>
4524
4525 </div>
4526
4527
4528 <div class="item">
4529 <div class="name def" id="netCDF4.Group.set_auto_chartostring">
4530 <p>def <span class="ident">set_auto_chartostring</span>(</p><p>self, True_or_False)</p>
4531 </div>
4532
4533
4534
4535
4536 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_chartostring"><code>set_auto_chartostring</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
4537 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
4538 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion of
4539 all character arrays &lt;--&gt; string arrays should be performed for
4540 character variables (variables of type <code>NC_CHAR</code> or <code>S1</code>) with the
4541 <code>_Encoding</code> attribute set.</p>
4542 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
4543 after calling this function will follow the default behaviour.</p></div>
4544 <div class="source_cont">
4545 </div>
4546
4547 </div>
4548
4549
4550 <div class="item">
4551 <div class="name def" id="netCDF4.Group.set_auto_mask">
4552 <p>def <span class="ident">set_auto_mask</span>(</p><p>self, True_or_False)</p>
4553 </div>
4554
4555
4556
4557
4558 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_mask"><code>set_auto_mask</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
4559 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
4560 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion to masked arrays
4561 shall be applied for all variables.</p>
4562 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
4563 after calling this function will follow the default behaviour.</p></div>
4564 <div class="source_cont">
4565 </div>
4566
4567 </div>
4568
4569
4570 <div class="item">
4571 <div class="name def" id="netCDF4.Group.set_auto_maskandscale">
4572 <p>def <span class="ident">set_auto_maskandscale</span>(</p><p>self, True_or_False)</p>
4573 </div>
4574
4575
4576
4577
4578 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_maskandscale"><code>set_auto_maskandscale</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
4579 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
4580 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion to masked arrays
4581 and variable scaling shall be applied for all variables.</p>
4582 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
4583 after calling this function will follow the default behaviour.</p></div>
4584 <div class="source_cont">
4585 </div>
4586
4587 </div>
4588
4589
4590 <div class="item">
4591 <div class="name def" id="netCDF4.Group.set_auto_scale">
4592 <p>def <span class="ident">set_auto_scale</span>(</p><p>self, True_or_False)</p>
4593 </div>
4594
4595
4596
4597
4598 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_scale"><code>set_auto_scale</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
4599 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
4600 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic variable scaling
4601 shall be applied for all variables.</p>
4602 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
4603 after calling this function will follow the default behaviour.</p></div>
4604 <div class="source_cont">
4605 </div>
4606
4607 </div>
4608
4609
4610 <div class="item">
4611 <div class="name def" id="netCDF4.Group.set_fill_off">
4612 <p>def <span class="ident">set_fill_off</span>(</p><p>self)</p>
4613 </div>
4614
4615
4616
4617
4618 <div class="desc"><p>Sets the fill mode for a <a href="#netCDF4.Dataset"><code>Dataset</code></a> open for writing to <code>off</code>.</p>
4619 <p>This will prevent the data from being pre-filled with fill values, which
4620 may result in some performance improvements. However, you must then make
4621 sure the data is actually written before being read.</p></div>
4622 <div class="source_cont">
4623 </div>
4624
4625 </div>
4626
4627
4628 <div class="item">
4629 <div class="name def" id="netCDF4.Group.set_fill_on">
4630 <p>def <span class="ident">set_fill_on</span>(</p><p>self)</p>
4631 </div>
4632
4633
4634
4635
4636 <div class="desc"><p>Sets the fill mode for a <a href="#netCDF4.Dataset"><code>Dataset</code></a> open for writing to <code>on</code>.</p>
4637 <p>This causes data to be pre-filled with fill values. The fill values can be
4638 controlled by the variable's <code>_Fill_Value</code> attribute, but is usually
4639 sufficient to the use the netCDF default <code>_Fill_Value</code> (defined
4640 separately for each variable type). The default behavior of the netCDF
4641 library corresponds to <code>set_fill_on</code>. Data which are equal to the
4642 <code>_Fill_Value</code> indicate that the variable was created, but never written
4643 to.</p></div>
4644 <div class="source_cont">
4645 </div>
4646
4647 </div>
4648
4649
4650 <div class="item">
4651 <div class="name def" id="netCDF4.Group.set_ncstring_attrs">
4652 <p>def <span class="ident">set_ncstring_attrs</span>(</p><p>self, True_or_False)</p>
4653 </div>
4654
4655
4656
4657
4658 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_ncstring_attrs"><code>set_ncstring_attrs</code></a> for all variables contained in
4659 this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all its
4660 subgroups and their variables.</p>
4661 <p><strong><code>True_or_False</code></strong>: Boolean determining if all string attributes are
4662 created as variable-length NC_STRINGs, (if True), or if ascii text
4663 attributes are stored as NC_CHARs (if False; default)</p>
4664 <p><strong><em>Note</em></strong>: Calling this function only affects newly created attributes
4665 of existing (sub-) groups and their variables.</p></div>
4666 <div class="source_cont">
4667 </div>
4668
4669 </div>
4670
4671
4672 <div class="item">
4673 <div class="name def" id="netCDF4.Group.setncattr">
4674 <p>def <span class="ident">setncattr</span>(</p><p>self,name,value)</p>
4675 </div>
4676
4677
4678
4679
4680 <div class="desc"><p>set a netCDF dataset or group attribute using name,value pair.
4681 Use if you need to set a netCDF attribute with the
4682 with the same name as one of the reserved python attributes.</p></div>
4683 <div class="source_cont">
4684 </div>
4685
4686 </div>
4687
4688
4689 <div class="item">
4690 <div class="name def" id="netCDF4.Group.setncattr_string">
4691 <p>def <span class="ident">setncattr_string</span>(</p><p>self,name,value)</p>
4692 </div>
4693
4694
4695
4696
4697 <div class="desc"><p>set a netCDF dataset or group string attribute using name,value pair.
4698 Use if you need to ensure that a netCDF attribute is created with type
4699 <code>NC_STRING</code> if the file format is <code>NETCDF4</code>.</p></div>
4700 <div class="source_cont">
4701 </div>
4702
4703 </div>
4704
4705
4706 <div class="item">
4707 <div class="name def" id="netCDF4.Group.setncatts">
4708 <p>def <span class="ident">setncatts</span>(</p><p>self,attdict)</p>
4709 </div>
4710
4711
4712
4713
4714 <div class="desc"><p>set a bunch of netCDF dataset or group attributes at once using a python dictionary.
4715 This may be faster when setting a lot of attributes for a <code>NETCDF3</code>
4716 formatted file, since nc_redef/nc_enddef is not called in between setting
4717 each attribute</p></div>
4718 <div class="source_cont">
4719 </div>
4720
4721 </div>
4722
4723
4724 <div class="item">
4725 <div class="name def" id="netCDF4.Group.sync">
4726 <p>def <span class="ident">sync</span>(</p><p>self)</p>
4727 </div>
4728
4729
4730
4731
4732 <div class="desc"><p>Writes all buffered data in the <a href="#netCDF4.Dataset"><code>Dataset</code></a> to the disk file.</p></div>
4733 <div class="source_cont">
4734 </div>
4735
4736 </div>
4737
4738 </div>
4739 </div>
4740
4741 <div class="item">
4742 <p id="netCDF4.MFDataset" class="name">class <span class="ident">MFDataset</span></p>
4743
4744
4745 <div class="desc"><p>Class for reading multi-file netCDF Datasets, making variables
4746 spanning multiple files appear as if they were in one file.
4747 Datasets must be in <code>NETCDF4_CLASSIC, NETCDF3_CLASSIC, NETCDF3_64BIT_OFFSET
4748 or NETCDF3_64BIT_DATA</code> format (<code>NETCDF4</code> Datasets won't work).</p>
4749 <p>Adapted from <a href="http://pysclint.sourceforge.net/pycdf">pycdf</a> by Andre Gosselin.</p>
4750 <p>Example usage (See <a href="#netCDF4.MFDataset.__init__"><code>__init__</code></a> for more details):</p>
4751 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
4752 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># create a series of netCDF files with a variable sharing</span>
4753 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># the same unlimited dimension.</span>
4754 <span class="o">&gt;&gt;&gt;</span> <span class="k">for</span> <span class="n">nf</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
4755 <span class="o">...</span> <span class="k">with</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;mftest</span><span class="si">%s</span><span class="s2">.nc&quot;</span> <span class="o">%</span> <span class="n">nf</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;NETCDF4_CLASSIC&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
4756 <span class="o">...</span> <span class="n">f</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
4757 <span class="o">...</span> <span class="n">x</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;x&quot;</span><span class="p">,</span><span class="s2">&quot;i&quot;</span><span class="p">,(</span><span class="s2">&quot;x&quot;</span><span class="p">,))</span>
4758 <span class="o">...</span> <span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">]</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">nf</span><span class="o">*</span><span class="mi">10</span><span class="p">,</span><span class="mi">10</span><span class="o">*</span><span class="p">(</span><span class="n">nf</span><span class="o">+</span><span class="mi">1</span><span class="p">))</span>
4759 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># now read all those files in at once, in one Dataset.</span>
4760 <span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">MFDataset</span><span class="p">(</span><span class="s2">&quot;mftest*nc&quot;</span><span class="p">)</span>
4761 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;x&quot;</span><span class="p">][:])</span>
4762 <span class="p">[</span> <span class="mi">0</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span> <span class="mi">5</span> <span class="mi">6</span> <span class="mi">7</span> <span class="mi">8</span> <span class="mi">9</span> <span class="mi">10</span> <span class="mi">11</span> <span class="mi">12</span> <span class="mi">13</span> <span class="mi">14</span> <span class="mi">15</span> <span class="mi">16</span> <span class="mi">17</span> <span class="mi">18</span> <span class="mi">19</span> <span class="mi">20</span> <span class="mi">21</span> <span class="mi">22</span> <span class="mi">23</span>
4763 <span class="mi">24</span> <span class="mi">25</span> <span class="mi">26</span> <span class="mi">27</span> <span class="mi">28</span> <span class="mi">29</span> <span class="mi">30</span> <span class="mi">31</span> <span class="mi">32</span> <span class="mi">33</span> <span class="mi">34</span> <span class="mi">35</span> <span class="mi">36</span> <span class="mi">37</span> <span class="mi">38</span> <span class="mi">39</span> <span class="mi">40</span> <span class="mi">41</span> <span class="mi">42</span> <span class="mi">43</span> <span class="mi">44</span> <span class="mi">45</span> <span class="mi">46</span> <span class="mi">47</span>
4764 <span class="mi">48</span> <span class="mi">49</span> <span class="mi">50</span> <span class="mi">51</span> <span class="mi">52</span> <span class="mi">53</span> <span class="mi">54</span> <span class="mi">55</span> <span class="mi">56</span> <span class="mi">57</span> <span class="mi">58</span> <span class="mi">59</span> <span class="mi">60</span> <span class="mi">61</span> <span class="mi">62</span> <span class="mi">63</span> <span class="mi">64</span> <span class="mi">65</span> <span class="mi">66</span> <span class="mi">67</span> <span class="mi">68</span> <span class="mi">69</span> <span class="mi">70</span> <span class="mi">71</span>
4765 <span class="mi">72</span> <span class="mi">73</span> <span class="mi">74</span> <span class="mi">75</span> <span class="mi">76</span> <span class="mi">77</span> <span class="mi">78</span> <span class="mi">79</span> <span class="mi">80</span> <span class="mi">81</span> <span class="mi">82</span> <span class="mi">83</span> <span class="mi">84</span> <span class="mi">85</span> <span class="mi">86</span> <span class="mi">87</span> <span class="mi">88</span> <span class="mi">89</span> <span class="mi">90</span> <span class="mi">91</span> <span class="mi">92</span> <span class="mi">93</span> <span class="mi">94</span> <span class="mi">95</span>
4766 <span class="mi">96</span> <span class="mi">97</span> <span class="mi">98</span> <span class="mi">99</span><span class="p">]</span>
4767 </code></pre></div></div>
4768 <div class="source_cont">
4769 </div>
4770
4771
4772 <div class="class">
4773 <h3>Ancestors (in MRO)</h3>
4774 <ul class="class_list">
4775 <li><a href="#netCDF4.MFDataset">MFDataset</a></li>
4776 <li><a href="#netCDF4.Dataset">Dataset</a></li>
4777 <li>builtins.object</li>
4778 </ul>
4779 <h3>Class variables</h3>
4780 <div class="item">
4781 <p id="netCDF4.MFDataset.cmptypes" class="name">var <span class="ident">cmptypes</span></p>
4782
4783
4784
4785
4786 <div class="source_cont">
4787 </div>
4788
4789 </div>
4790 <div class="item">
4791 <p id="netCDF4.MFDataset.data_model" class="name">var <span class="ident">data_model</span></p>
4792
4793
4794
4795
4796 <div class="source_cont">
4797 </div>
4798
4799 </div>
4800 <div class="item">
4801 <p id="netCDF4.MFDataset.dimensions" class="name">var <span class="ident">dimensions</span></p>
4802
4803
4804
4805
4806 <div class="source_cont">
4807 </div>
4808
4809 </div>
4810 <div class="item">
4811 <p id="netCDF4.MFDataset.disk_format" class="name">var <span class="ident">disk_format</span></p>
4812
4813
4814
4815
4816 <div class="source_cont">
4817 </div>
4818
4819 </div>
4820 <div class="item">
4821 <p id="netCDF4.MFDataset.enumtypes" class="name">var <span class="ident">enumtypes</span></p>
4822
4823
4824
4825
4826 <div class="source_cont">
4827 </div>
4828
4829 </div>
4830 <div class="item">
4831 <p id="netCDF4.MFDataset.file_format" class="name">var <span class="ident">file_format</span></p>
4832
4833
4834
4835
4836 <div class="source_cont">
4837 </div>
4838
4839 </div>
4840 <div class="item">
4841 <p id="netCDF4.MFDataset.groups" class="name">var <span class="ident">groups</span></p>
4842
4843
4844
4845
4846 <div class="source_cont">
4847 </div>
4848
4849 </div>
4850 <div class="item">
4851 <p id="netCDF4.MFDataset.keepweakref" class="name">var <span class="ident">keepweakref</span></p>
4852
4853
4854
4855
4856 <div class="source_cont">
4857 </div>
4858
4859 </div>
4860 <div class="item">
4861 <p id="netCDF4.MFDataset.name" class="name">var <span class="ident">name</span></p>
4862
4863
4864
4865
4866 <div class="source_cont">
4867 </div>
4868
4869 </div>
4870 <div class="item">
4871 <p id="netCDF4.MFDataset.parent" class="name">var <span class="ident">parent</span></p>
4872
4873
4874
4875
4876 <div class="source_cont">
4877 </div>
4878
4879 </div>
4880 <div class="item">
4881 <p id="netCDF4.MFDataset.path" class="name">var <span class="ident">path</span></p>
4882
4883
4884
4885
4886 <div class="source_cont">
4887 </div>
4888
4889 </div>
4890 <div class="item">
4891 <p id="netCDF4.MFDataset.variables" class="name">var <span class="ident">variables</span></p>
4892
4893
4894
4895
4896 <div class="source_cont">
4897 </div>
4898
4899 </div>
4900 <div class="item">
4901 <p id="netCDF4.MFDataset.vltypes" class="name">var <span class="ident">vltypes</span></p>
4902
4903
4904
4905
4906 <div class="source_cont">
4907 </div>
4908
4909 </div>
4910 <h3>Static methods</h3>
4911
4912 <div class="item">
4913 <div class="name def" id="netCDF4.MFDataset.__init__">
4914 <p>def <span class="ident">__init__</span>(</p><p>self, files, check=False, aggdim=None, exclude=[], master_file=None)</p>
4915 </div>
4916
4917 <p class="inheritance">
4918 <strong>Inheritance:</strong>
4919 <code><a href="#netCDF4.Dataset">Dataset</a></code>.<code><a href="#netCDF4.Dataset.__init__">__init__</a></code>
4920 </p>
4921
4922
4923
4924 <div class="desc"><p><strong><code>__init__(self, files, check=False, aggdim=None, exclude=[],
4925 master_file=None)</code></strong></p>
4926 <p>Open a Dataset spanning multiple files, making it look as if it was a
4927 single file. Variables in the list of files that share the same
4928 dimension (specified with the keyword <code>aggdim</code>) are aggregated. If
4929 <code>aggdim</code> is not specified, the unlimited is aggregated. Currently,
4930 <code>aggdim</code> must be the leftmost (slowest varying) dimension of each
4931 of the variables to be aggregated.</p>
4932 <p><strong><code>files</code></strong>: either a sequence of netCDF files or a string with a
4933 wildcard (converted to a sorted list of files using glob) If
4934 the <code>master_file</code> kwarg is not specified, the first file
4935 in the list will become the "master" file, defining all the
4936 variables with an aggregation dimension which may span
4937 subsequent files. Attribute access returns attributes only from "master"
4938 file. The files are always opened in read-only mode.</p>
4939 <p><strong><code>check</code></strong>: True if you want to do consistency checking to ensure the
4940 correct variables structure for all of the netcdf files. Checking makes
4941 the initialization of the MFDataset instance much slower. Default is
4942 False.</p>
4943 <p><strong><code>aggdim</code></strong>: The name of the dimension to aggregate over (must
4944 be the leftmost dimension of each of the variables to be aggregated).
4945 If None (default), aggregate over the unlimited dimension.</p>
4946 <p><strong><code>exclude</code></strong>: A list of variable names to exclude from aggregation.
4947 Default is an empty list.</p>
4948 <p><strong><code>master_file</code></strong>: file to use as "master file", defining all the
4949 variables with an aggregation dimension and all global attributes.</p></div>
4950 <div class="source_cont">
4951 </div>
4952
4953 </div>
4954
4955
4956 <div class="item">
4957 <div class="name def" id="netCDF4.MFDataset.close">
4958 <p>def <span class="ident">close</span>(</p><p>self)</p>
4959 </div>
4960
4961
4962
4963
4964 <div class="desc"><p><strong><code>close(self)</code></strong></p>
4965 <p>close all the open files.</p></div>
4966 <div class="source_cont">
4967 </div>
4968
4969 </div>
4970
4971
4972 <div class="item">
4973 <div class="name def" id="netCDF4.MFDataset.createCompoundType">
4974 <p>def <span class="ident">createCompoundType</span>(</p><p>self, datatype, datatype_name)</p>
4975 </div>
4976
4977
4978
4979
4980 <div class="desc"><p>Creates a new compound data type named <code>datatype_name</code> from the numpy
4981 dtype object <code>datatype</code>.</p>
4982 <p><strong><em>Note</em></strong>: If the new compound data type contains other compound data types
4983 (i.e. it is a 'nested' compound type, where not all of the elements
4984 are homogeneous numeric data types), then the 'inner' compound types <strong>must</strong> be
4985 created first.</p>
4986 <p>The return value is the <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> class instance describing the new
4987 datatype.</p></div>
4988 <div class="source_cont">
4989 </div>
4990
4991 </div>
4992
4993
4994 <div class="item">
4995 <div class="name def" id="netCDF4.MFDataset.createDimension">
4996 <p>def <span class="ident">createDimension</span>(</p><p>self, dimname, size=None)</p>
4997 </div>
4998
4999
5000
5001
5002 <div class="desc"><p>Creates a new dimension with the given <code>dimname</code> and <code>size</code>.</p>
5003 <p><code>size</code> must be a positive integer or <code>None</code>, which stands for
5004 "unlimited" (default is <code>None</code>). Specifying a size of 0 also
5005 results in an unlimited dimension. The return value is the <a href="#netCDF4.Dimension"><code>Dimension</code></a>
5006 class instance describing the new dimension. To determine the current
5007 maximum size of the dimension, use the <code>len</code> function on the <a href="#netCDF4.Dimension"><code>Dimension</code></a>
5008 instance. To determine if a dimension is 'unlimited', use the
5009 <a href="#netCDF4.Dimension.isunlimited"><code>isunlimited</code></a> method of the <a href="#netCDF4.Dimension"><code>Dimension</code></a> instance.</p></div>
5010 <div class="source_cont">
5011 </div>
5012
5013 </div>
5014
5015
5016 <div class="item">
5017 <div class="name def" id="netCDF4.MFDataset.createEnumType">
5018 <p>def <span class="ident">createEnumType</span>(</p><p>self, datatype, datatype_name, enum_dict)</p>
5019 </div>
5020
5021
5022
5023
5024 <div class="desc"><p>Creates a new Enum data type named <code>datatype_name</code> from a numpy
5025 integer dtype object <code>datatype</code>, and a python dictionary
5026 defining the enum fields and values.</p>
5027 <p>The return value is the <a href="#netCDF4.EnumType"><code>EnumType</code></a> class instance describing the new
5028 datatype.</p></div>
5029 <div class="source_cont">
5030 </div>
5031
5032 </div>
5033
5034
5035 <div class="item">
5036 <div class="name def" id="netCDF4.MFDataset.createGroup">
5037 <p>def <span class="ident">createGroup</span>(</p><p>self, groupname)</p>
5038 </div>
5039
5040
5041
5042
5043 <div class="desc"><p>Creates a new <a href="#netCDF4.Group"><code>Group</code></a> with the given <code>groupname</code>.</p>
5044 <p>If <code>groupname</code> is specified as a path, using forward slashes as in unix to
5045 separate components, then intermediate groups will be created as necessary
5046 (analogous to <code>mkdir -p</code> in unix). For example,
5047 <code>createGroup('/GroupA/GroupB/GroupC')</code> will create <code>GroupA</code>,
5048 <code>GroupA/GroupB</code>, and <code>GroupA/GroupB/GroupC</code>, if they don't already exist.
5049 If the specified path describes a group that already exists, no error is
5050 raised.</p>
5051 <p>The return value is a <a href="#netCDF4.Group"><code>Group</code></a> class instance.</p></div>
5052 <div class="source_cont">
5053 </div>
5054
5055 </div>
5056
5057
5058 <div class="item">
5059 <div class="name def" id="netCDF4.MFDataset.createVLType">
5060 <p>def <span class="ident">createVLType</span>(</p><p>self, datatype, datatype_name)</p>
5061 </div>
5062
5063
5064
5065
5066 <div class="desc"><p>Creates a new VLEN data type named <code>datatype_name</code> from a numpy
5067 dtype object <code>datatype</code>.</p>
5068 <p>The return value is the <a href="#netCDF4.VLType"><code>VLType</code></a> class instance describing the new
5069 datatype.</p></div>
5070 <div class="source_cont">
5071 </div>
5072
5073 </div>
5074
5075
5076 <div class="item">
5077 <div class="name def" id="netCDF4.MFDataset.createVariable">
5078 <p>def <span class="ident">createVariable</span>(</p><p>self, varname, datatype, dimensions=(), zlib=False, complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None, endian=&#39;native&#39;, least_significant_digit=None, fill_value=None, chunk_cache=None)</p>
5079 </div>
5080
5081
5082
5083
5084 <div class="desc"><p>Creates a new variable with the given <code>varname</code>, <code>datatype</code>, and
5085 <code>dimensions</code>. If dimensions are not given, the variable is assumed to be
5086 a scalar.</p>
5087 <p>If <code>varname</code> is specified as a path, using forward slashes as in unix to
5088 separate components, then intermediate groups will be created as necessary
5089 For example, <code>createVariable('/GroupA/GroupB/VarC', float, ('x','y'))</code> will create groups <code>GroupA</code>
5090 and <code>GroupA/GroupB</code>, plus the variable <code>GroupA/GroupB/VarC</code>, if the preceding
5091 groups don't already exist.</p>
5092 <p>The <code>datatype</code> can be a numpy datatype object, or a string that describes
5093 a numpy dtype object (like the <code>dtype.str</code> attribute of a numpy array).
5094 Supported specifiers include: <code>'S1' or 'c' (NC_CHAR), 'i1' or 'b' or 'B'
5095 (NC_BYTE), 'u1' (NC_UBYTE), 'i2' or 'h' or 's' (NC_SHORT), 'u2'
5096 (NC_USHORT), 'i4' or 'i' or 'l' (NC_INT), 'u4' (NC_UINT), 'i8' (NC_INT64),
5097 'u8' (NC_UINT64), 'f4' or 'f' (NC_FLOAT), 'f8' or 'd' (NC_DOUBLE)</code>.
5098 <code>datatype</code> can also be a <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> instance
5099 (for a structured, or compound array), a <a href="#netCDF4.VLType"><code>VLType</code></a> instance
5100 (for a variable-length array), or the python <code>str</code> builtin
5101 (for a variable-length string array). Numpy string and unicode datatypes with
5102 length greater than one are aliases for <code>str</code>.</p>
5103 <p>Data from netCDF variables is presented to python as numpy arrays with
5104 the corresponding data type.</p>
5105 <p><code>dimensions</code> must be a tuple containing dimension names (strings) that
5106 have been defined previously using <a href="#netCDF4.Dataset.createDimension"><code>createDimension</code></a>. The default value
5107 is an empty tuple, which means the variable is a scalar.</p>
5108 <p>If the optional keyword <code>zlib</code> is <code>True</code>, the data will be compressed in
5109 the netCDF file using gzip compression (default <code>False</code>).</p>
5110 <p>The optional keyword <code>complevel</code> is an integer between 1 and 9 describing
5111 the level of compression desired (default 4). Ignored if <code>zlib=False</code>.</p>
5112 <p>If the optional keyword <code>shuffle</code> is <code>True</code>, the HDF5 shuffle filter
5113 will be applied before compressing the data (default <code>True</code>). This
5114 significantly improves compression. Default is <code>True</code>. Ignored if
5115 <code>zlib=False</code>.</p>
5116 <p>If the optional keyword <code>fletcher32</code> is <code>True</code>, the Fletcher32 HDF5
5117 checksum algorithm is activated to detect errors. Default <code>False</code>.</p>
5118 <p>If the optional keyword <code>contiguous</code> is <code>True</code>, the variable data is
5119 stored contiguously on disk. Default <code>False</code>. Setting to <code>True</code> for
5120 a variable with an unlimited dimension will trigger an error.</p>
5121 <p>The optional keyword <code>chunksizes</code> can be used to manually specify the
5122 HDF5 chunksizes for each dimension of the variable. A detailed
5123 discussion of HDF chunking and I/O performance is available
5124 <a href="http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html">here</a>.
5125 Basically, you want the chunk size for each dimension to match as
5126 closely as possible the size of the data block that users will read
5127 from the file. <code>chunksizes</code> cannot be set if <code>contiguous=True</code>.</p>
5128 <p>The optional keyword <code>endian</code> can be used to control whether the
5129 data is stored in little or big endian format on disk. Possible
5130 values are <code>little, big</code> or <code>native</code> (default). The library
5131 will automatically handle endian conversions when the data is read,
5132 but if the data is always going to be read on a computer with the
5133 opposite format as the one used to create the file, there may be
5134 some performance advantage to be gained by setting the endian-ness.</p>
5135 <p>The <code>zlib, complevel, shuffle, fletcher32, contiguous, chunksizes</code> and <code>endian</code>
5136 keywords are silently ignored for netCDF 3 files that do not use HDF5.</p>
5137 <p>The optional keyword <code>fill_value</code> can be used to override the default
5138 netCDF <code>_FillValue</code> (the value that the variable gets filled with before
5139 any data is written to it, defaults given in <code>netCDF4.default_fillvals</code>).
5140 If fill_value is set to <code>False</code>, then the variable is not pre-filled.</p>
5141 <p>If the optional keyword parameter <code>least_significant_digit</code> is
5142 specified, variable data will be truncated (quantized). In conjunction
5143 with <code>zlib=True</code> this produces 'lossy', but significantly more
5144 efficient compression. For example, if <code>least_significant_digit=1</code>,
5145 data will be quantized using <code>numpy.around(scale*data)/scale</code>, where
5146 scale = 2**bits, and bits is determined so that a precision of 0.1 is
5147 retained (in this case bits=4). From the
5148 <a href="http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml">PSD metadata conventions</a>:
5149 "least_significant_digit -- power of ten of the smallest decimal place
5150 in unpacked data that is a reliable value." Default is <code>None</code>, or no
5151 quantization, or 'lossless' compression.</p>
5152 <p>When creating variables in a <code>NETCDF4</code> or <code>NETCDF4_CLASSIC</code> formatted file,
5153 HDF5 creates something called a 'chunk cache' for each variable. The
5154 default size of the chunk cache may be large enough to completely fill
5155 available memory when creating thousands of variables. The optional
5156 keyword <code>chunk_cache</code> allows you to reduce (or increase) the size of
5157 the default chunk cache when creating a variable. The setting only
5158 persists as long as the Dataset is open - you can use the set_var_chunk_cache
5159 method to change it the next time the Dataset is opened.
5160 Warning - messing with this parameter can seriously degrade performance.</p>
5161 <p>The return value is the <a href="#netCDF4.Variable"><code>Variable</code></a> class instance describing the new
5162 variable.</p>
5163 <p>A list of names corresponding to netCDF variable attributes can be
5164 obtained with the <a href="#netCDF4.Variable"><code>Variable</code></a> method <a href="#netCDF4.Variable.ncattrs"><code>ncattrs</code></a>. A dictionary
5165 containing all the netCDF attribute name/value pairs is provided by
5166 the <code>__dict__</code> attribute of a <a href="#netCDF4.Variable"><code>Variable</code></a> instance.</p>
5167 <p><a href="#netCDF4.Variable"><code>Variable</code></a> instances behave much like array objects. Data can be
5168 assigned to or retrieved from a variable with indexing and slicing
5169 operations on the <a href="#netCDF4.Variable"><code>Variable</code></a> instance. A <a href="#netCDF4.Variable"><code>Variable</code></a> instance has six
5170 Dataset standard attributes: <code>dimensions, dtype, shape, ndim, name</code> and
5171 <code>least_significant_digit</code>. Application programs should never modify
5172 these attributes. The <code>dimensions</code> attribute is a tuple containing the
5173 names of the dimensions associated with this variable. The <code>dtype</code>
5174 attribute is a string describing the variable's data type (<code>i4, f8,
5175 S1,</code> etc). The <code>shape</code> attribute is a tuple describing the current
5176 sizes of all the variable's dimensions. The <code>name</code> attribute is a
5177 string containing the name of the Variable instance.
5178 The <code>least_significant_digit</code>
5179 attributes describes the power of ten of the smallest decimal place in
5180 the data the contains a reliable value. assigned to the <a href="#netCDF4.Variable"><code>Variable</code></a>
5181 instance. If <code>None</code>, the data is not truncated. The <code>ndim</code> attribute
5182 is the number of variable dimensions.</p></div>
5183 <div class="source_cont">
5184 </div>
5185
5186 </div>
5187
5188
5189 <div class="item">
5190 <div class="name def" id="netCDF4.MFDataset.delncattr">
5191 <p>def <span class="ident">delncattr</span>(</p><p>self,name,value)</p>
5192 </div>
5193
5194
5195
5196
5197 <div class="desc"><p>delete a netCDF dataset or group attribute. Use if you need to delete a
5198 netCDF attribute with the same name as one of the reserved python
5199 attributes.</p></div>
5200 <div class="source_cont">
5201 </div>
5202
5203 </div>
5204
5205
5206 <div class="item">
5207 <div class="name def" id="netCDF4.MFDataset.filepath">
5208 <p>def <span class="ident">filepath</span>(</p><p>self,encoding=None)</p>
5209 </div>
5210
5211
5212
5213
5214 <div class="desc"><p>Get the file system path (or the opendap URL) which was used to
5215 open/create the Dataset. Requires netcdf &gt;= 4.1.2. The path
5216 is decoded into a string using <code>sys.getfilesystemencoding()</code> by default, this can be
5217 changed using the <code>encoding</code> kwarg.</p></div>
5218 <div class="source_cont">
5219 </div>
5220
5221 </div>
5222
5223
5224 <div class="item">
5225 <div class="name def" id="netCDF4.MFDataset.get_variables_by_attributes">
5226 <p>def <span class="ident">get_variables_by_attributes</span>(</p><p>...)</p>
5227 </div>
5228
5229
5230
5231
5232 <div class="desc"><p>Returns a list of variables that match specific conditions.</p>
5233 <p>Can pass in key=value parameters and variables are returned that
5234 contain all of the matches. For example,</p>
5235 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables with x-axis attribute.</span>
5236 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="s1">&#39;X&#39;</span><span class="p">)</span>
5237 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables with matching &quot;standard_name&quot; attribute</span>
5238 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">standard_name</span><span class="o">=</span><span class="s1">&#39;northward_sea_water_velocity&#39;</span><span class="p">)</span>
5239 </code></pre></div>
5240
5241
5242 <p>Can pass in key=callable parameter and variables are returned if the
5243 callable returns True. The callable should accept a single parameter,
5244 the attribute value. None is given as the attribute value when the
5245 attribute does not exist on the variable. For example,</p>
5246 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get Axis variables</span>
5247 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">&#39;X&#39;</span><span class="p">,</span> <span class="s1">&#39;Y&#39;</span><span class="p">,</span> <span class="s1">&#39;Z&#39;</span><span class="p">,</span> <span class="s1">&#39;T&#39;</span><span class="p">])</span>
5248 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables that don&#39;t have an &quot;axis&quot; attribute</span>
5249 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">axis</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">)</span>
5250 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Get variables that have a &quot;grid_mapping&quot; attribute</span>
5251 <span class="o">&gt;&gt;&gt;</span> <span class="n">vs</span> <span class="o">=</span> <span class="n">nc</span><span class="o">.</span><span class="n">get_variables_by_attributes</span><span class="p">(</span><span class="n">grid_mapping</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">)</span>
5252 </code></pre></div></div>
5253 <div class="source_cont">
5254 </div>
5255
5256 </div>
5257
5258
5259 <div class="item">
5260 <div class="name def" id="netCDF4.MFDataset.getncattr">
5261 <p>def <span class="ident">getncattr</span>(</p><p>self,name)</p>
5262 </div>
5263
5264
5265
5266
5267 <div class="desc"><p>retrieve a netCDF dataset or group attribute.
5268 Use if you need to get a netCDF attribute with the same
5269 name as one of the reserved python attributes.</p>
5270 <p>option kwarg <code>encoding</code> can be used to specify the
5271 character encoding of a string attribute (default is <code>utf-8</code>).</p></div>
5272 <div class="source_cont">
5273 </div>
5274
5275 </div>
5276
5277
5278 <div class="item">
5279 <div class="name def" id="netCDF4.MFDataset.isopen">
5280 <p>def <span class="ident">isopen</span>(</p><p>...)</p>
5281 </div>
5282
5283
5284
5285
5286 <div class="desc"><p>is the Dataset open or closed?</p></div>
5287 <div class="source_cont">
5288 </div>
5289
5290 </div>
5291
5292
5293 <div class="item">
5294 <div class="name def" id="netCDF4.MFDataset.ncattrs">
5295 <p>def <span class="ident">ncattrs</span>(</p><p>self)</p>
5296 </div>
5297
5298
5299
5300
5301 <div class="desc"><p><strong><code>ncattrs(self)</code></strong></p>
5302 <p>return the netcdf attribute names from the master file.</p></div>
5303 <div class="source_cont">
5304 </div>
5305
5306 </div>
5307
5308
5309 <div class="item">
5310 <div class="name def" id="netCDF4.MFDataset.renameAttribute">
5311 <p>def <span class="ident">renameAttribute</span>(</p><p>self, oldname, newname)</p>
5312 </div>
5313
5314
5315
5316
5317 <div class="desc"><p>rename a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> attribute named <code>oldname</code> to <code>newname</code>.</p></div>
5318 <div class="source_cont">
5319 </div>
5320
5321 </div>
5322
5323
5324 <div class="item">
5325 <div class="name def" id="netCDF4.MFDataset.renameDimension">
5326 <p>def <span class="ident">renameDimension</span>(</p><p>self, oldname, newname)</p>
5327 </div>
5328
5329
5330
5331
5332 <div class="desc"><p>rename a <a href="#netCDF4.Dimension"><code>Dimension</code></a> named <code>oldname</code> to <code>newname</code>.</p></div>
5333 <div class="source_cont">
5334 </div>
5335
5336 </div>
5337
5338
5339 <div class="item">
5340 <div class="name def" id="netCDF4.MFDataset.renameGroup">
5341 <p>def <span class="ident">renameGroup</span>(</p><p>self, oldname, newname)</p>
5342 </div>
5343
5344
5345
5346
5347 <div class="desc"><p>rename a <a href="#netCDF4.Group"><code>Group</code></a> named <code>oldname</code> to <code>newname</code> (requires netcdf &gt;= 4.3.1).</p></div>
5348 <div class="source_cont">
5349 </div>
5350
5351 </div>
5352
5353
5354 <div class="item">
5355 <div class="name def" id="netCDF4.MFDataset.renameVariable">
5356 <p>def <span class="ident">renameVariable</span>(</p><p>self, oldname, newname)</p>
5357 </div>
5358
5359
5360
5361
5362 <div class="desc"><p>rename a <a href="#netCDF4.Variable"><code>Variable</code></a> named <code>oldname</code> to <code>newname</code></p></div>
5363 <div class="source_cont">
5364 </div>
5365
5366 </div>
5367
5368
5369 <div class="item">
5370 <div class="name def" id="netCDF4.MFDataset.set_always_mask">
5371 <p>def <span class="ident">set_always_mask</span>(</p><p>self, True_or_False)</p>
5372 </div>
5373
5374
5375
5376
5377 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_always_mask"><code>set_always_mask</code></a> for all variables contained in
5378 this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all
5379 variables in all its subgroups.</p>
5380 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion of
5381 masked arrays with no missing values to regular numpy arrays shall be
5382 applied for all variables. Default True. Set to False to restore the default behaviour
5383 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
5384 otherwise masked array returned).</p>
5385 <p><strong><em>Note</em></strong>: Calling this function only affects existing
5386 variables. Variables created after calling this function will follow
5387 the default behaviour.</p></div>
5388 <div class="source_cont">
5389 </div>
5390
5391 </div>
5392
5393
5394 <div class="item">
5395 <div class="name def" id="netCDF4.MFDataset.set_auto_chartostring">
5396 <p>def <span class="ident">set_auto_chartostring</span>(</p><p>self, True_or_False)</p>
5397 </div>
5398
5399
5400
5401
5402 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_chartostring"><code>set_auto_chartostring</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
5403 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
5404 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion of
5405 all character arrays &lt;--&gt; string arrays should be performed for
5406 character variables (variables of type <code>NC_CHAR</code> or <code>S1</code>) with the
5407 <code>_Encoding</code> attribute set.</p>
5408 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
5409 after calling this function will follow the default behaviour.</p></div>
5410 <div class="source_cont">
5411 </div>
5412
5413 </div>
5414
5415
5416 <div class="item">
5417 <div class="name def" id="netCDF4.MFDataset.set_auto_mask">
5418 <p>def <span class="ident">set_auto_mask</span>(</p><p>self, True_or_False)</p>
5419 </div>
5420
5421
5422
5423
5424 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_mask"><code>set_auto_mask</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
5425 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
5426 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion to masked arrays
5427 shall be applied for all variables.</p>
5428 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
5429 after calling this function will follow the default behaviour.</p></div>
5430 <div class="source_cont">
5431 </div>
5432
5433 </div>
5434
5435
5436 <div class="item">
5437 <div class="name def" id="netCDF4.MFDataset.set_auto_maskandscale">
5438 <p>def <span class="ident">set_auto_maskandscale</span>(</p><p>self, True_or_False)</p>
5439 </div>
5440
5441
5442
5443
5444 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_maskandscale"><code>set_auto_maskandscale</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
5445 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
5446 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic conversion to masked arrays
5447 and variable scaling shall be applied for all variables.</p>
5448 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
5449 after calling this function will follow the default behaviour.</p></div>
5450 <div class="source_cont">
5451 </div>
5452
5453 </div>
5454
5455
5456 <div class="item">
5457 <div class="name def" id="netCDF4.MFDataset.set_auto_scale">
5458 <p>def <span class="ident">set_auto_scale</span>(</p><p>self, True_or_False)</p>
5459 </div>
5460
5461
5462
5463
5464 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_auto_scale"><code>set_auto_scale</code></a> for all variables contained in this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
5465 <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all variables in all its subgroups.</p>
5466 <p><strong><code>True_or_False</code></strong>: Boolean determining if automatic variable scaling
5467 shall be applied for all variables.</p>
5468 <p><strong><em>Note</em></strong>: Calling this function only affects existing variables. Variables created
5469 after calling this function will follow the default behaviour.</p></div>
5470 <div class="source_cont">
5471 </div>
5472
5473 </div>
5474
5475
5476 <div class="item">
5477 <div class="name def" id="netCDF4.MFDataset.set_fill_off">
5478 <p>def <span class="ident">set_fill_off</span>(</p><p>self)</p>
5479 </div>
5480
5481
5482
5483
5484 <div class="desc"><p>Sets the fill mode for a <a href="#netCDF4.Dataset"><code>Dataset</code></a> open for writing to <code>off</code>.</p>
5485 <p>This will prevent the data from being pre-filled with fill values, which
5486 may result in some performance improvements. However, you must then make
5487 sure the data is actually written before being read.</p></div>
5488 <div class="source_cont">
5489 </div>
5490
5491 </div>
5492
5493
5494 <div class="item">
5495 <div class="name def" id="netCDF4.MFDataset.set_fill_on">
5496 <p>def <span class="ident">set_fill_on</span>(</p><p>self)</p>
5497 </div>
5498
5499
5500
5501
5502 <div class="desc"><p>Sets the fill mode for a <a href="#netCDF4.Dataset"><code>Dataset</code></a> open for writing to <code>on</code>.</p>
5503 <p>This causes data to be pre-filled with fill values. The fill values can be
5504 controlled by the variable's <code>_Fill_Value</code> attribute, but is usually
5505 sufficient to the use the netCDF default <code>_Fill_Value</code> (defined
5506 separately for each variable type). The default behavior of the netCDF
5507 library corresponds to <code>set_fill_on</code>. Data which are equal to the
5508 <code>_Fill_Value</code> indicate that the variable was created, but never written
5509 to.</p></div>
5510 <div class="source_cont">
5511 </div>
5512
5513 </div>
5514
5515
5516 <div class="item">
5517 <div class="name def" id="netCDF4.MFDataset.set_ncstring_attrs">
5518 <p>def <span class="ident">set_ncstring_attrs</span>(</p><p>self, True_or_False)</p>
5519 </div>
5520
5521
5522
5523
5524 <div class="desc"><p>Call <a href="#netCDF4.Variable.set_ncstring_attrs"><code>set_ncstring_attrs</code></a> for all variables contained in
5525 this <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a>, as well as for all its
5526 subgroups and their variables.</p>
5527 <p><strong><code>True_or_False</code></strong>: Boolean determining if all string attributes are
5528 created as variable-length NC_STRINGs, (if True), or if ascii text
5529 attributes are stored as NC_CHARs (if False; default)</p>
5530 <p><strong><em>Note</em></strong>: Calling this function only affects newly created attributes
5531 of existing (sub-) groups and their variables.</p></div>
5532 <div class="source_cont">
5533 </div>
5534
5535 </div>
5536
5537
5538 <div class="item">
5539 <div class="name def" id="netCDF4.MFDataset.setncattr">
5540 <p>def <span class="ident">setncattr</span>(</p><p>self,name,value)</p>
5541 </div>
5542
5543
5544
5545
5546 <div class="desc"><p>set a netCDF dataset or group attribute using name,value pair.
5547 Use if you need to set a netCDF attribute with the
5548 with the same name as one of the reserved python attributes.</p></div>
5549 <div class="source_cont">
5550 </div>
5551
5552 </div>
5553
5554
5555 <div class="item">
5556 <div class="name def" id="netCDF4.MFDataset.setncattr_string">
5557 <p>def <span class="ident">setncattr_string</span>(</p><p>self,name,value)</p>
5558 </div>
5559
5560
5561
5562
5563 <div class="desc"><p>set a netCDF dataset or group string attribute using name,value pair.
5564 Use if you need to ensure that a netCDF attribute is created with type
5565 <code>NC_STRING</code> if the file format is <code>NETCDF4</code>.</p></div>
5566 <div class="source_cont">
5567 </div>
5568
5569 </div>
5570
5571
5572 <div class="item">
5573 <div class="name def" id="netCDF4.MFDataset.setncatts">
5574 <p>def <span class="ident">setncatts</span>(</p><p>self,attdict)</p>
5575 </div>
5576
5577
5578
5579
5580 <div class="desc"><p>set a bunch of netCDF dataset or group attributes at once using a python dictionary.
5581 This may be faster when setting a lot of attributes for a <code>NETCDF3</code>
5582 formatted file, since nc_redef/nc_enddef is not called in between setting
5583 each attribute</p></div>
5584 <div class="source_cont">
5585 </div>
5586
5587 </div>
5588
5589
5590 <div class="item">
5591 <div class="name def" id="netCDF4.MFDataset.sync">
5592 <p>def <span class="ident">sync</span>(</p><p>self)</p>
5593 </div>
5594
5595
5596
5597
5598 <div class="desc"><p>Writes all buffered data in the <a href="#netCDF4.Dataset"><code>Dataset</code></a> to the disk file.</p></div>
5599 <div class="source_cont">
5600 </div>
5601
5602 </div>
5603
5604 </div>
5605 </div>
5606
5607 <div class="item">
5608 <p id="netCDF4.MFTime" class="name">class <span class="ident">MFTime</span></p>
5609
5610
5611 <div class="desc"><p>Class providing an interface to a MFDataset time Variable by imposing a unique common
5612 time unit and/or calendar to all files.</p>
5613 <p>Example usage (See <a href="#netCDF4.MFTime.__init__"><code>__init__</code></a> for more details):</p>
5614 <div class="codehilite"><pre><span></span><code><span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">numpy</span>
5615 <span class="o">&gt;&gt;&gt;</span> <span class="n">f1</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;mftest_1.nc&quot;</span><span class="p">,</span><span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s2">&quot;NETCDF4_CLASSIC&quot;</span><span class="p">)</span>
5616 <span class="o">&gt;&gt;&gt;</span> <span class="n">f2</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s2">&quot;mftest_2.nc&quot;</span><span class="p">,</span><span class="s2">&quot;w&quot;</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s2">&quot;NETCDF4_CLASSIC&quot;</span><span class="p">)</span>
5617 <span class="o">&gt;&gt;&gt;</span> <span class="n">f1</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
5618 <span class="o">&gt;&gt;&gt;</span> <span class="n">f2</span><span class="o">.</span><span class="n">createDimension</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">)</span>
5619 <span class="o">&gt;&gt;&gt;</span> <span class="n">t1</span> <span class="o">=</span> <span class="n">f1</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;i&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,))</span>
5620 <span class="o">&gt;&gt;&gt;</span> <span class="n">t2</span> <span class="o">=</span> <span class="n">f2</span><span class="o">.</span><span class="n">createVariable</span><span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span><span class="s2">&quot;i&quot;</span><span class="p">,(</span><span class="s2">&quot;time&quot;</span><span class="p">,))</span>
5621 <span class="o">&gt;&gt;&gt;</span> <span class="n">t1</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;days since 2000-01-01&quot;</span>
5622 <span class="o">&gt;&gt;&gt;</span> <span class="n">t2</span><span class="o">.</span><span class="n">units</span> <span class="o">=</span> <span class="s2">&quot;days since 2000-02-01&quot;</span>
5623 <span class="o">&gt;&gt;&gt;</span> <span class="n">t1</span><span class="o">.</span><span class="n">calendar</span> <span class="o">=</span> <span class="s2">&quot;standard&quot;</span>
5624 <span class="o">&gt;&gt;&gt;</span> <span class="n">t2</span><span class="o">.</span><span class="n">calendar</span> <span class="o">=</span> <span class="s2">&quot;standard&quot;</span>
5625 <span class="o">&gt;&gt;&gt;</span> <span class="n">t1</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">31</span><span class="p">)</span>
5626 <span class="o">&gt;&gt;&gt;</span> <span class="n">t2</span><span class="p">[:]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">30</span><span class="p">)</span>
5627 <span class="o">&gt;&gt;&gt;</span> <span class="n">f1</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
5628 <span class="o">&gt;&gt;&gt;</span> <span class="n">f2</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
5629 <span class="o">&gt;&gt;&gt;</span> <span class="c1"># Read the two files in at once, in one Dataset.</span>
5630 <span class="o">&gt;&gt;&gt;</span> <span class="n">f</span> <span class="o">=</span> <span class="n">MFDataset</span><span class="p">(</span><span class="s2">&quot;mftest_*nc&quot;</span><span class="p">)</span>
5631 <span class="o">&gt;&gt;&gt;</span> <span class="n">t</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s2">&quot;time&quot;</span><span class="p">]</span>
5632 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">units</span><span class="p">)</span>
5633 <span class="n">days</span> <span class="n">since</span> <span class="mi">2000</span><span class="o">-</span><span class="mi">01</span><span class="o">-</span><span class="mi">01</span>
5634 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">t</span><span class="p">[</span><span class="mi">32</span><span class="p">])</span> <span class="c1"># The value written in the file, inconsistent with the MF time units.</span>
5635 <span class="mi">1</span>
5636 <span class="o">&gt;&gt;&gt;</span> <span class="n">T</span> <span class="o">=</span> <span class="n">MFTime</span><span class="p">(</span><span class="n">t</span><span class="p">)</span>
5637 <span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span><span class="p">(</span><span class="n">T</span><span class="p">[</span><span class="mi">32</span><span class="p">])</span>
5638 <span class="mi">32</span>
5639 </code></pre></div></div>
5640 <div class="source_cont">
5641 </div>
5642
5643
5644 <div class="class">
5645 <h3>Ancestors (in MRO)</h3>
5646 <ul class="class_list">
5647 <li><a href="#netCDF4.MFTime">MFTime</a></li>
5648 <li>netCDF4._netCDF4._Variable</li>
5649 <li>builtins.object</li>
5650 </ul>
5651 <h3>Static methods</h3>
5652
5653 <div class="item">
5654 <div class="name def" id="netCDF4.MFTime.__init__">
5655 <p>def <span class="ident">__init__</span>(</p><p>self, time, units=None, calendar=None)</p>
5656 </div>
5657
5658
5659
5660
5661 <div class="desc"><p><strong><code>__init__(self, time, units=None, calendar=None)</code></strong></p>
5662 <p>Create a time Variable with units consistent across a multifile
5663 dataset.</p>
5664 <p><strong><code>time</code></strong>: Time variable from a <a href="#netCDF4.MFDataset"><code>MFDataset</code></a>.</p>
5665 <p><strong><code>units</code></strong>: Time units, for example, <code>'days since 1979-01-01'</code>. If <code>None</code>,
5666 use the units from the master variable.</p>
5667 <p><strong><code>calendar</code></strong>: Calendar overload to use across all files, for example,
5668 <code>'standard'</code> or <code>'gregorian'</code>. If <code>None</code>, check that the calendar attribute
5669 is present on each variable and values are unique across files raising a
5670 <code>ValueError</code> otherwise.</p></div>
5671 <div class="source_cont">
5672 </div>
5673
5674 </div>
5675
5676
5677 <div class="item">
5678 <div class="name def" id="netCDF4.MFTime.ncattrs">
5679 <p>def <span class="ident">ncattrs</span>(</p><p>self)</p>
5680 </div>
5681
5682
5683
5684
5685 <div class="source_cont">
5686 </div>
5687
5688 </div>
5689
5690
5691 <div class="item">
5692 <div class="name def" id="netCDF4.MFTime.set_always_mask">
5693 <p>def <span class="ident">set_always_mask</span>(</p><p>self, val)</p>
5694 </div>
5695
5696
5697
5698
5699 <div class="source_cont">
5700 </div>
5701
5702 </div>
5703
5704
5705 <div class="item">
5706 <div class="name def" id="netCDF4.MFTime.set_auto_chartostring">
5707 <p>def <span class="ident">set_auto_chartostring</span>(</p><p>self, val)</p>
5708 </div>
5709
5710
5711
5712
5713 <div class="source_cont">
5714 </div>
5715
5716 </div>
5717
5718
5719 <div class="item">
5720 <div class="name def" id="netCDF4.MFTime.set_auto_mask">
5721 <p>def <span class="ident">set_auto_mask</span>(</p><p>self, val)</p>
5722 </div>
5723
5724
5725
5726
5727 <div class="source_cont">
5728 </div>
5729
5730 </div>
5731
5732
5733 <div class="item">
5734 <div class="name def" id="netCDF4.MFTime.set_auto_maskandscale">
5735 <p>def <span class="ident">set_auto_maskandscale</span>(</p><p>self, val)</p>
5736 </div>
5737
5738
5739
5740
5741 <div class="source_cont">
5742 </div>
5743
5744 </div>
5745
5746
5747 <div class="item">
5748 <div class="name def" id="netCDF4.MFTime.set_auto_scale">
5749 <p>def <span class="ident">set_auto_scale</span>(</p><p>self, val)</p>
5750 </div>
5751
5752
5753
5754
5755 <div class="source_cont">
5756 </div>
5757
5758 </div>
5759
5760
5761 <div class="item">
5762 <div class="name def" id="netCDF4.MFTime.typecode">
5763 <p>def <span class="ident">typecode</span>(</p><p>self)</p>
5764 </div>
5765
5766
5767
5768
5769 <div class="source_cont">
5770 </div>
5771
5772 </div>
5773
5774 </div>
5775 </div>
5776
5777 <div class="item">
5778 <p id="netCDF4.VLType" class="name">class <span class="ident">VLType</span></p>
5779
5780
5781 <div class="desc"><p>A <a href="#netCDF4.VLType"><code>VLType</code></a> instance is used to describe a variable length (VLEN) data
5782 type, and can be passed to the the <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> method of
5783 a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance. See
5784 <a href="#netCDF4.VLType.__init__"><code>__init__</code></a> for more details.</p>
5785 <p>The instance variables <code>dtype</code> and <code>name</code> should not be modified by
5786 the user.</p></div>
5787 <div class="source_cont">
5788 </div>
5789
5790
5791 <div class="class">
5792 <h3>Ancestors (in MRO)</h3>
5793 <ul class="class_list">
5794 <li><a href="#netCDF4.VLType">VLType</a></li>
5795 <li>builtins.object</li>
5796 </ul>
5797 <h3>Class variables</h3>
5798 <div class="item">
5799 <p id="netCDF4.VLType.dtype" class="name">var <span class="ident">dtype</span></p>
5800
5801
5802
5803
5804 <div class="desc"><p>A numpy dtype object describing the component type for the VLEN.</p></div>
5805 <div class="source_cont">
5806 </div>
5807
5808 </div>
5809 <div class="item">
5810 <p id="netCDF4.VLType.name" class="name">var <span class="ident">name</span></p>
5811
5812
5813
5814
5815 <div class="desc"><p>String name.</p></div>
5816 <div class="source_cont">
5817 </div>
5818
5819 </div>
5820 <h3>Static methods</h3>
5821
5822 <div class="item">
5823 <div class="name def" id="netCDF4.VLType.__init__">
5824 <p>def <span class="ident">__init__</span>(</p><p>group, datatype, datatype_name)</p>
5825 </div>
5826
5827
5828
5829
5830 <div class="desc"><p>VLType constructor.</p>
5831 <p><strong><code>group</code></strong>: <a href="#netCDF4.Group"><code>Group</code></a> instance to associate with the VLEN datatype.</p>
5832 <p><strong><code>datatype</code></strong>: An numpy dtype object describing the component type for the
5833 variable length array.</p>
5834 <p><strong><code>datatype_name</code></strong>: a Python string containing a description of the
5835 VLEN data type.</p>
5836 <p><strong><em><code>Note</code></em></strong>: <a href="#netCDF4.VLType"><code>VLType</code></a> instances should be created using the
5837 <a href="#netCDF4.Dataset.createVLType"><code>createVLType</code></a>
5838 method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or <a href="#netCDF4.Group"><code>Group</code></a> instance, not using this class directly.</p></div>
5839 <div class="source_cont">
5840 </div>
5841
5842 </div>
5843
5844 </div>
5845 </div>
5846
5847 <div class="item">
5848 <p id="netCDF4.Variable" class="name">class <span class="ident">Variable</span></p>
5849
5850
5851 <div class="desc"><p>A netCDF <a href="#netCDF4.Variable"><code>Variable</code></a> is used to read and write netCDF data. They are
5852 analogous to numpy array objects. See <a href="#netCDF4.Variable.__init__"><code>__init__</code></a> for more
5853 details.</p>
5854 <p>A list of attribute names corresponding to netCDF attributes defined for
5855 the variable can be obtained with the <a href="#netCDF4.Variable.ncattrs"><code>ncattrs</code></a> method. These
5856 attributes can be created by assigning to an attribute of the
5857 <a href="#netCDF4.Variable"><code>Variable</code></a> instance. A dictionary containing all the netCDF attribute
5858 name/value pairs is provided by the <code>__dict__</code> attribute of a
5859 <a href="#netCDF4.Variable"><code>Variable</code></a> instance.</p>
5860 <p>The following class variables are read-only:</p>
5861 <p><strong><code>dimensions</code></strong>: A tuple containing the names of the
5862 dimensions associated with this variable.</p>
5863 <p><strong><code>dtype</code></strong>: A numpy dtype object describing the
5864 variable's data type.</p>
5865 <p><strong><code>ndim</code></strong>: The number of variable dimensions.</p>
5866 <p><strong><code>shape</code></strong>: A tuple with the current shape (length of all dimensions).</p>
5867 <p><strong><code>scale</code></strong>: If True, <code>scale_factor</code> and <code>add_offset</code> are
5868 applied, and signed integer data is automatically converted to
5869 unsigned integer data if the <code>_Unsigned</code> attribute is set.
5870 Default is <code>True</code>, can be reset using <a href="#netCDF4.Variable.set_auto_scale"><code>set_auto_scale</code></a> and
5871 <a href="#netCDF4.Variable.set_auto_maskandscale"><code>set_auto_maskandscale</code></a> methods.</p>
5872 <p><strong><code>mask</code></strong>: If True, data is automatically converted to/from masked
5873 arrays when missing values or fill values are present. Default is <code>True</code>, can be
5874 reset using <a href="#netCDF4.Variable.set_auto_mask"><code>set_auto_mask</code></a> and <a href="#netCDF4.Variable.set_auto_maskandscale"><code>set_auto_maskandscale</code></a>
5875 methods.</p>
5876 <p><strong><code>chartostring</code></strong>: If True, data is automatically converted to/from character
5877 arrays to string arrays when the <code>_Encoding</code> variable attribute is set.
5878 Default is <code>True</code>, can be reset using
5879 <a href="#netCDF4.Variable.set_auto_chartostring"><code>set_auto_chartostring</code></a> method.</p>
5880 <p><strong><code>least_significant_digit</code></strong>: Describes the power of ten of the
5881 smallest decimal place in the data the contains a reliable value. Data is
5882 truncated to this decimal place when it is assigned to the <a href="#netCDF4.Variable"><code>Variable</code></a>
5883 instance. If <code>None</code>, the data is not truncated.</p>
5884 <p><strong><code>__orthogonal_indexing__</code></strong>: Always <code>True</code>. Indicates to client code
5885 that the object supports 'orthogonal indexing', which means that slices
5886 that are 1d arrays or lists slice along each dimension independently. This
5887 behavior is similar to Fortran or Matlab, but different than numpy.</p>
5888 <p><strong><code>datatype</code></strong>: numpy data type (for primitive data types) or VLType/CompoundType
5889 instance (for compound or vlen data types).</p>
5890 <p><strong><code>name</code></strong>: String name.</p>
5891 <p><strong><code>size</code></strong>: The number of stored elements.</p></div>
5892 <div class="source_cont">
5893 </div>
5894
5895
5896 <div class="class">
5897 <h3>Ancestors (in MRO)</h3>
5898 <ul class="class_list">
5899 <li><a href="#netCDF4.Variable">Variable</a></li>
5900 <li>builtins.object</li>
5901 </ul>
5902 <h3>Class variables</h3>
5903 <div class="item">
5904 <p id="netCDF4.Variable.always_mask" class="name">var <span class="ident">always_mask</span></p>
5905
5906
5907
5908
5909 <div class="source_cont">
5910 </div>
5911
5912 </div>
5913 <div class="item">
5914 <p id="netCDF4.Variable.chartostring" class="name">var <span class="ident">chartostring</span></p>
5915
5916
5917
5918
5919 <div class="desc"><p>If True, data is automatically converted to/from character
5920 arrays to string arrays when <code>_Encoding</code> variable attribute is set.
5921 Default is <code>True</code>, can be reset using
5922 <a href="#netCDF4.Variable.set_auto_chartostring"><code>set_auto_chartostring</code></a> method.</p></div>
5923 <div class="source_cont">
5924 </div>
5925
5926 </div>
5927 <div class="item">
5928 <p id="netCDF4.Variable.datatype" class="name">var <span class="ident">datatype</span></p>
5929
5930
5931
5932
5933 <div class="desc"><p>numpy data type (for primitive data types) or
5934 VLType/CompoundType/EnumType instance (for compound, vlen or enum
5935 data types).</p></div>
5936 <div class="source_cont">
5937 </div>
5938
5939 </div>
5940 <div class="item">
5941 <p id="netCDF4.Variable.dimensions" class="name">var <span class="ident">dimensions</span></p>
5942
5943
5944
5945
5946 <div class="desc"><p>A tuple containing the names of the
5947 dimensions associated with this variable.</p></div>
5948 <div class="source_cont">
5949 </div>
5950
5951 </div>
5952 <div class="item">
5953 <p id="netCDF4.Variable.dtype" class="name">var <span class="ident">dtype</span></p>
5954
5955
5956
5957
5958 <div class="desc"><p>A numpy dtype object describing the
5959 variable's data type.</p></div>
5960 <div class="source_cont">
5961 </div>
5962
5963 </div>
5964 <div class="item">
5965 <p id="netCDF4.Variable.mask" class="name">var <span class="ident">mask</span></p>
5966
5967
5968
5969
5970 <div class="desc"><p>If True, data is automatically converted to/from masked
5971 arrays when missing values or fill values are present. Default is <code>True</code>, can be
5972 reset using <a href="#netCDF4.Variable.set_auto_mask"><code>set_auto_mask</code></a> and <a href="#netCDF4.Variable.set_auto_maskandscale"><code>set_auto_maskandscale</code></a>
5973 methods.</p></div>
5974 <div class="source_cont">
5975 </div>
5976
5977 </div>
5978 <div class="item">
5979 <p id="netCDF4.Variable.name" class="name">var <span class="ident">name</span></p>
5980
5981
5982
5983
5984 <div class="desc"><p>String name.</p></div>
5985 <div class="source_cont">
5986 </div>
5987
5988 </div>
5989 <div class="item">
5990 <p id="netCDF4.Variable.ndim" class="name">var <span class="ident">ndim</span></p>
5991
5992
5993
5994
5995 <div class="desc"><p>The number of variable dimensions.</p></div>
5996 <div class="source_cont">
5997 </div>
5998
5999 </div>
6000 <div class="item">
6001 <p id="netCDF4.Variable.scale" class="name">var <span class="ident">scale</span></p>
6002
6003
6004
6005
6006 <div class="desc"><p>if True, <code>scale_factor</code> and <code>add_offset</code> are
6007 applied, and signed integer data is converted to unsigned
6008 integer data if the <code>_Unsigned</code> attribute is set.
6009 Default is <code>True</code>, can be reset using <a href="#netCDF4.Variable.set_auto_scale"><code>set_auto_scale</code></a> and
6010 <a href="#netCDF4.Variable.set_auto_maskandscale"><code>set_auto_maskandscale</code></a> methods.</p></div>
6011 <div class="source_cont">
6012 </div>
6013
6014 </div>
6015 <div class="item">
6016 <p id="netCDF4.Variable.shape" class="name">var <span class="ident">shape</span></p>
6017
6018
6019
6020
6021 <div class="desc"><p>A tuple with the current shape (length of all dimensions).</p></div>
6022 <div class="source_cont">
6023 </div>
6024
6025 </div>
6026 <div class="item">
6027 <p id="netCDF4.Variable.size" class="name">var <span class="ident">size</span></p>
6028
6029
6030
6031
6032 <div class="desc"><p>The number of stored elements.</p></div>
6033 <div class="source_cont">
6034 </div>
6035
6036 </div>
6037 <h3>Static methods</h3>
6038
6039 <div class="item">
6040 <div class="name def" id="netCDF4.Variable.__init__">
6041 <p>def <span class="ident">__init__</span>(</p><p>self, group, name, datatype, dimensions=(), zlib=False, complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None, endian=&#39;native&#39;, least_significant_digit=None,fill_value=None,chunk_cache=None)</p>
6042 </div>
6043
6044
6045
6046
6047 <div class="desc"><p><a href="#netCDF4.Variable"><code>Variable</code></a> constructor.</p>
6048 <p><strong><code>group</code></strong>: <a href="#netCDF4.Group"><code>Group</code></a> or <a href="#netCDF4.Dataset"><code>Dataset</code></a> instance to associate with variable.</p>
6049 <p><strong><code>name</code></strong>: Name of the variable.</p>
6050 <p><strong><code>datatype</code></strong>: <a href="#netCDF4.Variable"><code>Variable</code></a> data type. Can be specified by providing a
6051 numpy dtype object, or a string that describes a numpy dtype object.
6052 Supported values, corresponding to <code>str</code> attribute of numpy dtype
6053 objects, include <code>'f4'</code> (32-bit floating point), <code>'f8'</code> (64-bit floating
6054 point), <code>'i4'</code> (32-bit signed integer), <code>'i2'</code> (16-bit signed integer),
6055 <code>'i8'</code> (64-bit signed integer), <code>'i4'</code> (8-bit signed integer), <code>'i1'</code>
6056 (8-bit signed integer), <code>'u1'</code> (8-bit unsigned integer), <code>'u2'</code> (16-bit
6057 unsigned integer), <code>'u4'</code> (32-bit unsigned integer), <code>'u8'</code> (64-bit
6058 unsigned integer), or <code>'S1'</code> (single-character string). From
6059 compatibility with Scientific.IO.NetCDF, the old Numeric single character
6060 typecodes can also be used (<code>'f'</code> instead of <code>'f4'</code>, <code>'d'</code> instead of
6061 <code>'f8'</code>, <code>'h'</code> or <code>'s'</code> instead of <code>'i2'</code>, <code>'b'</code> or <code>'B'</code> instead of
6062 <code>'i1'</code>, <code>'c'</code> instead of <code>'S1'</code>, and <code>'i'</code> or <code>'l'</code> instead of
6063 <code>'i4'</code>). <code>datatype</code> can also be a <a href="#netCDF4.CompoundType"><code>CompoundType</code></a> instance
6064 (for a structured, or compound array), a <a href="#netCDF4.VLType"><code>VLType</code></a> instance
6065 (for a variable-length array), or the python <code>str</code> builtin
6066 (for a variable-length string array). Numpy string and unicode datatypes with
6067 length greater than one are aliases for <code>str</code>.</p>
6068 <p><strong><code>dimensions</code></strong>: a tuple containing the variable's dimension names
6069 (defined previously with <code>createDimension</code>). Default is an empty tuple
6070 which means the variable is a scalar (and therefore has no dimensions).</p>
6071 <p><strong><code>zlib</code></strong>: if <code>True</code>, data assigned to the <a href="#netCDF4.Variable"><code>Variable</code></a>
6072 instance is compressed on disk. Default <code>False</code>.</p>
6073 <p><strong><code>complevel</code></strong>: the level of zlib compression to use (1 is the fastest,
6074 but poorest compression, 9 is the slowest but best compression). Default 4.
6075 Ignored if <code>zlib=False</code>.</p>
6076 <p><strong><code>shuffle</code></strong>: if <code>True</code>, the HDF5 shuffle filter is applied
6077 to improve compression. Default <code>True</code>. Ignored if <code>zlib=False</code>.</p>
6078 <p><strong><code>fletcher32</code></strong>: if <code>True</code> (default <code>False</code>), the Fletcher32 checksum
6079 algorithm is used for error detection.</p>
6080 <p><strong><code>contiguous</code></strong>: if <code>True</code> (default <code>False</code>), the variable data is
6081 stored contiguously on disk. Default <code>False</code>. Setting to <code>True</code> for
6082 a variable with an unlimited dimension will trigger an error.</p>
6083 <p><strong><code>chunksizes</code></strong>: Can be used to specify the HDF5 chunksizes for each
6084 dimension of the variable. A detailed discussion of HDF chunking and I/O
6085 performance is available
6086 <a href="http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html">here</a>.
6087 Basically, you want the chunk size for each dimension to match as
6088 closely as possible the size of the data block that users will read
6089 from the file. <code>chunksizes</code> cannot be set if <code>contiguous=True</code>.</p>
6090 <p><strong><code>endian</code></strong>: Can be used to control whether the
6091 data is stored in little or big endian format on disk. Possible
6092 values are <code>little, big</code> or <code>native</code> (default). The library
6093 will automatically handle endian conversions when the data is read,
6094 but if the data is always going to be read on a computer with the
6095 opposite format as the one used to create the file, there may be
6096 some performance advantage to be gained by setting the endian-ness.
6097 For netCDF 3 files (that don't use HDF5), only <code>endian='native'</code> is allowed.</p>
6098 <p>The <code>zlib, complevel, shuffle, fletcher32, contiguous</code> and <code>chunksizes</code>
6099 keywords are silently ignored for netCDF 3 files that do not use HDF5.</p>
6100 <p><strong><code>least_significant_digit</code></strong>: If specified, variable data will be
6101 truncated (quantized). In conjunction with <code>zlib=True</code> this produces
6102 'lossy', but significantly more efficient compression. For example, if
6103 <code>least_significant_digit=1</code>, data will be quantized using
6104 around(scale<em>data)/scale, where scale = 2</em>*bits, and bits is determined
6105 so that a precision of 0.1 is retained (in this case bits=4). Default is
6106 <code>None</code>, or no quantization.</p>
6107 <p><strong><code>fill_value</code></strong>: If specified, the default netCDF <code>_FillValue</code> (the
6108 value that the variable gets filled with before any data is written to it)
6109 is replaced with this value. If fill_value is set to <code>False</code>, then
6110 the variable is not pre-filled. The default netCDF fill values can be found
6111 in <code>netCDF4.default_fillvals</code>.</p>
6112 <p><strong><code>chunk_cache</code></strong>: If specified, sets the chunk cache size for this variable.
6113 Persists as long as Dataset is open. Use <code>netCDF4.set_var_chunk_cache</code> to
6114 change it when Dataset is re-opened. </p>
6115 <p><strong><em>Note</em></strong>: <a href="#netCDF4.Variable"><code>Variable</code></a> instances should be created using the
6116 <a href="#netCDF4.Dataset.createVariable"><code>createVariable</code></a> method of a <a href="#netCDF4.Dataset"><code>Dataset</code></a> or
6117 <a href="#netCDF4.Group"><code>Group</code></a> instance, not using this class directly.</p></div>
6118 <div class="source_cont">
6119 </div>
6120
6121 </div>
6122
6123
6124 <div class="item">
6125 <div class="name def" id="netCDF4.Variable.assignValue">
6126 <p>def <span class="ident">assignValue</span>(</p><p>self, val)</p>
6127 </div>
6128
6129
6130
6131
6132 <div class="desc"><p>assign a value to a scalar variable. Provided for compatibility with
6133 Scientific.IO.NetCDF, can also be done by assigning to an Ellipsis slice ([...]).</p></div>
6134 <div class="source_cont">
6135 </div>
6136
6137 </div>
6138
6139
6140 <div class="item">
6141 <div class="name def" id="netCDF4.Variable.chunking">
6142 <p>def <span class="ident">chunking</span>(</p><p>self)</p>
6143 </div>
6144
6145
6146
6147
6148 <div class="desc"><p>return variable chunking information. If the dataset is
6149 defined to be contiguous (and hence there is no chunking) the word 'contiguous'
6150 is returned. Otherwise, a sequence with the chunksize for
6151 each dimension is returned.</p></div>
6152 <div class="source_cont">
6153 </div>
6154
6155 </div>
6156
6157
6158 <div class="item">
6159 <div class="name def" id="netCDF4.Variable.delncattr">
6160 <p>def <span class="ident">delncattr</span>(</p><p>self,name,value)</p>
6161 </div>
6162
6163
6164
6165
6166 <div class="desc"><p>delete a netCDF variable attribute. Use if you need to delete a
6167 netCDF attribute with the same name as one of the reserved python
6168 attributes.</p></div>
6169 <div class="source_cont">
6170 </div>
6171
6172 </div>
6173
6174
6175 <div class="item">
6176 <div class="name def" id="netCDF4.Variable.endian">
6177 <p>def <span class="ident">endian</span>(</p><p>self)</p>
6178 </div>
6179
6180
6181
6182
6183 <div class="desc"><p>return endian-ness (<code>little,big,native</code>) of variable (as stored in HDF5 file).</p></div>
6184 <div class="source_cont">
6185 </div>
6186
6187 </div>
6188
6189
6190 <div class="item">
6191 <div class="name def" id="netCDF4.Variable.filters">
6192 <p>def <span class="ident">filters</span>(</p><p>self)</p>
6193 </div>
6194
6195
6196
6197
6198 <div class="desc"><p>return dictionary containing HDF5 filter parameters.</p></div>
6199 <div class="source_cont">
6200 </div>
6201
6202 </div>
6203
6204
6205 <div class="item">
6206 <div class="name def" id="netCDF4.Variable.getValue">
6207 <p>def <span class="ident">getValue</span>(</p><p>self)</p>
6208 </div>
6209
6210
6211
6212
6213 <div class="desc"><p>get the value of a scalar variable. Provided for compatibility with
6214 Scientific.IO.NetCDF, can also be done by slicing with an Ellipsis ([...]).</p></div>
6215 <div class="source_cont">
6216 </div>
6217
6218 </div>
6219
6220
6221 <div class="item">
6222 <div class="name def" id="netCDF4.Variable.get_dims">
6223 <p>def <span class="ident">get_dims</span>(</p><p>self)</p>
6224 </div>
6225
6226
6227
6228
6229 <div class="desc"><p>return a tuple of <a href="#netCDF4.Dimension"><code>Dimension</code></a> instances associated with this
6230 `netCDF4.Variable.</p></div>
6231 <div class="source_cont">
6232 </div>
6233
6234 </div>
6235
6236
6237 <div class="item">
6238 <div class="name def" id="netCDF4.Variable.get_var_chunk_cache">
6239 <p>def <span class="ident">get_var_chunk_cache</span>(</p><p>self)</p>
6240 </div>
6241
6242
6243
6244
6245 <div class="desc"><p>return variable chunk cache information in a tuple (size,nelems,preemption).
6246 See netcdf C library documentation for <code>nc_get_var_chunk_cache</code> for
6247 details.</p></div>
6248 <div class="source_cont">
6249 </div>
6250
6251 </div>
6252
6253
6254 <div class="item">
6255 <div class="name def" id="netCDF4.Variable.getncattr">
6256 <p>def <span class="ident">getncattr</span>(</p><p>self,name)</p>
6257 </div>
6258
6259
6260
6261
6262 <div class="desc"><p>retrieve a netCDF variable attribute. Use if you need to set a
6263 netCDF attribute with the same name as one of the reserved python
6264 attributes.</p>
6265 <p>option kwarg <code>encoding</code> can be used to specify the
6266 character encoding of a string attribute (default is <code>utf-8</code>).</p></div>
6267 <div class="source_cont">
6268 </div>
6269
6270 </div>
6271
6272
6273 <div class="item">
6274 <div class="name def" id="netCDF4.Variable.group">
6275 <p>def <span class="ident">group</span>(</p><p>self)</p>
6276 </div>
6277
6278
6279
6280
6281 <div class="desc"><p>return the group that this <a href="#netCDF4.Variable"><code>Variable</code></a> is a member of.</p></div>
6282 <div class="source_cont">
6283 </div>
6284
6285 </div>
6286
6287
6288 <div class="item">
6289 <div class="name def" id="netCDF4.Variable.ncattrs">
6290 <p>def <span class="ident">ncattrs</span>(</p><p>self)</p>
6291 </div>
6292
6293
6294
6295
6296 <div class="desc"><p>return netCDF attribute names for this <a href="#netCDF4.Variable"><code>Variable</code></a> in a list.</p></div>
6297 <div class="source_cont">
6298 </div>
6299
6300 </div>
6301
6302
6303 <div class="item">
6304 <div class="name def" id="netCDF4.Variable.renameAttribute">
6305 <p>def <span class="ident">renameAttribute</span>(</p><p>self, oldname, newname)</p>
6306 </div>
6307
6308
6309
6310
6311 <div class="desc"><p>rename a <a href="#netCDF4.Variable"><code>Variable</code></a> attribute named <code>oldname</code> to <code>newname</code>.</p></div>
6312 <div class="source_cont">
6313 </div>
6314
6315 </div>
6316
6317
6318 <div class="item">
6319 <div class="name def" id="netCDF4.Variable.set_always_mask">
6320 <p>def <span class="ident">set_always_mask</span>(</p><p>self,always_mask)</p>
6321 </div>
6322
6323
6324
6325
6326 <div class="desc"><p>turn on or off conversion of data without missing values to regular
6327 numpy arrays.</p>
6328 <p><code>always_mask</code> is a Boolean determining if automatic conversion of
6329 masked arrays with no missing values to regular numpy arrays shall be
6330 applied. Default is True. Set to False to restore the default behaviour
6331 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
6332 otherwise masked array returned).</p></div>
6333 <div class="source_cont">
6334 </div>
6335
6336 </div>
6337
6338
6339 <div class="item">
6340 <div class="name def" id="netCDF4.Variable.set_auto_chartostring">
6341 <p>def <span class="ident">set_auto_chartostring</span>(</p><p>self,chartostring)</p>
6342 </div>
6343
6344
6345
6346
6347 <div class="desc"><p>turn on or off automatic conversion of character variable data to and
6348 from numpy fixed length string arrays when the <code>_Encoding</code> variable attribute
6349 is set.</p>
6350 <p>If <code>chartostring</code> is set to <code>True</code>, when data is read from a character variable
6351 (dtype = <code>S1</code>) that has an <code>_Encoding</code> attribute, it is converted to a numpy
6352 fixed length unicode string array (dtype = <code>UN</code>, where <code>N</code> is the length
6353 of the the rightmost dimension of the variable). The value of <code>_Encoding</code>
6354 is the unicode encoding that is used to decode the bytes into strings.</p>
6355 <p>When numpy string data is written to a variable it is converted back to
6356 indiviual bytes, with the number of bytes in each string equalling the
6357 rightmost dimension of the variable.</p>
6358 <p>The default value of <code>chartostring</code> is <code>True</code>
6359 (automatic conversions are performed).</p></div>
6360 <div class="source_cont">
6361 </div>
6362
6363 </div>
6364
6365
6366 <div class="item">
6367 <div class="name def" id="netCDF4.Variable.set_auto_mask">
6368 <p>def <span class="ident">set_auto_mask</span>(</p><p>self,mask)</p>
6369 </div>
6370
6371
6372
6373
6374 <div class="desc"><p>turn on or off automatic conversion of variable data to and
6375 from masked arrays .</p>
6376 <p>If <code>mask</code> is set to <code>True</code>, when data is read from a variable
6377 it is converted to a masked array if any of the values are exactly
6378 equal to the either the netCDF _FillValue or the value specified by the
6379 missing_value variable attribute. The fill_value of the masked array
6380 is set to the missing_value attribute (if it exists), otherwise
6381 the netCDF _FillValue attribute (which has a default value
6382 for each data type). When data is written to a variable, the masked
6383 array is converted back to a regular numpy array by replacing all the
6384 masked values by the missing_value attribute of the variable (if it
6385 exists). If the variable has no missing_value attribute, the _FillValue
6386 is used instead. If the variable has valid_min/valid_max and
6387 missing_value attributes, data outside the specified range will be
6388 set to missing_value.</p>
6389 <p>The default value of <code>mask</code> is <code>True</code>
6390 (automatic conversions are performed).</p></div>
6391 <div class="source_cont">
6392 </div>
6393
6394 </div>
6395
6396
6397 <div class="item">
6398 <div class="name def" id="netCDF4.Variable.set_auto_maskandscale">
6399 <p>def <span class="ident">set_auto_maskandscale</span>(</p><p>self,maskandscale)</p>
6400 </div>
6401
6402
6403
6404
6405 <div class="desc"><p>turn on or off automatic conversion of variable data to and
6406 from masked arrays, automatic packing/unpacking of variable
6407 data using <code>scale_factor</code> and <code>add_offset</code> attributes and
6408 automatic conversion of signed integer data to unsigned integer
6409 data if the <code>_Unsigned</code> attribute exists.</p>
6410 <p>If <code>maskandscale</code> is set to <code>True</code>, when data is read from a variable
6411 it is converted to a masked array if any of the values are exactly
6412 equal to the either the netCDF _FillValue or the value specified by the
6413 missing_value variable attribute. The fill_value of the masked array
6414 is set to the missing_value attribute (if it exists), otherwise
6415 the netCDF _FillValue attribute (which has a default value
6416 for each data type). When data is written to a variable, the masked
6417 array is converted back to a regular numpy array by replacing all the
6418 masked values by the missing_value attribute of the variable (if it
6419 exists). If the variable has no missing_value attribute, the _FillValue
6420 is used instead. If the variable has valid_min/valid_max and
6421 missing_value attributes, data outside the specified range will be
6422 set to missing_value.</p>
6423 <p>If <code>maskandscale</code> is set to <code>True</code>, and the variable has a
6424 <code>scale_factor</code> or an <code>add_offset</code> attribute, then data read
6425 from that variable is unpacked using::</p>
6426 <div class="codehilite"><pre><span></span><code><span class="err">data = self.scale_factor*data + self.add_offset</span>
6427 </code></pre></div>
6428
6429
6430 <p>When data is written to a variable it is packed using::</p>
6431 <div class="codehilite"><pre><span></span><code><span class="err">data = (data - self.add_offset)/self.scale_factor</span>
6432 </code></pre></div>
6433
6434
6435 <p>If either scale_factor is present, but add_offset is missing, add_offset
6436 is assumed zero. If add_offset is present, but scale_factor is missing,
6437 scale_factor is assumed to be one.
6438 For more information on how <code>scale_factor</code> and <code>add_offset</code> can be
6439 used to provide simple compression, see the
6440 <a href="http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml">PSD metadata conventions</a>.</p>
6441 <p>In addition, if <code>maskandscale</code> is set to <code>True</code>, and if the variable has an
6442 attribute <code>_Unsigned</code> set, and the variable has a signed integer data type,
6443 a view to the data is returned with the corresponding unsigned integer data type.
6444 This convention is used by the netcdf-java library to save unsigned integer
6445 data in <code>NETCDF3</code> or <code>NETCDF4_CLASSIC</code> files (since the <code>NETCDF3</code>
6446 data model does not have unsigned integer data types).</p>
6447 <p>The default value of <code>maskandscale</code> is <code>True</code>
6448 (automatic conversions are performed).</p></div>
6449 <div class="source_cont">
6450 </div>
6451
6452 </div>
6453
6454
6455 <div class="item">
6456 <div class="name def" id="netCDF4.Variable.set_auto_scale">
6457 <p>def <span class="ident">set_auto_scale</span>(</p><p>self,scale)</p>
6458 </div>
6459
6460
6461
6462
6463 <div class="desc"><p>turn on or off automatic packing/unpacking of variable
6464 data using <code>scale_factor</code> and <code>add_offset</code> attributes.
6465 Also turns on and off automatic conversion of signed integer data
6466 to unsigned integer data if the variable has an <code>_Unsigned</code>
6467 attribute.</p>
6468 <p>If <code>scale</code> is set to <code>True</code>, and the variable has a
6469 <code>scale_factor</code> or an <code>add_offset</code> attribute, then data read
6470 from that variable is unpacked using::</p>
6471 <div class="codehilite"><pre><span></span><code><span class="err">data = self.scale_factor*data + self.add_offset</span>
6472 </code></pre></div>
6473
6474
6475 <p>When data is written to a variable it is packed using::</p>
6476 <div class="codehilite"><pre><span></span><code><span class="err">data = (data - self.add_offset)/self.scale_factor</span>
6477 </code></pre></div>
6478
6479
6480 <p>If either scale_factor is present, but add_offset is missing, add_offset
6481 is assumed zero. If add_offset is present, but scale_factor is missing,
6482 scale_factor is assumed to be one.
6483 For more information on how <code>scale_factor</code> and <code>add_offset</code> can be
6484 used to provide simple compression, see the
6485 <a href="http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml">PSD metadata conventions</a>.</p>
6486 <p>In addition, if <code>scale</code> is set to <code>True</code>, and if the variable has an
6487 attribute <code>_Unsigned</code> set, and the variable has a signed integer data type,
6488 a view to the data is returned with the corresponding unsigned integer datatype.
6489 This convention is used by the netcdf-java library to save unsigned integer
6490 data in <code>NETCDF3</code> or <code>NETCDF4_CLASSIC</code> files (since the <code>NETCDF3</code>
6491 data model does not have unsigned integer data types).</p>
6492 <p>The default value of <code>scale</code> is <code>True</code>
6493 (automatic conversions are performed).</p></div>
6494 <div class="source_cont">
6495 </div>
6496
6497 </div>
6498
6499
6500 <div class="item">
6501 <div class="name def" id="netCDF4.Variable.set_collective">
6502 <p>def <span class="ident">set_collective</span>(</p><p>self,True_or_False)</p>
6503 </div>
6504
6505
6506
6507
6508 <div class="desc"><p>turn on or off collective parallel IO access. Ignored if file is not
6509 open for parallel access.</p></div>
6510 <div class="source_cont">
6511 </div>
6512
6513 </div>
6514
6515
6516 <div class="item">
6517 <div class="name def" id="netCDF4.Variable.set_ncstring_attrs">
6518 <p>def <span class="ident">set_ncstring_attrs</span>(</p><p>...)</p>
6519 </div>
6520
6521
6522
6523
6524 <div class="desc"><p>turn on or off creating NC_STRING string attributes.</p>
6525 <p>If <code>ncstring_attrs</code> is set to <code>True</code> then text attributes will be variable-length
6526 NC_STRINGs.</p>
6527 <p>The default value of <code>ncstring_attrs</code> is <code>False</code> (writing ascii text attributes as
6528 NC_CHAR).</p></div>
6529 <div class="source_cont">
6530 </div>
6531
6532 </div>
6533
6534
6535 <div class="item">
6536 <div class="name def" id="netCDF4.Variable.set_var_chunk_cache">
6537 <p>def <span class="ident">set_var_chunk_cache</span>(</p><p>self,size=None,nelems=None,preemption=None)</p>
6538 </div>
6539
6540
6541
6542
6543 <div class="desc"><p>change variable chunk cache settings.
6544 See netcdf C library documentation for <code>nc_set_var_chunk_cache</code> for
6545 details.</p></div>
6546 <div class="source_cont">
6547 </div>
6548
6549 </div>
6550
6551
6552 <div class="item">
6553 <div class="name def" id="netCDF4.Variable.setncattr">
6554 <p>def <span class="ident">setncattr</span>(</p><p>self,name,value)</p>
6555 </div>
6556
6557
6558
6559
6560 <div class="desc"><p>set a netCDF variable attribute using name,value pair. Use if you need to set a
6561 netCDF attribute with the same name as one of the reserved python
6562 attributes.</p></div>
6563 <div class="source_cont">
6564 </div>
6565
6566 </div>
6567
6568
6569 <div class="item">
6570 <div class="name def" id="netCDF4.Variable.setncattr_string">
6571 <p>def <span class="ident">setncattr_string</span>(</p><p>self,name,value)</p>
6572 </div>
6573
6574
6575
6576
6577 <div class="desc"><p>set a netCDF variable string attribute using name,value pair.
6578 Use if you need to ensure that a netCDF attribute is created with type
6579 <code>NC_STRING</code> if the file format is <code>NETCDF4</code>.
6580 Use if you need to set an attribute to an array of variable-length strings.</p></div>
6581 <div class="source_cont">
6582 </div>
6583
6584 </div>
6585
6586
6587 <div class="item">
6588 <div class="name def" id="netCDF4.Variable.setncatts">
6589 <p>def <span class="ident">setncatts</span>(</p><p>self,attdict)</p>
6590 </div>
6591
6592
6593
6594
6595 <div class="desc"><p>set a bunch of netCDF variable attributes at once using a python dictionary.
6596 This may be faster when setting a lot of attributes for a <code>NETCDF3</code>
6597 formatted file, since nc_redef/nc_enddef is not called in between setting
6598 each attribute</p></div>
6599 <div class="source_cont">
6600 </div>
6601
6602 </div>
6603
6604
6605 <div class="item">
6606 <div class="name def" id="netCDF4.Variable.use_nc_get_vars">
6607 <p>def <span class="ident">use_nc_get_vars</span>(</p><p>self,_use_get_vars)</p>
6608 </div>
6609
6610
6611
6612
6613 <div class="desc"><p>enable the use of netcdf library routine <code>nc_get_vars</code>
6614 to retrieve strided variable slices. By default,
6615 <code>nc_get_vars</code> may not used by default (depending on the
6616 version of the netcdf-c library being used) since it may be
6617 slower than multiple calls to the unstrided read routine <code>nc_get_vara</code>.</p></div>
6618 <div class="source_cont">
6619 </div>
6620
6621 </div>
6622
6623 </div>
6624 </div>
6625
6626 </section>
6627
6628 </article>
6629 <div class="clear"> </div>
6630 <footer id="footer">
6631 <p>
6632 Documentation generated by
6633 <a href="https://github.com/BurntSushi/pdoc">pdoc 0.3.2.dev29+dirty</a>
6634 </p>
6635
6636 <p>pdoc is in the public domain with the
6637 <a href="http://unlicense.org">UNLICENSE</a></p>
6638
6639 <p>Design by <a href="http://nadh.in">Kailash Nadh</a></p>
6640 </footer>
6641 </div>
6642 </body>
6643 </html>
724724 cdef extern from "numpy/arrayobject.h":
725725 ctypedef int npy_intp
726726 ctypedef extern class numpy.ndarray [object PyArrayObject]:
727 cdef char *data
728 cdef int nd
729 cdef npy_intp *dimensions
730 cdef npy_intp *strides
731 cdef object base
732 # cdef dtype descr
733 cdef int flags
727 pass
734728 npy_intp PyArray_SIZE(ndarray arr)
735729 npy_intp PyArray_ISCONTIGUOUS(ndarray arr)
736730 npy_intp PyArray_ISALIGNED(ndarray arr)
731 void* PyArray_DATA(ndarray) nogil
732 char* PyArray_BYTES(ndarray) nogil
733 npy_intp* PyArray_STRIDES(ndarray) nogil
737734 void import_array()
+0
-12
netCDF4/__init__.py less more
0 # init for netCDF4. package
1 # Docstring comes from extension module _netCDF4.
2 from ._netCDF4 import *
3 # Need explicit imports for names beginning with underscores
4 from ._netCDF4 import __doc__, __pdoc__
5 from ._netCDF4 import (__version__, __netcdf4libversion__, __hdf5libversion__,
6 __has_rename_grp__, __has_nc_inq_path__,
7 __has_nc_inq_format_extended__, __has_nc_open_mem__,
8 __has_nc_create_mem__, __has_cdf5_format__,
9 __has_parallel4_support__, __has_pnetcdf_support__)
10 __all__ =\
11 ['Dataset','Variable','Dimension','Group','MFDataset','MFTime','CompoundType','VLType','date2num','num2date','date2index','stringtochar','chartostring','stringtoarr','getlibversion','EnumType','get_chunk_cache','set_chunk_cache']
+0
-6740
netCDF4/_netCDF4.pyx less more
0 """
1 Version 1.5.5.1
2 ---------------
3 - - -
4
5 Introduction
6 ============
7
8 netcdf4-python is a Python interface to the netCDF C library.
9
10 [netCDF](http://www.unidata.ucar.edu/software/netcdf/) version 4 has many features
11 not found in earlier versions of the library and is implemented on top of
12 [HDF5](http://www.hdfgroup.org/HDF5). This module can read and write
13 files in both the new netCDF 4 and the old netCDF 3 format, and can create
14 files that are readable by HDF5 clients. The API modelled after
15 [Scientific.IO.NetCDF](http://dirac.cnrs-orleans.fr/ScientificPython/),
16 and should be familiar to users of that module.
17
18 Most new features of netCDF 4 are implemented, such as multiple
19 unlimited dimensions, groups and zlib data compression. All the new
20 numeric data types (such as 64 bit and unsigned integer types) are
21 implemented. Compound (struct), variable length (vlen) and
22 enumerated (enum) data types are supported, but not the opaque data type.
23 Mixtures of compound, vlen and enum data types (such as
24 compound types containing enums, or vlens containing compound
25 types) are not supported.
26
27 Download
28 ========
29
30 - Latest bleeding-edge code from the
31 [github repository](http://github.com/Unidata/netcdf4-python).
32 - Latest [releases](https://pypi.python.org/pypi/netCDF4)
33 (source code and binary installers).
34
35 Requires
36 ========
37
38 - [numpy array module](http://numpy.scipy.org), version 1.10.0 or later.
39 - [Cython](http://cython.org), version 0.21 or later.
40 - [setuptools](https://pypi.python.org/pypi/setuptools), version 18.0 or
41 later.
42 - [cftime](https://github.com/Unidata/cftime) for
43 the time and date handling utility functions (`netCDF4.num2date`,
44 `netCDF4.date2num` and `netCDF4.date2index`).
45 - The HDF5 C library version 1.8.4-patch1 or higher (1.8.x recommended)
46 from [](ftp://ftp.hdfgroup.org/HDF5/current/src).
47 ***netCDF version 4.4.1 or higher is recommended if using HDF5 1.10.x -
48 otherwise resulting files may be unreadable by clients using earlier
49 versions of HDF5. For netCDF < 4.4.1, HDF5 version 1.8.x is recommended.***
50 Be sure to build with `--enable-hl --enable-shared`.
51 - [Libcurl](http://curl.haxx.se/libcurl), if you want
52 [OPeNDAP](http://opendap.org) support.
53 - [HDF4](http://www.hdfgroup.org/products/hdf4), if you want
54 to be able to read HDF4 "Scientific Dataset" (SD) files.
55 - The netCDF-4 C library from the [github releases
56 page](https://github.com/Unidata/netcdf-c/releases).
57 Version 4.1.1 or higher is required (4.2 or higher recommended).
58 Be sure to build with `--enable-netcdf-4 --enable-shared`, and set
59 `CPPFLAGS="-I $HDF5_DIR/include"` and `LDFLAGS="-L $HDF5_DIR/lib"`,
60 where `$HDF5_DIR` is the directory where HDF5 was installed.
61 If you want [OPeNDAP](http://opendap.org) support, add `--enable-dap`.
62 If you want HDF4 SD support, add `--enable-hdf4` and add
63 the location of the HDF4 headers and library to `$CPPFLAGS` and `$LDFLAGS`.
64 - for MPI parallel IO support, an MPI-enabled versions of the netcdf library
65 is required, as is the [mpi4py](http://mpi4py.scipy.org) python module.
66 Parallel IO further depends on the existence of MPI-enabled HDF5 or the
67 [PnetCDF](https://parallel-netcdf.github.io/) library.
68
69
70 Install
71 =======
72
73 - install the requisite python modules and C libraries (see above). It's
74 easiest if all the C libs are built as shared libraries.
75 - By default, the utility `nc-config`, installed with netcdf 4.1.2 or higher,
76 will be run used to determine where all the dependencies live.
77 - If `nc-config` is not in your default `PATH`, you can set the `NETCDF4_DIR`
78 environment variable and `setup.py` will look in `$NETCDF4_DIR/bin`.
79 You can also use the file `setup.cfg` to set the path to `nc-config`, or
80 enter the paths to the libraries and include files manually. Just edit the `setup.cfg` file
81 in a text editor and follow the instructions in the comments.
82 To disable the use of `nc-config`, set the env var `USE_NCCONFIG` to 0.
83 To disable the use of `setup.cfg`, set `USE_SETUPCFG` to 0.
84 As a last resort, the library and include paths can be set via environment variables.
85 If you go this route, set `USE_NCCONFIG` and `USE_SETUPCFG` to 0, and specify
86 `NETCDF4_LIBDIR`, `NETCDF4_INCDIR`, `HDF5_LIBDIR` and `HDF5_INCDIR`.
87 Similarly, environment variables
88 (all capitalized) can be used to set the include and library paths for
89 `hdf4`, `szip`, `jpeg`, `curl` and `zlib`. If the dependencies are not found
90 in any of the paths specified by environment variables, then standard locations
91 (such as `/usr` and `/usr/local`) are searched.
92 - run `python setup.py build`, then `python setup.py install` (as root if
93 necessary). `pip install` can be used to install pre-compiled binary wheels from
94 [pypi](https://pypi.org/project/netCDF4).
95 - run the tests in the 'test' directory by running `python run_all.py`.
96
97 Tutorial
98 ========
99
100 1. [Creating/Opening/Closing a netCDF file.](#section1)
101 2. [Groups in a netCDF file.](#section2)
102 3. [Dimensions in a netCDF file.](#section3)
103 4. [Variables in a netCDF file.](#section4)
104 5. [Attributes in a netCDF file.](#section5)
105 6. [Writing data to and retrieving data from a netCDF variable.](#section6)
106 7. [Dealing with time coordinates.](#section7)
107 8. [Reading data from a multi-file netCDF dataset.](#section8)
108 9. [Efficient compression of netCDF variables.](#section9)
109 10. [Beyond homogeneous arrays of a fixed type - compound data types.](#section10)
110 11. [Variable-length (vlen) data types.](#section11)
111 12. [Enum data type.](#section12)
112 13. [Parallel IO.](#section13)
113 14. [Dealing with strings.](#section14)
114 15. [In-memory (diskless) Datasets.](#section15)
115
116
117 ## <div id='section1'>1) Creating/Opening/Closing a netCDF file.
118
119 To create a netCDF file from python, you simply call the `netCDF4.Dataset`
120 constructor. This is also the method used to open an existing netCDF
121 file. If the file is open for write access (`mode='w', 'r+'` or `'a'`), you may
122 write any type of data including new dimensions, groups, variables and
123 attributes. netCDF files come in five flavors (`NETCDF3_CLASSIC,
124 NETCDF3_64BIT_OFFSET, NETCDF3_64BIT_DATA, NETCDF4_CLASSIC`, and `NETCDF4`).
125 `NETCDF3_CLASSIC` was the original netcdf binary format, and was limited
126 to file sizes less than 2 Gb. `NETCDF3_64BIT_OFFSET` was introduced
127 in version 3.6.0 of the library, and extended the original binary format
128 to allow for file sizes greater than 2 Gb.
129 `NETCDF3_64BIT_DATA` is a new format that requires version 4.4.0 of
130 the C library - it extends the `NETCDF3_64BIT_OFFSET` binary format to
131 allow for unsigned/64 bit integer data types and 64-bit dimension sizes.
132 `NETCDF3_64BIT` is an alias for `NETCDF3_64BIT_OFFSET`.
133 `NETCDF4_CLASSIC` files use the version 4 disk format (HDF5), but omits features
134 not found in the version 3 API. They can be read by netCDF 3 clients
135 only if they have been relinked against the netCDF 4 library. They can
136 also be read by HDF5 clients. `NETCDF4` files use the version 4 disk
137 format (HDF5) and use the new features of the version 4 API. The
138 `netCDF4` module can read and write files in any of these formats. When
139 creating a new file, the format may be specified using the `format`
140 keyword in the `Dataset` constructor. The default format is
141 `NETCDF4`. To see how a given file is formatted, you can examine the
142 `data_model` attribute. Closing the netCDF file is
143 accomplished via the `netCDF4.Dataset.close` method of the `netCDF4.Dataset`
144 instance.
145
146 Here's an example:
147
148 :::python
149 >>> from netCDF4 import Dataset
150 >>> rootgrp = Dataset("test.nc", "w", format="NETCDF4")
151 >>> print(rootgrp.data_model)
152 NETCDF4
153 >>> rootgrp.close()
154
155 Remote [OPeNDAP](http://opendap.org)-hosted datasets can be accessed for
156 reading over http if a URL is provided to the `netCDF4.Dataset` constructor instead of a
157 filename. However, this requires that the netCDF library be built with
158 OPenDAP support, via the `--enable-dap` configure option (added in
159 version 4.0.1).
160
161
162 ## <div id='section2'>2) Groups in a netCDF file.
163
164 netCDF version 4 added support for organizing data in hierarchical
165 groups, which are analogous to directories in a filesystem. Groups serve
166 as containers for variables, dimensions and attributes, as well as other
167 groups. A `netCDF4.Dataset` creates a special group, called
168 the 'root group', which is similar to the root directory in a unix
169 filesystem. To create `netCDF4.Group` instances, use the
170 `netCDF4.Dataset.createGroup` method of a `netCDF4.Dataset` or `netCDF4.Group`
171 instance. `netCDF4.Dataset.createGroup` takes a single argument, a
172 python string containing the name of the new group. The new `netCDF4.Group`
173 instances contained within the root group can be accessed by name using
174 the `groups` dictionary attribute of the `netCDF4.Dataset` instance. Only
175 `NETCDF4` formatted files support Groups, if you try to create a Group
176 in a netCDF 3 file you will get an error message.
177
178 :::python
179 >>> rootgrp = Dataset("test.nc", "a")
180 >>> fcstgrp = rootgrp.createGroup("forecasts")
181 >>> analgrp = rootgrp.createGroup("analyses")
182 >>> print(rootgrp.groups)
183 {'forecasts': <class 'netCDF4._netCDF4.Group'>
184 group /forecasts:
185 dimensions(sizes):
186 variables(dimensions):
187 groups: , 'analyses': <class 'netCDF4._netCDF4.Group'>
188 group /analyses:
189 dimensions(sizes):
190 variables(dimensions):
191 groups: }
192
193
194
195 Groups can exist within groups in a `netCDF4.Dataset`, just as directories
196 exist within directories in a unix filesystem. Each `netCDF4.Group` instance
197 has a `groups` attribute dictionary containing all of the group
198 instances contained within that group. Each `netCDF4.Group` instance also has a
199 `path` attribute that contains a simulated unix directory path to
200 that group. To simplify the creation of nested groups, you can
201 use a unix-like path as an argument to `netCDF4.Dataset.createGroup`.
202
203 :::python
204 >>> fcstgrp1 = rootgrp.createGroup("/forecasts/model1")
205 >>> fcstgrp2 = rootgrp.createGroup("/forecasts/model2")
206
207 If any of the intermediate elements of the path do not exist, they are created,
208 just as with the unix command `'mkdir -p'`. If you try to create a group
209 that already exists, no error will be raised, and the existing group will be
210 returned.
211
212 Here's an example that shows how to navigate all the groups in a
213 `netCDF4.Dataset`. The function `walktree` is a Python generator that is used
214 to walk the directory tree. Note that printing the `netCDF4.Dataset` or `netCDF4.Group`
215 object yields summary information about it's contents.
216
217 :::python
218 >>> def walktree(top):
219 ... values = top.groups.values()
220 ... yield values
221 ... for value in top.groups.values():
222 ... for children in walktree(value):
223 ... yield children
224 >>> print(rootgrp)
225 <class 'netCDF4._netCDF4.Dataset'>
226 root group (NETCDF4 data model, file format HDF5):
227 dimensions(sizes):
228 variables(dimensions):
229 groups: forecasts, analyses
230 >>> for children in walktree(rootgrp):
231 ... for child in children:
232 ... print(child)
233 <class 'netCDF4._netCDF4.Group'>
234 group /forecasts:
235 dimensions(sizes):
236 variables(dimensions):
237 groups: model1, model2
238 <class 'netCDF4._netCDF4.Group'>
239 group /analyses:
240 dimensions(sizes):
241 variables(dimensions):
242 groups:
243 <class 'netCDF4._netCDF4.Group'>
244 group /forecasts/model1:
245 dimensions(sizes):
246 variables(dimensions):
247 groups:
248 <class 'netCDF4._netCDF4.Group'>
249 group /forecasts/model2:
250 dimensions(sizes):
251 variables(dimensions):
252 groups:
253
254 ## <div id='section3'>3) Dimensions in a netCDF file.
255
256 netCDF defines the sizes of all variables in terms of dimensions, so
257 before any variables can be created the dimensions they use must be
258 created first. A special case, not often used in practice, is that of a
259 scalar variable, which has no dimensions. A dimension is created using
260 the `netCDF4.Dataset.createDimension` method of a `netCDF4.Dataset`
261 or `netCDF4.Group` instance. A Python string is used to set the name of the
262 dimension, and an integer value is used to set the size. To create an
263 unlimited dimension (a dimension that can be appended to), the size
264 value is set to `None` or 0. In this example, there both the `time` and
265 `level` dimensions are unlimited. Having more than one unlimited
266 dimension is a new netCDF 4 feature, in netCDF 3 files there may be only
267 one, and it must be the first (leftmost) dimension of the variable.
268
269 :::python
270 >>> level = rootgrp.createDimension("level", None)
271 >>> time = rootgrp.createDimension("time", None)
272 >>> lat = rootgrp.createDimension("lat", 73)
273 >>> lon = rootgrp.createDimension("lon", 144)
274
275
276 All of the `netCDF4.Dimension` instances are stored in a python dictionary.
277
278 :::python
279 >>> print(rootgrp.dimensions)
280 {'level': <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'level', size = 0, 'time': <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'time', size = 0, 'lat': <class 'netCDF4._netCDF4.Dimension'>: name = 'lat', size = 73, 'lon': <class 'netCDF4._netCDF4.Dimension'>: name = 'lon', size = 144}
281
282 Calling the python `len` function with a `netCDF4.Dimension` instance returns
283 the current size of that dimension.
284 The `netCDF4.Dimension.isunlimited` method of a `netCDF4.Dimension` instance
285 can be used to determine if the dimensions is unlimited, or appendable.
286
287 :::python
288 >>> print(len(lon))
289 144
290 >>> print(lon.isunlimited())
291 False
292 >>> print(time.isunlimited())
293 True
294
295 Printing the `netCDF4.Dimension` object
296 provides useful summary info, including the name and length of the dimension,
297 and whether it is unlimited.
298
299 :::python
300 >>> for dimobj in rootgrp.dimensions.values():
301 ... print(dimobj)
302 <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'level', size = 0
303 <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'time', size = 0
304 <class 'netCDF4._netCDF4.Dimension'>: name = 'lat', size = 73
305 <class 'netCDF4._netCDF4.Dimension'>: name = 'lon', size = 144
306
307 `netCDF4.Dimension` names can be changed using the
308 `netCDF4.Datatset.renameDimension` method of a `netCDF4.Dataset` or
309 `netCDF4.Group` instance.
310
311 ## <div id='section4'>4) Variables in a netCDF file.
312
313 netCDF variables behave much like python multidimensional array objects
314 supplied by the [numpy module](http://numpy.scipy.org). However,
315 unlike numpy arrays, netCDF4 variables can be appended to along one or
316 more 'unlimited' dimensions. To create a netCDF variable, use the
317 `netCDF4.Dataset.createVariable` method of a `netCDF4.Dataset` or
318 `netCDF4.Group` instance. The `netCDF4.Dataset.createVariable` method
319 has two mandatory arguments, the variable name (a Python string), and
320 the variable datatype. The variable's dimensions are given by a tuple
321 containing the dimension names (defined previously with
322 `netCDF4.Dataset.createDimension`). To create a scalar
323 variable, simply leave out the dimensions keyword. The variable
324 primitive datatypes correspond to the dtype attribute of a numpy array.
325 You can specify the datatype as a numpy dtype object, or anything that
326 can be converted to a numpy dtype object. Valid datatype specifiers
327 include: `'f4'` (32-bit floating point), `'f8'` (64-bit floating
328 point), `'i4'` (32-bit signed integer), `'i2'` (16-bit signed
329 integer), `'i8'` (64-bit signed integer), `'i1'` (8-bit signed
330 integer), `'u1'` (8-bit unsigned integer), `'u2'` (16-bit unsigned
331 integer), `'u4'` (32-bit unsigned integer), `'u8'` (64-bit unsigned
332 integer), or `'S1'` (single-character string). The old Numeric
333 single-character typecodes (`'f'`,`'d'`,`'h'`,
334 `'s'`,`'b'`,`'B'`,`'c'`,`'i'`,`'l'`), corresponding to
335 (`'f4'`,`'f8'`,`'i2'`,`'i2'`,`'i1'`,`'i1'`,`'S1'`,`'i4'`,`'i4'`),
336 will also work. The unsigned integer types and the 64-bit integer type
337 can only be used if the file format is `NETCDF4`.
338
339 The dimensions themselves are usually also defined as variables, called
340 coordinate variables. The `netCDF4.Dataset.createVariable`
341 method returns an instance of the `netCDF4.Variable` class whose methods can be
342 used later to access and set variable data and attributes.
343
344 :::python
345 >>> times = rootgrp.createVariable("time","f8",("time",))
346 >>> levels = rootgrp.createVariable("level","i4",("level",))
347 >>> latitudes = rootgrp.createVariable("lat","f4",("lat",))
348 >>> longitudes = rootgrp.createVariable("lon","f4",("lon",))
349 >>> # two dimensions unlimited
350 >>> temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",))
351 >>> temp.units = "K"
352
353 To get summary info on a `netCDF4.Variable` instance in an interactive session,
354 just print it.
355
356 :::python
357 >>> print(temp)
358 <class 'netCDF4._netCDF4.Variable'>
359 float32 temp(time, level, lat, lon)
360 units: K
361 unlimited dimensions: time, level
362 current shape = (0, 0, 73, 144)
363 filling on, default _FillValue of 9.969209968386869e+36 used
364
365 You can use a path to create a Variable inside a hierarchy of groups.
366
367 :::python
368 >>> ftemp = rootgrp.createVariable("/forecasts/model1/temp","f4",("time","level","lat","lon",))
369
370 If the intermediate groups do not yet exist, they will be created.
371
372 You can also query a `netCDF4.Dataset` or `netCDF4.Group` instance directly to obtain `netCDF4.Group` or
373 `netCDF4.Variable` instances using paths.
374
375 :::python
376 >>> print(rootgrp["/forecasts/model1"]) # a Group instance
377 <class 'netCDF4._netCDF4.Group'>
378 group /forecasts/model1:
379 dimensions(sizes):
380 variables(dimensions): float32 temp(time,level,lat,lon)
381 groups:
382 >>> print(rootgrp["/forecasts/model1/temp"]) # a Variable instance
383 <class 'netCDF4._netCDF4.Variable'>
384 float32 temp(time, level, lat, lon)
385 path = /forecasts/model1
386 unlimited dimensions: time, level
387 current shape = (0, 0, 73, 144)
388 filling on, default _FillValue of 9.969209968386869e+36 used
389
390
391 All of the variables in the `netCDF4.Dataset` or `netCDF4.Group` are stored in a
392 Python dictionary, in the same way as the dimensions:
393
394 :::python
395 >>> print(rootgrp.variables)
396 {'time': <class 'netCDF4._netCDF4.Variable'>
397 float64 time(time)
398 unlimited dimensions: time
399 current shape = (0,)
400 filling on, default _FillValue of 9.969209968386869e+36 used, 'level': <class 'netCDF4._netCDF4.Variable'>
401 int32 level(level)
402 unlimited dimensions: level
403 current shape = (0,)
404 filling on, default _FillValue of -2147483647 used, 'lat': <class 'netCDF4._netCDF4.Variable'>
405 float32 lat(lat)
406 unlimited dimensions:
407 current shape = (73,)
408 filling on, default _FillValue of 9.969209968386869e+36 used, 'lon': <class 'netCDF4._netCDF4.Variable'>
409 float32 lon(lon)
410 unlimited dimensions:
411 current shape = (144,)
412 filling on, default _FillValue of 9.969209968386869e+36 used, 'temp': <class 'netCDF4._netCDF4.Variable'>
413 float32 temp(time, level, lat, lon)
414 units: K
415 unlimited dimensions: time, level
416 current shape = (0, 0, 73, 144)
417 filling on, default _FillValue of 9.969209968386869e+36 used}
418
419 `netCDF4.Variable` names can be changed using the
420 `netCDF4.Dataset.renameVariable` method of a `netCDF4.Dataset`
421 instance.
422
423
424 ## <div id='section5'>5) Attributes in a netCDF file.
425
426 There are two types of attributes in a netCDF file, global and variable.
427 Global attributes provide information about a group, or the entire
428 dataset, as a whole. `netCDF4.Variable` attributes provide information about
429 one of the variables in a group. Global attributes are set by assigning
430 values to `netCDF4.Dataset` or `netCDF4.Group` instance variables. `netCDF4.Variable`
431 attributes are set by assigning values to `netCDF4.Variable` instances
432 variables. Attributes can be strings, numbers or sequences. Returning to
433 our example,
434
435 :::python
436 >>> import time
437 >>> rootgrp.description = "bogus example script"
438 >>> rootgrp.history = "Created " + time.ctime(time.time())
439 >>> rootgrp.source = "netCDF4 python module tutorial"
440 >>> latitudes.units = "degrees north"
441 >>> longitudes.units = "degrees east"
442 >>> levels.units = "hPa"
443 >>> temp.units = "K"
444 >>> times.units = "hours since 0001-01-01 00:00:00.0"
445 >>> times.calendar = "gregorian"
446
447 The `netCDF4.Dataset.ncattrs` method of a `netCDF4.Dataset`, `netCDF4.Group` or
448 `netCDF4.Variable` instance can be used to retrieve the names of all the netCDF
449 attributes. This method is provided as a convenience, since using the
450 built-in `dir` Python function will return a bunch of private methods
451 and attributes that cannot (or should not) be modified by the user.
452
453 :::python
454 >>> for name in rootgrp.ncattrs():
455 ... print("Global attr {} = {}".format(name, getattr(rootgrp, name)))
456 Global attr description = bogus example script
457 Global attr history = Created Mon Jul 8 14:19:41 2019
458 Global attr source = netCDF4 python module tutorial
459
460 The `__dict__` attribute of a `netCDF4.Dataset`, `netCDF4.Group` or `netCDF4.Variable`
461 instance provides all the netCDF attribute name/value pairs in a python
462 dictionary:
463
464 :::python
465 >>> print(rootgrp.__dict__)
466 {'description': 'bogus example script', 'history': 'Created Mon Jul 8 14:19:41 2019', 'source': 'netCDF4 python module tutorial'}
467
468 Attributes can be deleted from a netCDF `netCDF4.Dataset`, `netCDF4.Group` or
469 `netCDF4.Variable` using the python `del` statement (i.e. `del grp.foo`
470 removes the attribute `foo` the the group `grp`).
471
472 ## <div id='section6'>6) Writing data to and retrieving data from a netCDF variable.
473
474 Now that you have a netCDF `netCDF4.Variable` instance, how do you put data
475 into it? You can just treat it like an array and assign data to a slice.
476
477 :::python
478 >>> import numpy
479 >>> lats = numpy.arange(-90,91,2.5)
480 >>> lons = numpy.arange(-180,180,2.5)
481 >>> latitudes[:] = lats
482 >>> longitudes[:] = lons
483 >>> print("latitudes =\\n{}".format(latitudes[:]))
484 latitudes =
485 [-90. -87.5 -85. -82.5 -80. -77.5 -75. -72.5 -70. -67.5 -65. -62.5
486 -60. -57.5 -55. -52.5 -50. -47.5 -45. -42.5 -40. -37.5 -35. -32.5
487 -30. -27.5 -25. -22.5 -20. -17.5 -15. -12.5 -10. -7.5 -5. -2.5
488 0. 2.5 5. 7.5 10. 12.5 15. 17.5 20. 22.5 25. 27.5
489 30. 32.5 35. 37.5 40. 42.5 45. 47.5 50. 52.5 55. 57.5
490 60. 62.5 65. 67.5 70. 72.5 75. 77.5 80. 82.5 85. 87.5
491 90. ]
492
493 Unlike NumPy's array objects, netCDF `netCDF4.Variable`
494 objects with unlimited dimensions will grow along those dimensions if you
495 assign data outside the currently defined range of indices.
496
497 :::python
498 >>> # append along two unlimited dimensions by assigning to slice.
499 >>> nlats = len(rootgrp.dimensions["lat"])
500 >>> nlons = len(rootgrp.dimensions["lon"])
501 >>> print("temp shape before adding data = {}".format(temp.shape))
502 temp shape before adding data = (0, 0, 73, 144)
503 >>>
504 >>> from numpy.random import uniform
505 >>> temp[0:5, 0:10, :, :] = uniform(size=(5, 10, nlats, nlons))
506 >>> print("temp shape after adding data = {}".format(temp.shape))
507 temp shape after adding data = (5, 10, 73, 144)
508 >>>
509 >>> # levels have grown, but no values yet assigned.
510 >>> print("levels shape after adding pressure data = {}".format(levels.shape))
511 levels shape after adding pressure data = (10,)
512
513 Note that the size of the levels variable grows when data is appended
514 along the `level` dimension of the variable `temp`, even though no
515 data has yet been assigned to levels.
516
517 :::python
518 >>> # now, assign data to levels dimension variable.
519 >>> levels[:] = [1000.,850.,700.,500.,300.,250.,200.,150.,100.,50.]
520
521 However, that there are some differences between NumPy and netCDF
522 variable slicing rules. Slices behave as usual, being specified as a
523 `start:stop:step` triplet. Using a scalar integer index `i` takes the ith
524 element and reduces the rank of the output array by one. Boolean array and
525 integer sequence indexing behaves differently for netCDF variables
526 than for numpy arrays. Only 1-d boolean arrays and integer sequences are
527 allowed, and these indices work independently along each dimension (similar
528 to the way vector subscripts work in fortran). This means that
529
530 :::python
531 >>> temp[0, 0, [0,1,2,3], [0,1,2,3]].shape
532 (4, 4)
533
534 returns an array of shape (4,4) when slicing a netCDF variable, but for a
535 numpy array it returns an array of shape (4,).
536 Similarly, a netCDF variable of shape `(2,3,4,5)` indexed
537 with `[0, array([True, False, True]), array([False, True, True, True]), :]`
538 would return a `(2, 3, 5)` array. In NumPy, this would raise an error since
539 it would be equivalent to `[0, [0,1], [1,2,3], :]`. When slicing with integer
540 sequences, the indices ***need not be sorted*** and ***may contain
541 duplicates*** (both of these are new features in version 1.2.1).
542 While this behaviour may cause some confusion for those used to NumPy's 'fancy indexing' rules,
543 it provides a very powerful way to extract data from multidimensional netCDF
544 variables by using logical operations on the dimension arrays to create slices.
545
546 For example,
547
548 :::python
549 >>> tempdat = temp[::2, [1,3,6], lats>0, lons>0]
550
551 will extract time indices 0,2 and 4, pressure levels
552 850, 500 and 200 hPa, all Northern Hemisphere latitudes and Eastern
553 Hemisphere longitudes, resulting in a numpy array of shape (3, 3, 36, 71).
554
555 :::python
556 >>> print("shape of fancy temp slice = {}".format(tempdat.shape))
557 shape of fancy temp slice = (3, 3, 36, 71)
558
559 ***Special note for scalar variables***: To extract data from a scalar variable
560 `v` with no associated dimensions, use `numpy.asarray(v)` or `v[...]`.
561 The result will be a numpy scalar array.
562
563 By default, netcdf4-python returns numpy masked arrays with values equal to the
564 `missing_value` or `_FillValue` variable attributes masked. The
565 `netCDF4.Dataset.set_auto_mask` `netCDF4.Dataset` and `netCDF4.Variable` methods
566 can be used to disable this feature so that
567 numpy arrays are always returned, with the missing values included. Prior to
568 version 1.4.0 the default behavior was to only return masked arrays when the
569 requested slice contained missing values. This behavior can be recovered
570 using the `netCDF4.Dataset.set_always_mask` method. If a masked array is
571 written to a netCDF variable, the masked elements are filled with the
572 value specified by the `missing_value` attribute. If the variable has
573 no `missing_value`, the `_FillValue` is used instead.
574
575 ## <div id='section7'>7) Dealing with time coordinates.
576
577 Time coordinate values pose a special challenge to netCDF users. Most
578 metadata standards (such as CF) specify that time should be
579 measure relative to a fixed date using a certain calendar, with units
580 specified like `hours since YY-MM-DD hh:mm:ss`. These units can be
581 awkward to deal with, without a utility to convert the values to and
582 from calendar dates. The function called `netCDF4.num2date` and `netCDF4.date2num` are
583 provided with this package to do just that (starting with version 1.4.0, the
584 [cftime](https://unidata.github.io/cftime) package must be installed
585 separately). Here's an example of how they
586 can be used:
587
588 :::python
589 >>> # fill in times.
590 >>> from datetime import datetime, timedelta
591 >>> from netCDF4 import num2date, date2num
592 >>> dates = [datetime(2001,3,1)+n*timedelta(hours=12) for n in range(temp.shape[0])]
593 >>> times[:] = date2num(dates,units=times.units,calendar=times.calendar)
594 >>> print("time values (in units {}):\\n{}".format(times.units, times[:]))
595 time values (in units hours since 0001-01-01 00:00:00.0):
596 [17533104. 17533116. 17533128. 17533140. 17533152.]
597 >>> dates = num2date(times[:],units=times.units,calendar=times.calendar)
598 >>> print("dates corresponding to time values:\\n{}".format(dates))
599 dates corresponding to time values:
600 [real_datetime(2001, 3, 1, 0, 0) real_datetime(2001, 3, 1, 12, 0)
601 real_datetime(2001, 3, 2, 0, 0) real_datetime(2001, 3, 2, 12, 0)
602 real_datetime(2001, 3, 3, 0, 0)]
603
604 `netCDF4.num2date` converts numeric values of time in the specified `units`
605 and `calendar` to datetime objects, and `netCDF4.date2num` does the reverse.
606 All the calendars currently defined in the
607 [CF metadata convention](http://cfconventions.org) are supported.
608 A function called `netCDF4.date2index` is also provided which returns the indices
609 of a netCDF time variable corresponding to a sequence of datetime instances.
610
611
612 ## <div id='section8'>8) Reading data from a multi-file netCDF dataset.
613
614 If you want to read data from a variable that spans multiple netCDF files,
615 you can use the `netCDF4.MFDataset` class to read the data as if it were
616 contained in a single file. Instead of using a single filename to create
617 a `netCDF4.Dataset` instance, create a `netCDF4.MFDataset` instance with either a list
618 of filenames, or a string with a wildcard (which is then converted to
619 a sorted list of files using the python glob module).
620 Variables in the list of files that share the same unlimited
621 dimension are aggregated together, and can be sliced across multiple
622 files. To illustrate this, let's first create a bunch of netCDF files with
623 the same variable (with the same unlimited dimension). The files
624 must in be in `NETCDF3_64BIT_OFFSET`, `NETCDF3_64BIT_DATA`, `NETCDF3_CLASSIC` or
625 `NETCDF4_CLASSIC` format (`NETCDF4` formatted multi-file
626 datasets are not supported).
627
628 :::python
629 >>> for nf in range(10):
630 ... with Dataset("mftest%s.nc" % nf, "w", format="NETCDF4_CLASSIC") as f:
631 ... _ = f.createDimension("x",None)
632 ... x = f.createVariable("x","i",("x",))
633 ... x[0:10] = numpy.arange(nf*10,10*(nf+1))
634
635 Now read all the files back in at once with `netCDF4.MFDataset`
636
637 :::python
638 >>> from netCDF4 import MFDataset
639 >>> f = MFDataset("mftest*nc")
640 >>> print(f.variables["x"][:])
641 [ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
642 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
643 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
644 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
645 96 97 98 99]
646
647 Note that `netCDF4.MFDataset` can only be used to read, not write, multi-file
648 datasets.
649
650 ## <div id='section9'>9) Efficient compression of netCDF variables.
651
652 Data stored in netCDF 4 `netCDF4.Variable` objects can be compressed and
653 decompressed on the fly. The parameters for the compression are
654 determined by the `zlib`, `complevel` and `shuffle` keyword arguments
655 to the `netCDF4.Dataset.createVariable` method. To turn on
656 compression, set `zlib=True`. The `complevel` keyword regulates the
657 speed and efficiency of the compression (1 being fastest, but lowest
658 compression ratio, 9 being slowest but best compression ratio). The
659 default value of `complevel` is 4. Setting `shuffle=False` will turn
660 off the HDF5 shuffle filter, which de-interlaces a block of data before
661 compression by reordering the bytes. The shuffle filter can
662 significantly improve compression ratios, and is on by default. Setting
663 `fletcher32` keyword argument to
664 `netCDF4.Dataset.createVariable` to `True` (it's `False` by
665 default) enables the Fletcher32 checksum algorithm for error detection.
666 It's also possible to set the HDF5 chunking parameters and endian-ness
667 of the binary data stored in the HDF5 file with the `chunksizes`
668 and `endian` keyword arguments to
669 `netCDF4.Dataset.createVariable`. These keyword arguments only
670 are relevant for `NETCDF4` and `NETCDF4_CLASSIC` files (where the
671 underlying file format is HDF5) and are silently ignored if the file
672 format is `NETCDF3_CLASSIC`, `NETCDF3_64BIT_OFFSET` or `NETCDF3_64BIT_DATA`.
673
674 If your data only has a certain number of digits of precision (say for
675 example, it is temperature data that was measured with a precision of
676 0.1 degrees), you can dramatically improve zlib compression by
677 quantizing (or truncating) the data using the `least_significant_digit`
678 keyword argument to `netCDF4.Dataset.createVariable`. The least
679 significant digit is the power of ten of the smallest decimal place in
680 the data that is a reliable value. For example if the data has a
681 precision of 0.1, then setting `least_significant_digit=1` will cause
682 data the data to be quantized using `numpy.around(scale*data)/scale`, where
683 scale = 2**bits, and bits is determined so that a precision of 0.1 is
684 retained (in this case bits=4). Effectively, this makes the compression
685 'lossy' instead of 'lossless', that is some precision in the data is
686 sacrificed for the sake of disk space.
687
688 In our example, try replacing the line
689
690 :::python
691 >>> temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",))
692
693 with
694
695 :::python
696 >>> temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",),zlib=True)
697
698 and then
699
700 :::python
701 >>> temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",),zlib=True,least_significant_digit=3)
702
703 and see how much smaller the resulting files are.
704
705 ## <div id='section10'>10) Beyond homogeneous arrays of a fixed type - compound data types.
706
707 Compound data types map directly to numpy structured (a.k.a 'record')
708 arrays. Structured arrays are akin to C structs, or derived types
709 in Fortran. They allow for the construction of table-like structures
710 composed of combinations of other data types, including other
711 compound types. Compound types might be useful for representing multiple
712 parameter values at each point on a grid, or at each time and space
713 location for scattered (point) data. You can then access all the
714 information for a point by reading one variable, instead of reading
715 different parameters from different variables. Compound data types
716 are created from the corresponding numpy data type using the
717 `netCDF4.Dataset.createCompoundType` method of a `netCDF4.Dataset` or `netCDF4.Group` instance.
718 Since there is no native complex data type in netcdf, compound types are handy
719 for storing numpy complex arrays. Here's an example:
720
721 :::python
722 >>> f = Dataset("complex.nc","w")
723 >>> size = 3 # length of 1-d complex array
724 >>> # create sample complex data.
725 >>> datac = numpy.exp(1j*(1.+numpy.linspace(0, numpy.pi, size)))
726 >>> # create complex128 compound data type.
727 >>> complex128 = numpy.dtype([("real",numpy.float64),("imag",numpy.float64)])
728 >>> complex128_t = f.createCompoundType(complex128,"complex128")
729 >>> # create a variable with this data type, write some data to it.
730 >>> x_dim = f.createDimension("x_dim",None)
731 >>> v = f.createVariable("cmplx_var",complex128_t,"x_dim")
732 >>> data = numpy.empty(size,complex128) # numpy structured array
733 >>> data["real"] = datac.real; data["imag"] = datac.imag
734 >>> v[:] = data # write numpy structured array to netcdf compound var
735 >>> # close and reopen the file, check the contents.
736 >>> f.close(); f = Dataset("complex.nc")
737 >>> v = f.variables["cmplx_var"]
738 >>> datain = v[:] # read in all the data into a numpy structured array
739 >>> # create an empty numpy complex array
740 >>> datac2 = numpy.empty(datain.shape,numpy.complex128)
741 >>> # .. fill it with contents of structured array.
742 >>> datac2.real = datain["real"]; datac2.imag = datain["imag"]
743 >>> print('{}: {}'.format(datac.dtype, datac)) # original data
744 complex128: [ 0.54030231+0.84147098j -0.84147098+0.54030231j -0.54030231-0.84147098j]
745 >>>
746 >>> print('{}: {}'.format(datac2.dtype, datac2)) # data from file
747 complex128: [ 0.54030231+0.84147098j -0.84147098+0.54030231j -0.54030231-0.84147098j]
748
749 Compound types can be nested, but you must create the 'inner'
750 ones first. All possible numpy structured arrays cannot be
751 represented as Compound variables - an error message will be
752 raise if you try to create one that is not supported.
753 All of the compound types defined for a `netCDF4.Dataset` or `netCDF4.Group` are stored
754 in a Python dictionary, just like variables and dimensions. As always, printing
755 objects gives useful summary information in an interactive session:
756
757 :::python
758 >>> print(f)
759 <class 'netCDF4._netCDF4.Dataset'>
760 root group (NETCDF4 data model, file format HDF5):
761 dimensions(sizes): x_dim(3)
762 variables(dimensions): {'names':['real','imag'], 'formats':['<f8','<f8'], 'offsets':[0,8], 'itemsize':16, 'aligned':True} cmplx_var(x_dim)
763 groups:
764 >>> print(f.variables["cmplx_var"])
765 <class 'netCDF4._netCDF4.Variable'>
766 compound cmplx_var(x_dim)
767 compound data type: {'names':['real','imag'], 'formats':['<f8','<f8'], 'offsets':[0,8], 'itemsize':16, 'aligned':True}
768 unlimited dimensions: x_dim
769 current shape = (3,)
770 >>> print(f.cmptypes)
771 {'complex128': <class 'netCDF4._netCDF4.CompoundType'>: name = 'complex128', numpy dtype = {'names':['real','imag'], 'formats':['<f8','<f8'], 'offsets':[0,8], 'itemsize':16, 'aligned':True}}
772 >>> print(f.cmptypes["complex128"])
773 <class 'netCDF4._netCDF4.CompoundType'>: name = 'complex128', numpy dtype = {'names':['real','imag'], 'formats':['<f8','<f8'], 'offsets':[0,8], 'itemsize':16, 'aligned':True}
774
775 ## <div id='section11'>11) Variable-length (vlen) data types.
776
777 NetCDF 4 has support for variable-length or "ragged" arrays. These are arrays
778 of variable length sequences having the same type. To create a variable-length
779 data type, use the `netCDF4.Dataset.createVLType` method
780 method of a `netCDF4.Dataset` or `netCDF4.Group` instance.
781
782 :::python
783 >>> f = Dataset("tst_vlen.nc","w")
784 >>> vlen_t = f.createVLType(numpy.int32, "phony_vlen")
785
786 The numpy datatype of the variable-length sequences and the name of the
787 new datatype must be specified. Any of the primitive datatypes can be
788 used (signed and unsigned integers, 32 and 64 bit floats, and characters),
789 but compound data types cannot.
790 A new variable can then be created using this datatype.
791
792 :::python
793 >>> x = f.createDimension("x",3)
794 >>> y = f.createDimension("y",4)
795 >>> vlvar = f.createVariable("phony_vlen_var", vlen_t, ("y","x"))
796
797 Since there is no native vlen datatype in numpy, vlen arrays are represented
798 in python as object arrays (arrays of dtype `object`). These are arrays whose
799 elements are Python object pointers, and can contain any type of python object.
800 For this application, they must contain 1-D numpy arrays all of the same type
801 but of varying length.
802 In this case, they contain 1-D numpy `int32` arrays of random length between
803 1 and 10.
804
805 :::python
806 >>> import random
807 >>> random.seed(54321)
808 >>> data = numpy.empty(len(y)*len(x),object)
809 >>> for n in range(len(y)*len(x)):
810 ... data[n] = numpy.arange(random.randint(1,10),dtype="int32")+1
811 >>> data = numpy.reshape(data,(len(y),len(x)))
812 >>> vlvar[:] = data
813 >>> print("vlen variable =\\n{}".format(vlvar[:]))
814 vlen variable =
815 [[array([1, 2, 3, 4, 5, 6, 7, 8], dtype=int32) array([1, 2], dtype=int32)
816 array([1, 2, 3, 4], dtype=int32)]
817 [array([1, 2, 3], dtype=int32)
818 array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=int32)
819 array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=int32)]
820 [array([1, 2, 3, 4, 5, 6, 7], dtype=int32) array([1, 2, 3], dtype=int32)
821 array([1, 2, 3, 4, 5, 6], dtype=int32)]
822 [array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=int32)
823 array([1, 2, 3, 4, 5], dtype=int32) array([1, 2], dtype=int32)]]
824 >>> print(f)
825 <class 'netCDF4._netCDF4.Dataset'>
826 root group (NETCDF4 data model, file format HDF5):
827 dimensions(sizes): x(3), y(4)
828 variables(dimensions): int32 phony_vlen_var(y,x)
829 groups:
830 >>> print(f.variables["phony_vlen_var"])
831 <class 'netCDF4._netCDF4.Variable'>
832 vlen phony_vlen_var(y, x)
833 vlen data type: int32
834 unlimited dimensions:
835 current shape = (4, 3)
836 >>> print(f.vltypes["phony_vlen"])
837 <class 'netCDF4._netCDF4.VLType'>: name = 'phony_vlen', numpy dtype = int32
838
839 Numpy object arrays containing python strings can also be written as vlen
840 variables, For vlen strings, you don't need to create a vlen data type.
841 Instead, simply use the python `str` builtin (or a numpy string datatype
842 with fixed length greater than 1) when calling the
843 `netCDF4.Dataset.createVariable` method.
844
845 :::python
846 >>> z = f.createDimension("z",10)
847 >>> strvar = f.createVariable("strvar", str, "z")
848
849 In this example, an object array is filled with random python strings with
850 random lengths between 2 and 12 characters, and the data in the object
851 array is assigned to the vlen string variable.
852
853 :::python
854 >>> chars = "1234567890aabcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
855 >>> data = numpy.empty(10,"O")
856 >>> for n in range(10):
857 ... stringlen = random.randint(2,12)
858 ... data[n] = "".join([random.choice(chars) for i in range(stringlen)])
859 >>> strvar[:] = data
860 >>> print("variable-length string variable:\\n{}".format(strvar[:]))
861 variable-length string variable:
862 ['Lh' '25F8wBbMI' '53rmM' 'vvjnb3t63ao' 'qjRBQk6w' 'aJh' 'QF'
863 'jtIJbJACaQk4' '3Z5' 'bftIIq']
864 >>> print(f)
865 <class 'netCDF4._netCDF4.Dataset'>
866 root group (NETCDF4 data model, file format HDF5):
867 dimensions(sizes): x(3), y(4), z(10)
868 variables(dimensions): int32 phony_vlen_var(y,x), <class 'str'> strvar(z)
869 groups:
870 >>> print(f.variables["strvar"])
871 <class 'netCDF4._netCDF4.Variable'>
872 vlen strvar(z)
873 vlen data type: <class 'str'>
874 unlimited dimensions:
875 current shape = (10,)
876
877 It is also possible to set contents of vlen string variables with numpy arrays
878 of any string or unicode data type. Note, however, that accessing the contents
879 of such variables will always return numpy arrays with dtype `object`.
880
881 ## <div id='section12'>12) Enum data type.
882
883 netCDF4 has an enumerated data type, which is an integer datatype that is
884 restricted to certain named values. Since Enums don't map directly to
885 a numpy data type, they are read and written as integer arrays.
886
887 Here's an example of using an Enum type to hold cloud type data.
888 The base integer data type and a python dictionary describing the allowed
889 values and their names are used to define an Enum data type using
890 `netCDF4.Dataset.createEnumType`.
891
892 :::python
893 >>> nc = Dataset('clouds.nc','w')
894 >>> # python dict with allowed values and their names.
895 >>> enum_dict = {'Altocumulus': 7, 'Missing': 255,
896 ... 'Stratus': 2, 'Clear': 0,
897 ... 'Nimbostratus': 6, 'Cumulus': 4, 'Altostratus': 5,
898 ... 'Cumulonimbus': 1, 'Stratocumulus': 3}
899 >>> # create the Enum type called 'cloud_t'.
900 >>> cloud_type = nc.createEnumType(numpy.uint8,'cloud_t',enum_dict)
901 >>> print(cloud_type)
902 <class 'netCDF4._netCDF4.EnumType'>: name = 'cloud_t', numpy dtype = uint8, fields/values ={'Altocumulus': 7, 'Missing': 255, 'Stratus': 2, 'Clear': 0, 'Nimbostratus': 6, 'Cumulus': 4, 'Altostratus': 5, 'Cumulonimbus': 1, 'Stratocumulus': 3}
903
904 A new variable can be created in the usual way using this data type.
905 Integer data is written to the variable that represents the named
906 cloud types in enum_dict. A `ValueError` will be raised if an attempt
907 is made to write an integer value not associated with one of the
908 specified names.
909
910 :::python
911 >>> time = nc.createDimension('time',None)
912 >>> # create a 1d variable of type 'cloud_type'.
913 >>> # The fill_value is set to the 'Missing' named value.
914 >>> cloud_var = nc.createVariable('primary_cloud',cloud_type,'time',
915 ... fill_value=enum_dict['Missing'])
916 >>> # write some data to the variable.
917 >>> cloud_var[:] = [enum_dict[k] for k in ['Clear', 'Stratus', 'Cumulus',
918 ... 'Missing', 'Cumulonimbus']]
919 >>> nc.close()
920 >>> # reopen the file, read the data.
921 >>> nc = Dataset('clouds.nc')
922 >>> cloud_var = nc.variables['primary_cloud']
923 >>> print(cloud_var)
924 <class 'netCDF4._netCDF4.Variable'>
925 enum primary_cloud(time)
926 _FillValue: 255
927 enum data type: uint8
928 unlimited dimensions: time
929 current shape = (5,)
930 >>> print(cloud_var.datatype.enum_dict)
931 {'Altocumulus': 7, 'Missing': 255, 'Stratus': 2, 'Clear': 0, 'Nimbostratus': 6, 'Cumulus': 4, 'Altostratus': 5, 'Cumulonimbus': 1, 'Stratocumulus': 3}
932 >>> print(cloud_var[:])
933 [0 2 4 -- 1]
934 >>> nc.close()
935
936 ## <div id='section13'>13) Parallel IO.
937
938 If MPI parallel enabled versions of netcdf and hdf5 or pnetcdf are detected,
939 and [mpi4py](https://mpi4py.scipy.org) is installed, netcdf4-python will
940 be built with parallel IO capabilities enabled. Parallel IO of NETCDF4 or
941 NETCDF4_CLASSIC formatted files is only available if the MPI parallel HDF5
942 library is available. Parallel IO of classic netcdf-3 file formats is only
943 available if the [PnetCDF](https://parallel-netcdf.github.io/) library is
944 available. To use parallel IO, your program must be running in an MPI
945 environment using [mpi4py](https://mpi4py.scipy.org).
946
947 :::python
948 >>> from mpi4py import MPI
949 >>> import numpy as np
950 >>> from netCDF4 import Dataset
951 >>> rank = MPI.COMM_WORLD.rank # The process ID (integer 0-3 for 4-process run)
952
953 To run an MPI-based parallel program like this, you must use `mpiexec` to launch several
954 parallel instances of Python (for example, using `mpiexec -np 4 python mpi_example.py`).
955 The parallel features of netcdf4-python are mostly transparent -
956 when a new dataset is created or an existing dataset is opened,
957 use the `parallel` keyword to enable parallel access.
958
959 :::python
960 >>> nc = Dataset('parallel_test.nc','w',parallel=True)
961
962 The optional `comm` keyword may be used to specify a particular
963 MPI communicator (`MPI_COMM_WORLD` is used by default). Each process (or rank)
964 can now write to the file indepedently. In this example the process rank is
965 written to a different variable index on each task
966
967 :::python
968 >>> d = nc.createDimension('dim',4)
969 >>> v = nc.createVariable('var', np.int, 'dim')
970 >>> v[rank] = rank
971 >>> nc.close()
972
973 % ncdump parallel_test.nc
974 netcdf parallel_test {
975 dimensions:
976 dim = 4 ;
977 variables:
978 int64 var(dim) ;
979 data:
980
981 var = 0, 1, 2, 3 ;
982 }
983
984 There are two types of parallel IO, independent (the default) and collective.
985 Independent IO means that each process can do IO independently. It should not
986 depend on or be affected by other processes. Collective IO is a way of doing
987 IO defined in the MPI-IO standard; unlike independent IO, all processes must
988 participate in doing IO. To toggle back and forth between
989 the two types of IO, use the `netCDF4.Variable.set_collective`
990 `netCDF4.Variable`method. All metadata
991 operations (such as creation of groups, types, variables, dimensions, or attributes)
992 are collective. There are a couple of important limitations of parallel IO:
993
994 - parallel IO for NETCDF4 or NETCDF4_CLASSIC formatted files is only available
995 if the netcdf library was compiled with MPI enabled HDF5.
996 - parallel IO for all classic netcdf-3 file formats is only available if the
997 netcdf library was compiled with PnetCDF.
998 - If a variable has an unlimited dimension, appending data must be done in collective mode.
999 If the write is done in independent mode, the operation will fail with a
1000 a generic "HDF Error".
1001 - You cannot write compressed data in parallel (although
1002 you can read it).
1003 - You cannot use variable-length (VLEN) data types.
1004
1005 ## <div id='section14'>14) Dealing with strings.
1006
1007 The most flexible way to store arrays of strings is with the
1008 [Variable-length (vlen) string data type](#section11). However, this requires
1009 the use of the NETCDF4 data model, and the vlen type does not map very well
1010 numpy arrays (you have to use numpy arrays of dtype=`object`, which are arrays of
1011 arbitrary python objects). numpy does have a fixed-width string array
1012 data type, but unfortunately the netCDF data model does not.
1013 Instead fixed-width byte strings are typically stored as [arrays of 8-bit
1014 characters](https://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.html#bp_Strings-and-Variables-of-type-char).
1015 To perform the conversion to and from character arrays to fixed-width numpy string arrays, the
1016 following convention is followed by the python interface.
1017 If the `_Encoding` special attribute is set for a character array
1018 (dtype `S1`) variable, the `netCDF4.chartostring` utility function is used to convert the array of
1019 characters to an array of strings with one less dimension (the last dimension is
1020 interpreted as the length of each string) when reading the data. The character
1021 set (usually ascii) is specified by the `_Encoding` attribute. If `_Encoding`
1022 is 'none' or 'bytes', then the character array is converted to a numpy
1023 fixed-width byte string array (dtype `S#`), otherwise a numpy unicode (dtype
1024 `U#`) array is created. When writing the data,
1025 `netCDF4.stringtochar` is used to convert the numpy string array to an array of
1026 characters with one more dimension. For example,
1027
1028 :::python
1029 >>> from netCDF4 import stringtochar
1030 >>> nc = Dataset('stringtest.nc','w',format='NETCDF4_CLASSIC')
1031 >>> _ = nc.createDimension('nchars',3)
1032 >>> _ = nc.createDimension('nstrings',None)
1033 >>> v = nc.createVariable('strings','S1',('nstrings','nchars'))
1034 >>> datain = numpy.array(['foo','bar'],dtype='S3')
1035 >>> v[:] = stringtochar(datain) # manual conversion to char array
1036 >>> print(v[:]) # data returned as char array
1037 [[b'f' b'o' b'o']
1038 [b'b' b'a' b'r']]
1039 >>> v._Encoding = 'ascii' # this enables automatic conversion
1040 >>> v[:] = datain # conversion to char array done internally
1041 >>> print(v[:]) # data returned in numpy string array
1042 ['foo' 'bar']
1043 >>> nc.close()
1044
1045 Even if the `_Encoding` attribute is set, the automatic conversion of char
1046 arrays to/from string arrays can be disabled with
1047 `netCDF4.Variable.set_auto_chartostring`.
1048
1049 A similar situation is often encountered with numpy structured arrays with subdtypes
1050 containing fixed-wdith byte strings (dtype=`S#`). Since there is no native fixed-length string
1051 netCDF datatype, these numpy structure arrays are mapped onto netCDF compound
1052 types with character array elements. In this case the string <-> char array
1053 conversion is handled automatically (without the need to set the `_Encoding`
1054 attribute) using [numpy
1055 views](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.view.html).
1056 The structured array dtype (including the string elements) can even be used to
1057 define the compound data type - the string dtype will be converted to
1058 character array dtype under the hood when creating the netcdf compound type.
1059 Here's an example:
1060
1061 :::python
1062 >>> nc = Dataset('compoundstring_example.nc','w')
1063 >>> dtype = numpy.dtype([('observation', 'f4'),
1064 ... ('station_name','S10')])
1065 >>> station_data_t = nc.createCompoundType(dtype,'station_data')
1066 >>> _ = nc.createDimension('station',None)
1067 >>> statdat = nc.createVariable('station_obs', station_data_t, ('station',))
1068 >>> data = numpy.empty(2,dtype)
1069 >>> data['observation'][:] = (123.,3.14)
1070 >>> data['station_name'][:] = ('Boulder','New York')
1071 >>> print(statdat.dtype) # strings actually stored as character arrays
1072 {'names':['observation','station_name'], 'formats':['<f4',('S1', (10,))], 'offsets':[0,4], 'itemsize':16, 'aligned':True}
1073 >>> statdat[:] = data # strings converted to character arrays internally
1074 >>> print(statdat[:]) # character arrays converted back to strings
1075 [(123. , b'Boulder') ( 3.14, b'New York')]
1076 >>> print(statdat[:].dtype)
1077 {'names':['observation','station_name'], 'formats':['<f4','S10'], 'offsets':[0,4], 'itemsize':16, 'aligned':True}
1078 >>> statdat.set_auto_chartostring(False) # turn off auto-conversion
1079 >>> statdat[:] = data.view(dtype=[('observation', 'f4'),('station_name','S1',10)])
1080 >>> print(statdat[:]) # now structured array with char array subtype is returned
1081 [(123. , [b'B', b'o', b'u', b'l', b'd', b'e', b'r', b'', b'', b''])
1082 ( 3.14, [b'N', b'e', b'w', b' ', b'Y', b'o', b'r', b'k', b'', b''])]
1083 >>> nc.close()
1084
1085 Note that there is currently no support for mapping numpy structured arrays with
1086 unicode elements (dtype `U#`) onto netCDF compound types, nor is there support
1087 for netCDF compound types with vlen string components.
1088
1089 ## <div id='section15'>15) In-memory (diskless) Datasets.
1090
1091 You can create netCDF Datasets whose content is held in memory
1092 instead of in a disk file. There are two ways to do this. If you
1093 don't need access to the memory buffer containing the Dataset from
1094 within python, the best way is to use the `diskless=True` keyword
1095 argument when creating the Dataset. If you want to save the Dataset
1096 to disk when you close it, also set `persist=True`. If you want to
1097 create a new read-only Dataset from an existing python memory buffer, use the
1098 `memory` keyword argument to pass the memory buffer when creating the Dataset.
1099 If you want to create a new in-memory Dataset, and then access the memory buffer
1100 directly from Python, use the `memory` keyword argument to specify the
1101 estimated size of the Dataset in bytes when creating the Dataset with
1102 `mode='w'`. Then, the `Dataset.close` method will return a python memoryview
1103 object representing the Dataset. Below are examples illustrating both
1104 approaches.
1105
1106 :::python
1107 >>> # create a diskless (in-memory) Dataset,
1108 >>> # and persist the file to disk when it is closed.
1109 >>> nc = Dataset('diskless_example.nc','w',diskless=True,persist=True)
1110 >>> d = nc.createDimension('x',None)
1111 >>> v = nc.createVariable('v',numpy.int32,'x')
1112 >>> v[0:5] = numpy.arange(5)
1113 >>> print(nc)
1114 <class 'netCDF4._netCDF4.Dataset'>
1115 root group (NETCDF4 data model, file format HDF5):
1116 dimensions(sizes): x(5)
1117 variables(dimensions): int32 v(x)
1118 groups:
1119 >>> print(nc['v'][:])
1120 [0 1 2 3 4]
1121 >>> nc.close() # file saved to disk
1122 >>> # create an in-memory dataset from an existing python
1123 >>> # python memory buffer.
1124 >>> # read the newly created netcdf file into a python
1125 >>> # bytes object.
1126 >>> with open('diskless_example.nc', 'rb') as f:
1127 ... nc_bytes = f.read()
1128 >>> # create a netCDF in-memory dataset from the bytes object.
1129 >>> nc = Dataset('inmemory.nc', memory=nc_bytes)
1130 >>> print(nc)
1131 <class 'netCDF4._netCDF4.Dataset'>
1132 root group (NETCDF4 data model, file format HDF5):
1133 dimensions(sizes): x(5)
1134 variables(dimensions): int32 v(x)
1135 groups:
1136 >>> print(nc['v'][:])
1137 [0 1 2 3 4]
1138 >>> nc.close()
1139 >>> # create an in-memory Dataset and retrieve memory buffer
1140 >>> # estimated size is 1028 bytes - this is actually only
1141 >>> # used if format is NETCDF3
1142 >>> # (ignored for NETCDF4/HDF5 files).
1143 >>> nc = Dataset('inmemory.nc', mode='w',memory=1028)
1144 >>> d = nc.createDimension('x',None)
1145 >>> v = nc.createVariable('v',numpy.int32,'x')
1146 >>> v[0:5] = numpy.arange(5)
1147 >>> nc_buf = nc.close() # close returns memoryview
1148 >>> print(type(nc_buf))
1149 <class 'memoryview'>
1150 >>> # save nc_buf to disk, read it back in and check.
1151 >>> with open('inmemory.nc', 'wb') as f:
1152 ... f.write(nc_buf)
1153 >>> nc = Dataset('inmemory.nc')
1154 >>> print(nc)
1155 <class 'netCDF4._netCDF4.Dataset'>
1156 root group (NETCDF4 data model, file format HDF5):
1157 dimensions(sizes): x(5)
1158 variables(dimensions): int32 v(x)
1159 groups:
1160 >>> print(nc['v'][:])
1161 [0 1 2 3 4]
1162 >>> nc.close()
1163
1164
1165 All of the code in this tutorial is available in `examples/tutorial.py`, except
1166 the parallel IO example, which is in `examples/mpi_example.py`.
1167 Unit tests are in the `test` directory.
1168
1169 **contact**: Jeffrey Whitaker <jeffrey.s.whitaker@noaa.gov>
1170
1171 **copyright**: 2008 by Jeffrey Whitaker.
1172
1173 **license**: Permission to use, copy, modify, and distribute this software and
1174 its documentation for any purpose and without fee is hereby granted,
1175 provided that the above copyright notice appear in all copies and that
1176 both the copyright notice and this permission notice appear in
1177 supporting documentation.
1178 THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
1179 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
1180 EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
1181 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
1182 USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
1183 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1184 PERFORMANCE OF THIS SOFTWARE.
1185 - - -
1186 """
1187
1188 # Make changes to this file, not the c-wrappers that Cython generates.
1189 from cpython.mem cimport PyMem_Malloc, PyMem_Free
1190 from cpython.buffer cimport PyObject_GetBuffer, PyBuffer_Release, PyBUF_SIMPLE, PyBUF_ANY_CONTIGUOUS
1191 from cpython.bytes cimport PyBytes_FromStringAndSize
1192
1193 # pure python utilities
1194 from .utils import (_StartCountStride, _quantize, _find_dim, _walk_grps,
1195 _out_array_shape, _sortbylist, _tostr, _safecast, _is_int)
1196 import sys
1197 if sys.version_info[0:2] < (3, 7):
1198 # Python 3.7+ guarantees order; older versions need OrderedDict
1199 from collections import OrderedDict
1200 try:
1201 from itertools import izip as zip
1202 except ImportError:
1203 # python3: zip is already python2's itertools.izip
1204 pass
1205
1206 __version__ = "1.5.5.1"
1207
1208 # Initialize numpy
1209 import posixpath
1210 from cftime import num2date, date2num, date2index
1211 import numpy
1212 import weakref
1213 import warnings
1214 from glob import glob
1215 from numpy import ma
1216 from libc.string cimport memcpy, memset
1217 from libc.stdlib cimport malloc, free
1218 import_array()
1219 include "constants.pyx"
1220 include "membuf.pyx"
1221 include "netCDF4.pxi"
1222 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
1223 cimport mpi4py.MPI as MPI
1224 from mpi4py.libmpi cimport MPI_Comm, MPI_Info, MPI_Comm_dup, MPI_Info_dup, \
1225 MPI_Comm_free, MPI_Info_free, MPI_INFO_NULL,\
1226 MPI_COMM_WORLD
1227 ctypedef MPI.Comm Comm
1228 ctypedef MPI.Info Info
1229 ELSE:
1230 ctypedef object Comm
1231 ctypedef object Info
1232
1233 # check for required version of netcdf-4 and hdf5.
1234
1235 def _gethdf5libversion():
1236 cdef unsigned int majorvers, minorvers, releasevers
1237 cdef herr_t ierr
1238 ierr = H5get_libversion( &majorvers, &minorvers, &releasevers)
1239 if ierr < 0:
1240 raise RuntimeError('error getting HDF5 library version info')
1241 return '%d.%d.%d' % (majorvers,minorvers,releasevers)
1242
1243 def getlibversion():
1244 """
1245 **`getlibversion()`**
1246
1247 returns a string describing the version of the netcdf library
1248 used to build the module, and when it was built.
1249 """
1250 return (<char *>nc_inq_libvers()).decode('ascii')
1251
1252 def get_chunk_cache():
1253 """
1254 **`get_chunk_cache()`**
1255
1256 return current netCDF chunk cache information in a tuple (size,nelems,preemption).
1257 See netcdf C library documentation for `nc_get_chunk_cache` for
1258 details. Values can be reset with `netCDF4.set_chunk_cache`."""
1259 cdef int ierr
1260 cdef size_t sizep, nelemsp
1261 cdef float preemptionp
1262 ierr = nc_get_chunk_cache(&sizep, &nelemsp, &preemptionp)
1263 _ensure_nc_success(ierr)
1264 size = sizep; nelems = nelemsp; preemption = preemptionp
1265 return (size,nelems,preemption)
1266
1267 def set_chunk_cache(size=None,nelems=None,preemption=None):
1268 """
1269 **`set_chunk_cache(self,size=None,nelems=None,preemption=None)`**
1270
1271 change netCDF4 chunk cache settings.
1272 See netcdf C library documentation for `nc_set_chunk_cache` for
1273 details."""
1274 cdef int ierr
1275 cdef size_t sizep, nelemsp
1276 cdef float preemptionp
1277 # reset chunk cache size, leave other parameters unchanged.
1278 size_orig, nelems_orig, preemption_orig = get_chunk_cache()
1279 if size is not None:
1280 sizep = size
1281 else:
1282 sizep = size_orig
1283 if nelems is not None:
1284 nelemsp = nelems
1285 else:
1286 nelemsp = nelems_orig
1287 if preemption is not None:
1288 preemptionp = preemption
1289 else:
1290 preemptionp = preemption_orig
1291 ierr = nc_set_chunk_cache(sizep,nelemsp, preemptionp)
1292 _ensure_nc_success(ierr)
1293
1294 __netcdf4libversion__ = getlibversion().split()[0]
1295 __hdf5libversion__ = _gethdf5libversion()
1296 __has_rename_grp__ = HAS_RENAME_GRP
1297 __has_nc_inq_path__ = HAS_NC_INQ_PATH
1298 __has_nc_inq_format_extended__ = HAS_NC_INQ_FORMAT_EXTENDED
1299 __has_cdf5_format__ = HAS_CDF5_FORMAT
1300 __has_nc_open_mem__ = HAS_NC_OPEN_MEM
1301 __has_nc_create_mem__ = HAS_NC_CREATE_MEM
1302 __has_parallel4_support__ = HAS_PARALLEL4_SUPPORT
1303 __has_pnetcdf_support__ = HAS_PNETCDF_SUPPORT
1304 _needsworkaround_issue485 = __netcdf4libversion__ < "4.4.0" or \
1305 (__netcdf4libversion__.startswith("4.4.0") and \
1306 "-development" in __netcdf4libversion__)
1307
1308 # issue warning for hdf5 1.10 (issue #549)
1309 if __netcdf4libversion__[0:5] < "4.4.1" and\
1310 __hdf5libversion__.startswith("1.10"):
1311 msg = """
1312 WARNING: Backwards incompatible files will be created with HDF5 1.10.x
1313 and netCDF < 4.4.1. Upgrading to netCDF4 >= 4.4.1 or downgrading to
1314 to HDF5 version 1.8.x is highly recommended
1315 (see https://github.com/Unidata/netcdf-c/issues/250)."""
1316 warnings.warn(msg)
1317
1318 # numpy data type <--> netCDF 4 data type mapping.
1319 _nptonctype = {'S1' : NC_CHAR,
1320 'i1' : NC_BYTE,
1321 'u1' : NC_UBYTE,
1322 'i2' : NC_SHORT,
1323 'u2' : NC_USHORT,
1324 'i4' : NC_INT,
1325 'u4' : NC_UINT,
1326 'i8' : NC_INT64,
1327 'u8' : NC_UINT64,
1328 'f4' : NC_FLOAT,
1329 'f8' : NC_DOUBLE}
1330
1331 # just integer types.
1332 _intnptonctype = {'i1' : NC_BYTE,
1333 'u1' : NC_UBYTE,
1334 'i2' : NC_SHORT,
1335 'u2' : NC_USHORT,
1336 'i4' : NC_INT,
1337 'u4' : NC_UINT,
1338 'i8' : NC_INT64,
1339 'u8' : NC_UINT64}
1340
1341 # create dictionary mapping string identifiers to netcdf format codes
1342 _format_dict = {'NETCDF3_CLASSIC' : NC_FORMAT_CLASSIC,
1343 'NETCDF4_CLASSIC' : NC_FORMAT_NETCDF4_CLASSIC,
1344 'NETCDF4' : NC_FORMAT_NETCDF4}
1345 # create dictionary mapping string identifiers to netcdf create format codes
1346 _cmode_dict = {'NETCDF3_CLASSIC' : NC_CLASSIC_MODEL,
1347 'NETCDF4_CLASSIC' : NC_CLASSIC_MODEL | NC_NETCDF4,
1348 'NETCDF4' : NC_NETCDF4}
1349 IF HAS_CDF5_FORMAT:
1350 # NETCDF3_64BIT deprecated, saved for compatibility.
1351 # use NETCDF3_64BIT_OFFSET instead.
1352 _format_dict['NETCDF3_64BIT_OFFSET'] = NC_FORMAT_64BIT_OFFSET
1353 _format_dict['NETCDF3_64BIT_DATA'] = NC_FORMAT_64BIT_DATA
1354 _cmode_dict['NETCDF3_64BIT_OFFSET'] = NC_64BIT_OFFSET
1355 _cmode_dict['NETCDF3_64BIT_DATA'] = NC_64BIT_DATA
1356 ELSE:
1357 _format_dict['NETCDF3_64BIT'] = NC_FORMAT_64BIT
1358 _cmode_dict['NETCDF3_64BIT'] = NC_64BIT_OFFSET
1359 # invert dictionary mapping
1360 _reverse_format_dict = dict((v, k) for k, v in _format_dict.iteritems())
1361 # add duplicate entry (NETCDF3_64BIT == NETCDF3_64BIT_OFFSET)
1362 IF HAS_CDF5_FORMAT:
1363 _format_dict['NETCDF3_64BIT'] = NC_FORMAT_64BIT_OFFSET
1364 _cmode_dict['NETCDF3_64BIT'] = NC_64BIT_OFFSET
1365 ELSE:
1366 _format_dict['NETCDF3_64BIT_OFFSET'] = NC_FORMAT_64BIT
1367 _cmode_dict['NETCDF3_64BIT_OFFSET'] = NC_64BIT_OFFSET
1368
1369 # default fill_value to numpy datatype mapping.
1370 default_fillvals = {#'S1':NC_FILL_CHAR,
1371 'S1':'\0',
1372 'i1':NC_FILL_BYTE,
1373 'u1':NC_FILL_UBYTE,
1374 'i2':NC_FILL_SHORT,
1375 'u2':NC_FILL_USHORT,
1376 'i4':NC_FILL_INT,
1377 'u4':NC_FILL_UINT,
1378 'i8':NC_FILL_INT64,
1379 'u8':NC_FILL_UINT64,
1380 'f4':NC_FILL_FLOAT,
1381 'f8':NC_FILL_DOUBLE}
1382
1383 # logical for native endian type.
1384 is_native_little = numpy.dtype('<f4').byteorder == '='
1385 is_native_big = numpy.dtype('>f4').byteorder == '='
1386
1387 # hard code these here, instead of importing from netcdf.h
1388 # so it will compile with versions <= 4.2.
1389 NC_DISKLESS = 0x0008
1390 # introduced in 4.6.2
1391 if __netcdf4libversion__[0:5] >= "4.6.2":
1392 NC_PERSIST = 0x4000
1393 else: # prior to 4.6.2 this flag doesn't work, so make the same as NC_DISKLESS
1394 NC_PERSIST = NC_DISKLESS
1395
1396 # next two lines do nothing, preserved for backwards compatibility.
1397 default_encoding = 'utf-8'
1398 unicode_error = 'replace'
1399
1400 python3 = sys.version_info[0] > 2
1401 if python3:
1402 buffer = memoryview
1403
1404 _nctonptype = {}
1405 for _key,_value in _nptonctype.items():
1406 _nctonptype[_value] = _key
1407 _supportedtypes = _nptonctype.keys()
1408 # make sure NC_CHAR points to S1
1409 _nctonptype[NC_CHAR]='S1'
1410
1411 # internal C functions.
1412
1413 cdef _get_att_names(int grpid, int varid):
1414 # Private function to get all the attribute names in a group
1415 cdef int ierr, numatts, n
1416 cdef char namstring[NC_MAX_NAME+1]
1417 if varid == NC_GLOBAL:
1418 with nogil:
1419 ierr = nc_inq_natts(grpid, &numatts)
1420 else:
1421 with nogil:
1422 ierr = nc_inq_varnatts(grpid, varid, &numatts)
1423 _ensure_nc_success(ierr, err_cls=AttributeError)
1424 attslist = []
1425 for n from 0 <= n < numatts:
1426 with nogil:
1427 ierr = nc_inq_attname(grpid, varid, n, namstring)
1428 _ensure_nc_success(ierr, err_cls=AttributeError)
1429 # attribute names are assumed to be utf-8
1430 attslist.append(namstring.decode('utf-8'))
1431 return attslist
1432
1433 cdef _get_att(grp, int varid, name, encoding='utf-8'):
1434 # Private function to get an attribute value given its name
1435 cdef int ierr, n, _grpid
1436 cdef size_t att_len
1437 cdef char *attname
1438 cdef nc_type att_type
1439 cdef ndarray value_arr
1440 # attribute names are assumed to be utf-8
1441 bytestr = _strencode(name,encoding='utf-8')
1442 attname = bytestr
1443 _grpid = grp._grpid
1444 with nogil:
1445 ierr = nc_inq_att(_grpid, varid, attname, &att_type, &att_len)
1446 _ensure_nc_success(ierr, err_cls=AttributeError)
1447 # attribute is a character or string ...
1448 if att_type == NC_CHAR:
1449 value_arr = numpy.empty(att_len,'S1')
1450 with nogil:
1451 ierr = nc_get_att_text(_grpid, varid, attname, <char *>value_arr.data)
1452 _ensure_nc_success(ierr, err_cls=AttributeError)
1453 if name == '_FillValue' and python3:
1454 # make sure _FillValue for character arrays is a byte on python 3
1455 # (issue 271).
1456 pstring = value_arr.tobytes()
1457 else:
1458 pstring =\
1459 value_arr.tobytes().decode(encoding,errors='replace').replace('\x00','')
1460 return pstring
1461 elif att_type == NC_STRING:
1462 values = <char**>PyMem_Malloc(sizeof(char*) * att_len)
1463 if not values:
1464 raise MemoryError()
1465 try:
1466 with nogil:
1467 ierr = nc_get_att_string(_grpid, varid, attname, values)
1468 _ensure_nc_success(ierr, err_cls=AttributeError)
1469 try:
1470 result = [values[j].decode(encoding,errors='replace').replace('\x00','')
1471 if values[j] else "" for j in range(att_len)]
1472 finally:
1473 ierr = nc_free_string(att_len, values) # free memory in netcdf C lib
1474 finally:
1475 PyMem_Free(values)
1476
1477 if len(result) == 1:
1478 return result[0]
1479 else:
1480 return result
1481 else:
1482 # a regular numeric or compound type.
1483 if att_type == NC_LONG:
1484 att_type = NC_INT
1485 try:
1486 type_att = _nctonptype[att_type] # see if it is a primitive type
1487 value_arr = numpy.empty(att_len,type_att)
1488 except KeyError:
1489 # check if it's a compound
1490 try:
1491 type_att = _read_compound(grp, att_type)
1492 value_arr = numpy.empty(att_len,type_att.dtype_view)
1493 except:
1494 # check if it's an enum
1495 try:
1496 type_att = _read_enum(grp, att_type)
1497 value_arr = numpy.empty(att_len,type_att.dtype)
1498 except:
1499 raise KeyError('attribute %s has unsupported datatype' % attname)
1500 with nogil:
1501 ierr = nc_get_att(_grpid, varid, attname, value_arr.data)
1502 _ensure_nc_success(ierr, err_cls=AttributeError)
1503 if value_arr.shape == ():
1504 # return a scalar for a scalar array
1505 return value_arr.item()
1506 elif att_len == 1:
1507 # return a scalar for a single element array
1508 return value_arr[0]
1509 else:
1510 return value_arr
1511
1512 def _set_default_format(object format='NETCDF4'):
1513 # Private function to set the netCDF file format
1514 if format not in _format_dict:
1515 raise ValueError("unrecognized format requested")
1516 nc_set_default_format(_format_dict[format], NULL)
1517
1518 cdef _get_format(int grpid):
1519 # Private function to get the netCDF file format
1520 cdef int ierr, formatp
1521 with nogil:
1522 ierr = nc_inq_format(grpid, &formatp)
1523 _ensure_nc_success(ierr)
1524 if formatp not in _reverse_format_dict:
1525 raise ValueError('format not supported by python interface')
1526 return _reverse_format_dict[formatp]
1527
1528 cdef _get_full_format(int grpid):
1529 # Private function to get the underlying disk format
1530 cdef int ierr, formatp, modep
1531 IF HAS_NC_INQ_FORMAT_EXTENDED:
1532 with nogil:
1533 ierr = nc_inq_format_extended(grpid, &formatp, &modep)
1534 _ensure_nc_success(ierr)
1535 if formatp == NC_FORMAT_NC3:
1536 return 'NETCDF3'
1537 elif formatp == NC_FORMAT_NC_HDF5:
1538 return 'HDF5'
1539 elif formatp == NC_FORMAT_NC_HDF4:
1540 return 'HDF4'
1541 elif formatp == NC_FORMAT_PNETCDF:
1542 return 'PNETCDF'
1543 elif formatp == NC_FORMAT_DAP2:
1544 return 'DAP2'
1545 elif formatp == NC_FORMAT_DAP4:
1546 return 'DAP4'
1547 elif formatp == NC_FORMAT_UNDEFINED:
1548 return 'UNDEFINED'
1549 ELSE:
1550 return 'UNDEFINED'
1551
1552 cdef issue485_workaround(int grpid, int varid, char* attname):
1553 # check to see if attribute already exists
1554 # and is NC_CHAR, if so delete it and re-create it
1555 # (workaround for issue #485). Fixed in C library
1556 # with commit 473259b7728120bb281c52359b1af50cca2fcb72,
1557 # which was included in 4.4.0-RC5.
1558 cdef nc_type att_type
1559 cdef size_t att_len
1560
1561 if not _needsworkaround_issue485:
1562 return
1563 ierr = nc_inq_att(grpid, varid, attname, &att_type, &att_len)
1564 if ierr == NC_NOERR and att_type == NC_CHAR:
1565 ierr = nc_del_att(grpid, varid, attname)
1566 _ensure_nc_success(ierr)
1567
1568
1569 cdef _set_att(grp, int varid, name, value,\
1570 nc_type xtype=-99, force_ncstring=False):
1571 # Private function to set an attribute name/value pair
1572 cdef int ierr, lenarr
1573 cdef char *attname
1574 cdef char *datstring
1575 cdef char **string_ptrs
1576 cdef ndarray value_arr
1577 bytestr = _strencode(name)
1578 attname = bytestr
1579 # put attribute value into a numpy array.
1580 value_arr = numpy.array(value)
1581 if value_arr.ndim > 1: # issue #841
1582 if __version__ > "1.4.2":
1583 raise ValueError('multi-dimensional array attributes not supported')
1584 else:
1585 msg = """
1586 Multi-dimensional array attributes are now deprecated.
1587 Instead of silently flattening the array, an error will
1588 be raised in the next release."""
1589 warnings.warn(msg,FutureWarning)
1590 # if array is 64 bit integers or
1591 # if 64-bit datatype not supported, cast to 32 bit integers.
1592 fmt = _get_format(grp._grpid)
1593 is_netcdf3 = fmt.startswith('NETCDF3') or fmt == 'NETCDF4_CLASSIC'
1594 if value_arr.dtype.str[1:] == 'i8' and ('i8' not in _supportedtypes or\
1595 (is_netcdf3 and fmt != 'NETCDF3_64BIT_DATA')):
1596 value_arr = value_arr.astype('i4')
1597 # if array contains ascii strings, write a text attribute (stored as bytes).
1598 # if array contains unicode strings, and data model is NETCDF4,
1599 # write as a string.
1600 if value_arr.dtype.char in ['S','U']:
1601 # force array of strings if array has multiple elements (issue #770)
1602 N = value_arr.size
1603 if N > 1: force_ncstring=True
1604 if not is_netcdf3 and force_ncstring and N > 1:
1605 string_ptrs = <char**>PyMem_Malloc(N * sizeof(char*))
1606 if not string_ptrs:
1607 raise MemoryError()
1608 try:
1609 strings = [_strencode(s) for s in value_arr.flat]
1610 for j in range(N):
1611 if len(strings[j]) == 0:
1612 strings[j] = _strencode('\x00')
1613 string_ptrs[j] = strings[j]
1614 issue485_workaround(grp._grpid, varid, attname)
1615 ierr = nc_put_att_string(grp._grpid, varid, attname, N, string_ptrs)
1616 finally:
1617 PyMem_Free(string_ptrs)
1618 else:
1619 # don't allow string array attributes in NETCDF3 files.
1620 if is_netcdf3 and N > 1:
1621 msg='array string attributes can only be written with NETCDF4'
1622 raise IOError(msg)
1623 if not value_arr.shape:
1624 dats = _strencode(value_arr.item())
1625 else:
1626 value_arr1 = value_arr.ravel()
1627 dats = _strencode(''.join(value_arr1.tolist()))
1628 lenarr = len(dats)
1629 datstring = dats
1630 if lenarr == 0:
1631 # write null byte
1632 lenarr=1; datstring = '\x00'
1633 if (force_ncstring or value_arr.dtype.char == 'U') and not is_netcdf3:
1634 # try to convert to ascii string, write as NC_CHAR
1635 # else it's a unicode string, write as NC_STRING (if NETCDF4)
1636 try:
1637 if force_ncstring: raise UnicodeError
1638 dats_ascii = _to_ascii(dats) # try to encode bytes as ascii string
1639 ierr = nc_put_att_text(grp._grpid, varid, attname, lenarr, datstring)
1640 except UnicodeError:
1641 issue485_workaround(grp._grpid, varid, attname)
1642 ierr = nc_put_att_string(grp._grpid, varid, attname, 1, &datstring)
1643 else:
1644 ierr = nc_put_att_text(grp._grpid, varid, attname, lenarr, datstring)
1645 _ensure_nc_success(ierr, err_cls=AttributeError)
1646 # a 'regular' array type ('f4','i4','f8' etc)
1647 else:
1648 if value_arr.dtype.kind == 'V': # compound attribute.
1649 xtype = _find_cmptype(grp,value_arr.dtype)
1650 elif value_arr.dtype.str[1:] not in _supportedtypes:
1651 raise TypeError, 'illegal data type for attribute %r, must be one of %s, got %s' % (attname, _supportedtypes, value_arr.dtype.str[1:])
1652 elif xtype == -99: # if xtype is not passed in as kwarg.
1653 xtype = _nptonctype[value_arr.dtype.str[1:]]
1654 lenarr = PyArray_SIZE(value_arr)
1655 ierr = nc_put_att(grp._grpid, varid, attname, xtype, lenarr, value_arr.data)
1656 _ensure_nc_success(ierr, err_cls=AttributeError)
1657
1658 cdef _get_types(group):
1659 # Private function to create `netCDF4.CompoundType`,
1660 # `netCDF4.VLType` or `netCDF4.EnumType` instances for all the
1661 # compound, VLEN or Enum types in a `netCDF4.Group` or `netCDF4.Dataset`.
1662 cdef int ierr, ntypes, classp, n, _grpid
1663 cdef nc_type xtype
1664 cdef nc_type *typeids
1665 cdef char namstring[NC_MAX_NAME+1]
1666 _grpid = group._grpid
1667 # get the number of user defined types in this group.
1668 with nogil:
1669 ierr = nc_inq_typeids(_grpid, &ntypes, NULL)
1670 _ensure_nc_success(ierr)
1671 if ntypes > 0:
1672 typeids = <nc_type *>malloc(sizeof(nc_type) * ntypes)
1673 with nogil:
1674 ierr = nc_inq_typeids(_grpid, &ntypes, typeids)
1675 _ensure_nc_success(ierr)
1676 # create empty dictionary for CompoundType instances.
1677 if sys.version_info[0:2] < (3, 7):
1678 cmptypes = OrderedDict()
1679 vltypes = OrderedDict()
1680 enumtypes = OrderedDict()
1681 else:
1682 cmptypes = dict()
1683 vltypes = dict()
1684 enumtypes = dict()
1685
1686 if ntypes > 0:
1687 for n from 0 <= n < ntypes:
1688 xtype = typeids[n]
1689 with nogil:
1690 ierr = nc_inq_user_type(_grpid, xtype, namstring,
1691 NULL,NULL,NULL,&classp)
1692 _ensure_nc_success(ierr)
1693 if classp == NC_COMPOUND: # a compound
1694 name = namstring.decode('utf-8')
1695 # read the compound type info from the file,
1696 # create a CompoundType instance from it.
1697 try:
1698 cmptype = _read_compound(group, xtype)
1699 except KeyError:
1700 msg='WARNING: unsupported Compound type, skipping...'
1701 warnings.warn(msg)
1702 continue
1703 cmptypes[name] = cmptype
1704 elif classp == NC_VLEN: # a vlen
1705 name = namstring.decode('utf-8')
1706 # read the VLEN type info from the file,
1707 # create a VLType instance from it.
1708 try:
1709 vltype = _read_vlen(group, xtype)
1710 except KeyError:
1711 msg='WARNING: unsupported VLEN type, skipping...'
1712 warnings.warn(msg)
1713 continue
1714 vltypes[name] = vltype
1715 elif classp == NC_ENUM: # an enum type
1716 name = namstring.decode('utf-8')
1717 # read the Enum type info from the file,
1718 # create a EnumType instance from it.
1719 try:
1720 enumtype = _read_enum(group, xtype)
1721 except KeyError:
1722 msg='WARNING: unsupported Enum type, skipping...'
1723 warnings.warn(msg)
1724 continue
1725 enumtypes[name] = enumtype
1726 free(typeids)
1727 return cmptypes, vltypes, enumtypes
1728
1729 cdef _get_dims(group):
1730 # Private function to create `netCDF4.Dimension` instances for all the
1731 # dimensions in a `netCDF4.Group` or Dataset
1732 cdef int ierr, numdims, n, _grpid
1733 cdef int *dimids
1734 cdef char namstring[NC_MAX_NAME+1]
1735 # get number of dimensions in this Group.
1736 _grpid = group._grpid
1737 with nogil:
1738 ierr = nc_inq_ndims(_grpid, &numdims)
1739 _ensure_nc_success(ierr)
1740 # create empty dictionary for dimensions.
1741 if sys.version_info[0:2] < (3, 7):
1742 dimensions = OrderedDict()
1743 else:
1744 dimensions = dict()
1745 if numdims > 0:
1746 dimids = <int *>malloc(sizeof(int) * numdims)
1747 if group.data_model == 'NETCDF4':
1748 with nogil:
1749 ierr = nc_inq_dimids(_grpid, &numdims, dimids, 0)
1750 _ensure_nc_success(ierr)
1751 else:
1752 for n from 0 <= n < numdims:
1753 dimids[n] = n
1754 for n from 0 <= n < numdims:
1755 with nogil:
1756 ierr = nc_inq_dimname(_grpid, dimids[n], namstring)
1757 _ensure_nc_success(ierr)
1758 name = namstring.decode('utf-8')
1759 dimensions[name] = Dimension(group, name, id=dimids[n])
1760 free(dimids)
1761 return dimensions
1762
1763 cdef _get_grps(group):
1764 # Private function to create `netCDF4.Group` instances for all the
1765 # groups in a `netCDF4.Group` or Dataset
1766 cdef int ierr, numgrps, n, _grpid
1767 cdef int *grpids
1768 cdef char namstring[NC_MAX_NAME+1]
1769 # get number of groups in this Group.
1770 _grpid = group._grpid
1771 with nogil:
1772 ierr = nc_inq_grps(_grpid, &numgrps, NULL)
1773 _ensure_nc_success(ierr)
1774 # create dictionary containing `netCDF4.Group` instances for groups in this group
1775 if sys.version_info[0:2] < (3, 7):
1776 groups = OrderedDict()
1777 else:
1778 groups = dict()
1779 if numgrps > 0:
1780 grpids = <int *>malloc(sizeof(int) * numgrps)
1781 with nogil:
1782 ierr = nc_inq_grps(_grpid, NULL, grpids)
1783 _ensure_nc_success(ierr)
1784 for n from 0 <= n < numgrps:
1785 with nogil:
1786 ierr = nc_inq_grpname(grpids[n], namstring)
1787 _ensure_nc_success(ierr)
1788 name = namstring.decode('utf-8')
1789 groups[name] = Group(group, name, id=grpids[n])
1790 free(grpids)
1791 return groups
1792
1793 cdef _get_vars(group):
1794 # Private function to create `netCDF4.Variable` instances for all the
1795 # variables in a `netCDF4.Group` or Dataset
1796 cdef int ierr, numvars, n, nn, numdims, varid, classp, iendian, _grpid
1797 cdef int *varids
1798 cdef int *dimids
1799 cdef nc_type xtype
1800 cdef char namstring[NC_MAX_NAME+1]
1801 cdef char namstring_cmp[NC_MAX_NAME+1]
1802 # get number of variables in this Group.
1803 _grpid = group._grpid
1804 with nogil:
1805 ierr = nc_inq_nvars(_grpid, &numvars)
1806 _ensure_nc_success(ierr, err_cls=AttributeError)
1807 # create empty dictionary for variables.
1808 if sys.version_info[0:2] < (3, 7):
1809 variables = OrderedDict()
1810 else:
1811 variables = dict()
1812 if numvars > 0:
1813 # get variable ids.
1814 varids = <int *>malloc(sizeof(int) * numvars)
1815 if group.data_model == 'NETCDF4':
1816 with nogil:
1817 ierr = nc_inq_varids(_grpid, &numvars, varids)
1818 _ensure_nc_success(ierr)
1819 else:
1820 for n from 0 <= n < numvars:
1821 varids[n] = n
1822 # loop over variables.
1823 for n from 0 <= n < numvars:
1824 varid = varids[n]
1825 # get variable name.
1826 with nogil:
1827 ierr = nc_inq_varname(_grpid, varid, namstring)
1828 _ensure_nc_success(ierr)
1829 name = namstring.decode('utf-8')
1830 # get variable type.
1831 with nogil:
1832 ierr = nc_inq_vartype(_grpid, varid, &xtype)
1833 _ensure_nc_success(ierr)
1834 # get endian-ness of variable.
1835 endianness = None
1836 with nogil:
1837 ierr = nc_inq_var_endian(_grpid, varid, &iendian)
1838 if ierr == NC_NOERR and iendian == NC_ENDIAN_LITTLE:
1839 endianness = '<'
1840 elif iendian == NC_ENDIAN_BIG:
1841 endianness = '>'
1842 # check to see if it is a supported user-defined type.
1843 try:
1844 datatype = _nctonptype[xtype]
1845 if endianness is not None:
1846 datatype = endianness + datatype
1847 except KeyError:
1848 if xtype == NC_STRING:
1849 datatype = str
1850 else:
1851 with nogil:
1852 ierr = nc_inq_user_type(_grpid, xtype, namstring_cmp,
1853 NULL, NULL, NULL, &classp)
1854 _ensure_nc_success(ierr)
1855 if classp == NC_COMPOUND: # a compound type
1856 # create CompoundType instance describing this compound type.
1857 try:
1858 datatype = _read_compound(group, xtype, endian=endianness)
1859 except KeyError:
1860 msg="WARNING: variable '%s' has unsupported compound datatype, skipping .." % name
1861 warnings.warn(msg)
1862 continue
1863 elif classp == NC_VLEN: # a compound type
1864 # create VLType instance describing this compound type.
1865 try:
1866 datatype = _read_vlen(group, xtype, endian=endianness)
1867 except KeyError:
1868 msg="WARNING: variable '%s' has unsupported VLEN datatype, skipping .." % name
1869 warnings.warn(msg)
1870 continue
1871 elif classp == NC_ENUM:
1872 # create EnumType instance describing this compound type.
1873 try:
1874 datatype = _read_enum(group, xtype, endian=endianness)
1875 except KeyError:
1876 msg="WARNING: variable '%s' has unsupported Enum datatype, skipping .." % name
1877 warnings.warn(msg)
1878 continue
1879 else:
1880 msg="WARNING: variable '%s' has unsupported datatype, skipping .." % name
1881 warnings.warn(msg)
1882 continue
1883 # get number of dimensions.
1884 with nogil:
1885 ierr = nc_inq_varndims(_grpid, varid, &numdims)
1886 _ensure_nc_success(ierr)
1887 dimids = <int *>malloc(sizeof(int) * numdims)
1888 # get dimension ids.
1889 with nogil:
1890 ierr = nc_inq_vardimid(_grpid, varid, dimids)
1891 _ensure_nc_success(ierr)
1892 # loop over dimensions, retrieve names.
1893 # if not found in current group, look in parents.
1894 # QUESTION: what if grp1 has a dimension named 'foo'
1895 # and so does it's parent - can a variable in grp1
1896 # use the 'foo' dimension from the parent?
1897 dimensions = []
1898 for nn from 0 <= nn < numdims:
1899 grp = group
1900 found = False
1901 while not found:
1902 for key, value in grp.dimensions.items():
1903 if value._dimid == dimids[nn]:
1904 dimensions.append(key)
1905 found = True
1906 break
1907 grp = grp.parent
1908 free(dimids)
1909 # create new variable instance.
1910 if endianness == '>':
1911 variables[name] = Variable(group, name, datatype, dimensions, id=varid, endian='big')
1912 elif endianness == '<':
1913 variables[name] = Variable(group, name, datatype, dimensions, id=varid, endian='little')
1914 else:
1915 variables[name] = Variable(group, name, datatype, dimensions, id=varid)
1916 free(varids) # free pointer holding variable ids.
1917 return variables
1918
1919 cdef _ensure_nc_success(ierr, err_cls=RuntimeError, filename=None):
1920 # print netcdf error message, raise error.
1921 if ierr != NC_NOERR:
1922 err_str = (<char *>nc_strerror(ierr)).decode('ascii')
1923 if issubclass(err_cls, EnvironmentError):
1924 raise err_cls(ierr, err_str, filename)
1925 else:
1926 raise err_cls(err_str)
1927
1928 # these are class attributes that
1929 # only exist at the python level (not in the netCDF file).
1930
1931 _private_atts = \
1932 ['_grpid','_grp','_varid','groups','dimensions','variables','dtype','data_model','disk_format',
1933 '_nunlimdim','path','parent','ndim','mask','scale','cmptypes','vltypes','enumtypes','_isprimitive',
1934 'file_format','_isvlen','_isenum','_iscompound','_cmptype','_vltype','_enumtype','name',
1935 '__orthogoral_indexing__','keepweakref','_has_lsd',
1936 '_buffer','chartostring','_use_get_vars','_ncstring_attrs__']
1937 __pdoc__ = {}
1938
1939 cdef class Dataset:
1940 """
1941 A netCDF `netCDF4.Dataset` is a collection of dimensions, groups, variables and
1942 attributes. Together they describe the meaning of data and relations among
1943 data fields stored in a netCDF file. See `netCDF4.Dataset.__init__` for more
1944 details.
1945
1946 A list of attribute names corresponding to global netCDF attributes
1947 defined for the `netCDF4.Dataset` can be obtained with the
1948 `netCDF4.Dataset.ncattrs` method.
1949 These attributes can be created by assigning to an attribute of the
1950 `netCDF4.Dataset` instance. A dictionary containing all the netCDF attribute
1951 name/value pairs is provided by the `__dict__` attribute of a
1952 `netCDF4.Dataset` instance.
1953
1954 The following class variables are read-only and should not be
1955 modified by the user.
1956
1957 **`dimensions`**: The `dimensions` dictionary maps the names of
1958 dimensions defined for the `netCDF4.Group` or `netCDF4.Dataset` to instances of the
1959 `netCDF4.Dimension` class.
1960
1961 **`variables`**: The `variables` dictionary maps the names of variables
1962 defined for this `netCDF4.Dataset` or `netCDF4.Group` to instances of the
1963 `netCDF4.Variable` class.
1964
1965 **`groups`**: The groups dictionary maps the names of groups created for
1966 this `netCDF4.Dataset` or `netCDF4.Group` to instances of the `netCDF4.Group` class (the
1967 `netCDF4.Dataset` class is simply a special case of the `netCDF4.Group` class which
1968 describes the root group in the netCDF4 file).
1969
1970 **`cmptypes`**: The `cmptypes` dictionary maps the names of
1971 compound types defined for the `netCDF4.Group` or `netCDF4.Dataset` to instances of the
1972 `netCDF4.CompoundType` class.
1973
1974 **`vltypes`**: The `vltypes` dictionary maps the names of
1975 variable-length types defined for the `netCDF4.Group` or `netCDF4.Dataset` to instances
1976 of the `netCDF4.VLType` class.
1977
1978 **`enumtypes`**: The `enumtypes` dictionary maps the names of
1979 Enum types defined for the `netCDF4.Group` or `netCDF4.Dataset` to instances
1980 of the `netCDF4.EnumType` class.
1981
1982 **`data_model`**: `data_model` describes the netCDF
1983 data model version, one of `NETCDF3_CLASSIC`, `NETCDF4`,
1984 `NETCDF4_CLASSIC`, `NETCDF3_64BIT_OFFSET` or `NETCDF3_64BIT_DATA`.
1985
1986 **`file_format`**: same as `data_model`, retained for backwards compatibility.
1987
1988 **`disk_format`**: `disk_format` describes the underlying
1989 file format, one of `NETCDF3`, `HDF5`, `HDF4`,
1990 `PNETCDF`, `DAP2`, `DAP4` or `UNDEFINED`. Only available if using
1991 netcdf C library version >= 4.3.1, otherwise will always return
1992 `UNDEFINED`.
1993
1994 **`parent`**: `parent` is a reference to the parent
1995 `netCDF4.Group` instance. `None` for the root group or `netCDF4.Dataset`
1996 instance.
1997
1998 **`path`**: `path` shows the location of the `netCDF4.Group` in
1999 the `netCDF4.Dataset` in a unix directory format (the names of groups in the
2000 hierarchy separated by backslashes). A `netCDF4.Dataset` instance is the root
2001 group, so the path is simply `'/'`.
2002
2003 **`keepweakref`**: If `True`, child Dimension and Variables objects only keep weak
2004 references to the parent Dataset or Group.
2005
2006 **`_ncstring_attrs__`**: If `True`, all text attributes will be written as variable-length
2007 strings.
2008 """
2009 cdef object __weakref__, _inmemory
2010 cdef public int _grpid
2011 cdef public int _isopen
2012 cdef Py_buffer _buffer
2013 cdef public groups, dimensions, variables, disk_format, path, parent,\
2014 file_format, data_model, cmptypes, vltypes, enumtypes, __orthogonal_indexing__, \
2015 keepweakref, _ncstring_attrs__
2016 # Docstrings for class variables (used by pdoc).
2017 __pdoc__['Dataset.dimensions']=\
2018 """The `dimensions` dictionary maps the names of
2019 dimensions defined for the `netCDF4.Group` or `netCDF4.Dataset` to instances of the
2020 `netCDF4.Dimension` class."""
2021 __pdoc__['Dataset.variables']=\
2022 """The `variables` dictionary maps the names of variables
2023 defined for this `netCDF4.Dataset` or `netCDF4.Group` to instances of the `netCDF4.Variable`
2024 class."""
2025 __pdoc__['Dataset.groups']=\
2026 """The groups dictionary maps the names of groups created for
2027 this `netCDF4.Dataset` or `netCDF4.Group` to instances of the `netCDF4.Group` class (the
2028 `netCDF4.Dataset` class is simply a special case of the `netCDF4.Group` class which
2029 describes the root group in the netCDF4 file)."""
2030 __pdoc__['Dataset.cmptypes']=\
2031 """The `cmptypes` dictionary maps the names of
2032 compound types defined for the `netCDF4.Group` or `netCDF4.Dataset` to instances of the
2033 `netCDF4.CompoundType` class."""
2034 __pdoc__['Dataset.vltypes']=\
2035 """The `vltypes` dictionary maps the names of
2036 variable-length types defined for the `netCDF4.Group` or `netCDF4.Dataset` to instances of the
2037 `netCDF4.VLType` class."""
2038 __pdoc__['Dataset.enumtypes']=\
2039 """The `enumtypes` dictionary maps the names of
2040 Enum types defined for the `netCDF4.Group` or `netCDF4.Dataset` to instances of the
2041 `netCDF4.EnumType` class."""
2042 __pdoc__['Dataset.data_model']=\
2043 """`data_model` describes the netCDF
2044 data model version, one of `NETCDF3_CLASSIC`, `NETCDF4`,
2045 `NETCDF4_CLASSIC`, `NETCDF3_64BIT_OFFSET` or `NETCDF3_64BIT_DATA`."""
2046 __pdoc__['Dataset.file_format']=\
2047 """same as `data_model`, retained for backwards compatibility."""
2048 __pdoc__['Dataset.disk_format']=\
2049 """`disk_format` describes the underlying
2050 file format, one of `NETCDF3`, `HDF5`, `HDF4`,
2051 `PNETCDF`, `DAP2`, `DAP4` or `UNDEFINED`. Only available if using
2052 netcdf C library version >= 4.3.1, otherwise will always return
2053 `UNDEFINED`."""
2054 __pdoc__['Dataset.parent']=\
2055 """`parent` is a reference to the parent
2056 `netCDF4.Group` instance. `None` for the root group or `netCDF4.Dataset` instance"""
2057 __pdoc__['Dataset.path']=\
2058 """`path` shows the location of the `netCDF4.Group` in
2059 the `netCDF4.Dataset` in a unix directory format (the names of groups in the
2060 hierarchy separated by backslashes). A `netCDF4.Dataset` instance is the root
2061 group, so the path is simply `'/'`."""
2062 __pdoc__['Dataset.keepweakref']=\
2063 """If `True`, child Dimension and Variables objects only keep weak references to
2064 the parent Dataset or Group."""
2065
2066 def __init__(self, filename, mode='r', clobber=True, format='NETCDF4',
2067 diskless=False, persist=False, keepweakref=False,
2068 memory=None, encoding=None, parallel=False,
2069 Comm comm=None, Info info=None, **kwargs):
2070 """
2071 **`__init__(self, filename, mode="r", clobber=True, diskless=False,
2072 persist=False, keepweakref=False, memory=None, encoding=None,
2073 parallel=False, comm=None, info=None, format='NETCDF4')`**
2074
2075 `netCDF4.Dataset` constructor.
2076
2077 **`filename`**: Name of netCDF file to hold dataset. Can also
2078 be a python 3 pathlib instance or the URL of an OpenDAP dataset. When memory is
2079 set this is just used to set the `filepath()`.
2080
2081 **`mode`**: access mode. `r` means read-only; no data can be
2082 modified. `w` means write; a new file is created, an existing file with
2083 the same name is deleted. `a` and `r+` mean append (in analogy with
2084 serial files); an existing file is opened for reading and writing.
2085 Appending `s` to modes `r`, `w`, `r+` or `a` will enable unbuffered shared
2086 access to `NETCDF3_CLASSIC`, `NETCDF3_64BIT_OFFSET` or
2087 `NETCDF3_64BIT_DATA` formatted files.
2088 Unbuffered access may be useful even if you don't need shared
2089 access, since it may be faster for programs that don't access data
2090 sequentially. This option is ignored for `NETCDF4` and `NETCDF4_CLASSIC`
2091 formatted files.
2092
2093 **`clobber`**: if `True` (default), opening a file with `mode='w'`
2094 will clobber an existing file with the same name. if `False`, an
2095 exception will be raised if a file with the same name already exists.
2096
2097 **`format`**: underlying file format (one of `'NETCDF4',
2098 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC'`, `'NETCDF3_64BIT_OFFSET'` or
2099 `'NETCDF3_64BIT_DATA'`.
2100 Only relevant if `mode = 'w'` (if `mode = 'r','a'` or `'r+'` the file format
2101 is automatically detected). Default `'NETCDF4'`, which means the data is
2102 stored in an HDF5 file, using netCDF 4 API features. Setting
2103 `format='NETCDF4_CLASSIC'` will create an HDF5 file, using only netCDF 3
2104 compatible API features. netCDF 3 clients must be recompiled and linked
2105 against the netCDF 4 library to read files in `NETCDF4_CLASSIC` format.
2106 `'NETCDF3_CLASSIC'` is the classic netCDF 3 file format that does not
2107 handle 2+ Gb files. `'NETCDF3_64BIT_OFFSET'` is the 64-bit offset
2108 version of the netCDF 3 file format, which fully supports 2+ GB files, but
2109 is only compatible with clients linked against netCDF version 3.6.0 or
2110 later. `'NETCDF3_64BIT_DATA'` is the 64-bit data version of the netCDF 3
2111 file format, which supports 64-bit dimension sizes plus unsigned and
2112 64 bit integer data types, but is only compatible with clients linked against
2113 netCDF version 4.4.0 or later.
2114
2115 **`diskless`**: If `True`, create diskless (in-core) file.
2116 This is a feature added to the C library after the
2117 netcdf-4.2 release. If you need to access the memory buffer directly,
2118 use the in-memory feature instead (see `memory` kwarg).
2119
2120 **`persist`**: if `diskless=True`, persist file to disk when closed
2121 (default `False`).
2122
2123 **`keepweakref`**: if `True`, child Dimension and Variable instances will keep weak
2124 references to the parent Dataset or Group object. Default is `False`, which
2125 means strong references will be kept. Having Dimension and Variable instances
2126 keep a strong reference to the parent Dataset instance, which in turn keeps a
2127 reference to child Dimension and Variable instances, creates circular references.
2128 Circular references complicate garbage collection, which may mean increased
2129 memory usage for programs that create may Dataset instances with lots of
2130 Variables. It also will result in the Dataset object never being deleted, which
2131 means it may keep open files alive as well. Setting `keepweakref=True` allows
2132 Dataset instances to be garbage collected as soon as they go out of scope, potentially
2133 reducing memory usage and open file handles. However, in many cases this is not
2134 desirable, since the associated Variable instances may still be needed, but are
2135 rendered unusable when the parent Dataset instance is garbage collected.
2136
2137 **`memory`**: if not `None`, create or open an in-memory Dataset.
2138 If mode = 'r', the memory kwarg must contain a memory buffer object
2139 (an object that supports the python buffer interface).
2140 The Dataset will then be created with contents taken from this block of memory.
2141 If mode = 'w', the memory kwarg should contain the anticipated size
2142 of the Dataset in bytes (used only for NETCDF3 files). A memory
2143 buffer containing a copy of the Dataset is returned by the
2144 `Dataset.close` method. Requires netcdf-c version 4.4.1 for mode='r,
2145 netcdf-c 4.6.2 for mode='w'. To persist the file to disk, the raw
2146 bytes from the returned buffer can be written into a binary file.
2147 The Dataset can also be re-opened using this memory buffer.
2148
2149 **`encoding`**: encoding used to encode filename string into bytes.
2150 Default is None (`sys.getdefaultfileencoding()` is used).
2151
2152 **`parallel`**: open for parallel access using MPI (requires mpi4py and
2153 parallel-enabled netcdf-c and hdf5 libraries). Default is `False`. If
2154 `True`, `comm` and `info` kwargs may also be specified.
2155
2156 **`comm`**: MPI_Comm object for parallel access. Default `None`, which
2157 means MPI_COMM_WORLD will be used. Ignored if `parallel=False`.
2158
2159 **`info`**: MPI_Info object for parallel access. Default `None`, which
2160 means MPI_INFO_NULL will be used. Ignored if `parallel=False`.
2161 """
2162 cdef int grpid, ierr, numgrps, numdims, numvars
2163 cdef size_t initialsize
2164 cdef char *path
2165 cdef char namstring[NC_MAX_NAME+1]
2166 cdef int cmode
2167 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2168 cdef MPI_Comm mpicomm
2169 cdef MPI_Info mpiinfo
2170
2171 memset(&self._buffer, 0, sizeof(self._buffer))
2172
2173 # flag to indicate that Variables in this Dataset support orthogonal indexing.
2174 self.__orthogonal_indexing__ = True
2175 if diskless and __netcdf4libversion__ < '4.2.1':
2176 #diskless = False # don't raise error, instead silently ignore
2177 raise ValueError('diskless mode requires netcdf lib >= 4.2.1, you have %s' % __netcdf4libversion__)
2178 # convert filename into string (from os.path object for example),
2179 # encode into bytes.
2180 if encoding is None:
2181 encoding = sys.getfilesystemencoding()
2182 bytestr = _strencode(_tostr(filename), encoding=encoding)
2183 path = bytestr
2184
2185 if memory is not None and mode not in ['r','w']:
2186 msg='if memory kwarg specified, mode must be \'r\' or \'w\''
2187 raise ValueError(msg)
2188
2189 if parallel:
2190 IF HAS_PARALLEL4_SUPPORT != 1 and HAS_PNETCDF_SUPPORT != 1:
2191 msg='parallel mode requires MPI enabled netcdf-c'
2192 raise ValueError(msg)
2193 ELSE:
2194 parallel_formats = []
2195 IF HAS_PARALLEL4_SUPPORT:
2196 parallel_formats += ['NETCDF4','NETCDF4_CLASSIC']
2197 IF HAS_PNETCDF_SUPPORT:
2198 parallel_formats += ['NETCDF3_CLASSIC',
2199 'NETCDF3_64BIT_OFFSET',
2200 'NETCDF3_64BIT_DATA',
2201 'NETCDF3_64BIT']
2202 if format not in parallel_formats:
2203 msg='parallel mode only works with the following formats: ' + ' '.join(parallel_formats)
2204 raise ValueError(msg)
2205 if comm is not None:
2206 mpicomm = comm.ob_mpi
2207 else:
2208 mpicomm = MPI_COMM_WORLD
2209 if info is not None:
2210 mpiinfo = info.ob_mpi
2211 else:
2212 mpiinfo = MPI_INFO_NULL
2213 cmode = NC_MPIIO | _cmode_dict[format]
2214
2215 self._inmemory = False
2216 if mode == 'w':
2217 _set_default_format(format=format)
2218 if memory is not None:
2219 # if memory is not None and mode='w', memory
2220 # kwarg is interpreted as advisory size.
2221 IF HAS_NC_CREATE_MEM:
2222 initialsize = <size_t>memory
2223 ierr = nc_create_mem(path, 0, initialsize, &grpid)
2224 self._inmemory = True # checked in close method
2225 ELSE:
2226 msg = """
2227 nc_create_mem functionality not enabled. To enable, install Cython, make sure you have
2228 version 4.6.2 or higher of the netcdf C lib, and rebuild netcdf4-python."""
2229 raise ValueError(msg)
2230 else:
2231 if clobber:
2232 if parallel:
2233 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2234 ierr = nc_create_par(path, NC_CLOBBER | cmode, \
2235 mpicomm, mpiinfo, &grpid)
2236 ELSE:
2237 pass
2238 elif diskless:
2239 if persist:
2240 ierr = nc_create(path, NC_WRITE | NC_CLOBBER |
2241 NC_DISKLESS | NC_PERSIST, &grpid)
2242 else:
2243 ierr = nc_create(path, NC_CLOBBER | NC_DISKLESS , &grpid)
2244 else:
2245 ierr = nc_create(path, NC_CLOBBER, &grpid)
2246 else:
2247 if parallel:
2248 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2249 ierr = nc_create_par(path, NC_NOCLOBBER | cmode, \
2250 mpicomm, mpiinfo, &grpid)
2251 ELSE:
2252 pass
2253 elif diskless:
2254 if persist:
2255 ierr = nc_create(path, NC_WRITE | NC_NOCLOBBER |
2256 NC_DISKLESS | NC_PERSIST , &grpid)
2257 else:
2258 ierr = nc_create(path, NC_NOCLOBBER | NC_DISKLESS , &grpid)
2259 else:
2260 ierr = nc_create(path, NC_NOCLOBBER, &grpid)
2261 # reset default format to netcdf3 - this is a workaround
2262 # for issue 170 (nc_open'ing a DAP dataset after switching
2263 # format to NETCDF4). This bug should be fixed in version
2264 # 4.3.0 of the netcdf library (add a version check here?).
2265 # **this causes parallel mode to fail when both hdf5-parallel and
2266 # pnetcdf are enabled - issue #820 **
2267 #_set_default_format(format='NETCDF3_64BIT_OFFSET')
2268 elif mode in ('r', 'rs'):
2269 if memory is not None:
2270 IF HAS_NC_OPEN_MEM:
2271 # Store reference to memory
2272 result = PyObject_GetBuffer(memory, &self._buffer, PyBUF_SIMPLE | PyBUF_ANY_CONTIGUOUS)
2273 if result != 0:
2274 raise ValueError("Unable to retrieve Buffer from %s" % (memory,))
2275
2276 ierr = nc_open_mem(<char *>path, 0, self._buffer.len, <void *>self._buffer.buf, &grpid)
2277 ELSE:
2278 msg = """
2279 nc_open_mem functionality not enabled. To enable, install Cython, make sure you have
2280 version 4.4.1 or higher of the netcdf C lib, and rebuild netcdf4-python."""
2281 raise ValueError(msg)
2282 elif parallel:
2283 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2284 ierr = nc_open_par(path, NC_NOWRITE | NC_MPIIO, \
2285 mpicomm, mpiinfo, &grpid)
2286 ELSE:
2287 pass
2288 elif diskless:
2289 ierr = nc_open(path, NC_NOWRITE | NC_DISKLESS, &grpid)
2290 else:
2291 if mode == 'rs':
2292 # NC_SHARE is very important for speed reading
2293 # large netcdf3 files with a record dimension
2294 # (pull request #902).
2295 ierr = nc_open(path, NC_NOWRITE | NC_SHARE, &grpid)
2296 else:
2297 ierr = nc_open(path, NC_NOWRITE, &grpid)
2298 elif mode == 'r+' or mode == 'a':
2299 if parallel:
2300 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2301 ierr = nc_open_par(path, NC_WRITE | NC_MPIIO, \
2302 mpicomm, mpiinfo, &grpid)
2303 ELSE:
2304 pass
2305 elif diskless:
2306 ierr = nc_open(path, NC_WRITE | NC_DISKLESS, &grpid)
2307 else:
2308 ierr = nc_open(path, NC_WRITE, &grpid)
2309 elif mode == 'as' or mode == 'r+s':
2310 if parallel:
2311 # NC_SHARE ignored
2312 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2313 ierr = nc_open_par(path, NC_WRITE | NC_MPIIO, \
2314 mpicomm, mpiinfo, &grpid)
2315 ELSE:
2316 pass
2317 elif diskless:
2318 ierr = nc_open(path, NC_SHARE | NC_DISKLESS, &grpid)
2319 else:
2320 ierr = nc_open(path, NC_SHARE, &grpid)
2321 elif mode == 'ws':
2322 _set_default_format(format=format)
2323 if clobber:
2324 if parallel:
2325 # NC_SHARE ignored
2326 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2327 ierr = nc_create_par(path, NC_CLOBBER | cmode, \
2328 mpicomm, mpiinfo, &grpid)
2329 ELSE:
2330 pass
2331 elif diskless:
2332 if persist:
2333 ierr = nc_create(path, NC_WRITE | NC_SHARE | NC_CLOBBER | NC_DISKLESS , &grpid)
2334 else:
2335 ierr = nc_create(path, NC_SHARE | NC_CLOBBER | NC_DISKLESS , &grpid)
2336 else:
2337 ierr = nc_create(path, NC_SHARE | NC_CLOBBER, &grpid)
2338 else:
2339 if parallel:
2340 # NC_SHARE ignored
2341 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2342 ierr = nc_create_par(path, NC_NOCLOBBER | cmode, \
2343 mpicomm, mpiinfo, &grpid)
2344 ELSE:
2345 pass
2346 elif diskless:
2347 if persist:
2348 ierr = nc_create(path, NC_WRITE | NC_SHARE | NC_NOCLOBBER | NC_DISKLESS , &grpid)
2349 else:
2350 ierr = nc_create(path, NC_SHARE | NC_NOCLOBBER | NC_DISKLESS , &grpid)
2351 else:
2352 ierr = nc_create(path, NC_SHARE | NC_NOCLOBBER, &grpid)
2353 else:
2354 raise ValueError("mode must be 'w', 'r', 'a' or 'r+', got '%s'" % mode)
2355
2356 _ensure_nc_success(ierr, err_cls=IOError, filename=path)
2357
2358 # data model and file format attributes
2359 self.data_model = _get_format(grpid)
2360 # data_model attribute used to be file_format (versions < 1.0.8), retain
2361 # file_format for backwards compatibility.
2362 self.file_format = self.data_model
2363 self.disk_format = _get_full_format(grpid)
2364 # diskless read access only works with NETCDF_CLASSIC (for now)
2365 #ncopen = mode.startswith('a') or mode.startswith('r')
2366 #if diskless and self.data_model != 'NETCDF3_CLASSIC' and ncopen:
2367 # raise ValueError("diskless access only supported for NETCDF3_CLASSIC format")
2368 self._grpid = grpid
2369 self._isopen = 1
2370 self.path = '/'
2371 self.parent = None
2372 self.keepweakref = keepweakref
2373 self._ncstring_attrs__ = False
2374 # get compound, vlen and enum types in the root Group.
2375 self.cmptypes, self.vltypes, self.enumtypes = _get_types(self)
2376 # get dimensions in the root group.
2377 self.dimensions = _get_dims(self)
2378 # get variables in the root Group.
2379 self.variables = _get_vars(self)
2380 # get groups in the root Group.
2381 if self.data_model == 'NETCDF4':
2382 self.groups = _get_grps(self)
2383 else:
2384 if sys.version_info[0:2] < (3, 7):
2385 self.groups = OrderedDict()
2386 else:
2387 self.groups = dict()
2388
2389 # these allow Dataset objects to be used via a "with" statement.
2390 def __enter__(self):
2391 return self
2392 def __exit__(self,atype,value,traceback):
2393 self.close()
2394
2395 def __getitem__(self, elem):
2396 # return variable or group defined in relative path.
2397 # split out group names in unix path.
2398 elem = posixpath.normpath(elem)
2399 # last name in path, could be a variable or group
2400 dirname, lastname = posixpath.split(elem)
2401 nestedgroups = dirname.split('/')
2402 group = self
2403 # iterate over groups in path.
2404 for g in nestedgroups:
2405 if g: group = group.groups[g]
2406 # return last one, either a group or a variable.
2407 if lastname in group.groups:
2408 return group.groups[lastname]
2409 elif lastname in group.variables:
2410 return group.variables[lastname]
2411 else:
2412 raise IndexError('%s not found in %s' % (lastname,group.path))
2413
2414 def filepath(self,encoding=None):
2415 """
2416 **`filepath(self,encoding=None)`**
2417
2418 Get the file system path (or the opendap URL) which was used to
2419 open/create the Dataset. Requires netcdf >= 4.1.2. The path
2420 is decoded into a string using `sys.getfilesystemencoding()` by default, this can be
2421 changed using the `encoding` kwarg."""
2422 cdef int ierr
2423 cdef size_t pathlen
2424 cdef char *c_path
2425 if encoding is None:
2426 encoding = sys.getfilesystemencoding()
2427 IF HAS_NC_INQ_PATH:
2428 with nogil:
2429 ierr = nc_inq_path(self._grpid, &pathlen, NULL)
2430 _ensure_nc_success(ierr)
2431
2432 c_path = <char *>malloc(sizeof(char) * (pathlen + 1))
2433 if not c_path:
2434 raise MemoryError()
2435 try:
2436 with nogil:
2437 ierr = nc_inq_path(self._grpid, &pathlen, c_path)
2438 _ensure_nc_success(ierr)
2439
2440 py_path = c_path[:pathlen] # makes a copy of pathlen bytes from c_string
2441 finally:
2442 free(c_path)
2443 return py_path.decode(encoding)
2444 ELSE:
2445 msg = """
2446 filepath method not enabled. To enable, install Cython, make sure you have
2447 version 4.1.2 or higher of the netcdf C lib, and rebuild netcdf4-python."""
2448 raise ValueError(msg)
2449
2450 def __repr__(self):
2451 if python3:
2452 return self.__unicode__()
2453 else:
2454 return unicode(self).encode('utf-8')
2455
2456 def __unicode__(self):
2457 ncdump = [repr(type(self))]
2458 dimnames = tuple(_tostr(dimname)+'(%s)'%len(self.dimensions[dimname])\
2459 for dimname in self.dimensions.keys())
2460 if python3:
2461 varnames = tuple(\
2462 [_tostr(self.variables[varname].dtype)+' '+_tostr(varname)+
2463 ((_tostr(self.variables[varname].dimensions)).replace(",)",")")).replace("'","")
2464 for varname in self.variables.keys()])
2465 else: # don't try to remove quotes in python2
2466 varnames = tuple(\
2467 [_tostr(self.variables[varname].dtype)+' '+_tostr(varname)+
2468 (_tostr(self.variables[varname].dimensions)).replace(",)",")")
2469 for varname in self.variables.keys()])
2470 grpnames = tuple(_tostr(grpname) for grpname in self.groups.keys())
2471 if self.path == '/':
2472 ncdump.append('root group (%s data model, file format %s):' %
2473 (self.data_model, self.disk_format))
2474 else:
2475 ncdump.append('group %s:' % self.path)
2476 for name in self.ncattrs():
2477 ncdump.append(' %s: %s' % (name, self.getncattr(name)))
2478 ncdump.append(' dimensions(sizes): %s' % ', '.join(dimnames))
2479 ncdump.append(' variables(dimensions): %s' % ', '.join(varnames))
2480 ncdump.append(' groups: %s' % ', '.join(grpnames))
2481 return '\n'.join(ncdump)
2482
2483 def _close(self, check_err):
2484 cdef int ierr = nc_close(self._grpid)
2485
2486 if check_err:
2487 _ensure_nc_success(ierr)
2488
2489 self._isopen = 0 # indicates file already closed, checked by __dealloc__
2490
2491 # Only release buffer if close succeeded
2492 # per impl of PyBuffer_Release: https://github.com/python/cpython/blob/master/Objects/abstract.c#L667
2493 # view.obj is checked, ref on obj is decremented and obj will be null'd out
2494 PyBuffer_Release(&self._buffer)
2495
2496 IF HAS_NC_CREATE_MEM:
2497 def _close_mem(self, check_err):
2498 cdef int ierr
2499 cdef NC_memio memio
2500 ierr = nc_close_memio(self._grpid, &memio)
2501
2502 if check_err:
2503 _ensure_nc_success(ierr)
2504
2505 self._isopen = 0
2506 PyBuffer_Release(&self._buffer)
2507
2508 # membuf_fromptr from membuf.pyx - creates a python memoryview
2509 # from a raw pointer without making a copy.
2510 return memview_fromptr(<char *>memio.memory, memio.size)
2511
2512
2513 def close(self):
2514 """
2515 **`close(self)`**
2516
2517 Close the Dataset.
2518 """
2519 IF HAS_NC_CREATE_MEM:
2520 if self._inmemory:
2521 return self._close_mem(True)
2522 else:
2523 self._close(True)
2524 ELSE:
2525 self._close(True)
2526
2527 def isopen(self):
2528 """
2529 **`close(self)`**
2530
2531 is the Dataset open or closed?
2532 """
2533 return bool(self._isopen)
2534
2535 def __dealloc__(self):
2536 # close file when there are no references to object left
2537 if self._isopen:
2538 self._close(False)
2539
2540 def __reduce__(self):
2541 # raise error is user tries to pickle a Dataset object.
2542 raise NotImplementedError('Dataset is not picklable')
2543
2544 def sync(self):
2545 """
2546 **`sync(self)`**
2547
2548 Writes all buffered data in the `netCDF4.Dataset` to the disk file."""
2549 _ensure_nc_success(nc_sync(self._grpid))
2550
2551 def _redef(self):
2552 cdef int ierr
2553 ierr = nc_redef(self._grpid)
2554
2555 def _enddef(self):
2556 cdef int ierr
2557 ierr = nc_enddef(self._grpid)
2558
2559 def set_fill_on(self):
2560 """
2561 **`set_fill_on(self)`**
2562
2563 Sets the fill mode for a `netCDF4.Dataset` open for writing to `on`.
2564
2565 This causes data to be pre-filled with fill values. The fill values can be
2566 controlled by the variable's `_Fill_Value` attribute, but is usually
2567 sufficient to the use the netCDF default `_Fill_Value` (defined
2568 separately for each variable type). The default behavior of the netCDF
2569 library corresponds to `set_fill_on`. Data which are equal to the
2570 `_Fill_Value` indicate that the variable was created, but never written
2571 to."""
2572 cdef int oldmode
2573 _ensure_nc_success(nc_set_fill(self._grpid, NC_FILL, &oldmode))
2574
2575 def set_fill_off(self):
2576 """
2577 **`set_fill_off(self)`**
2578
2579 Sets the fill mode for a `netCDF4.Dataset` open for writing to `off`.
2580
2581 This will prevent the data from being pre-filled with fill values, which
2582 may result in some performance improvements. However, you must then make
2583 sure the data is actually written before being read."""
2584 cdef int oldmode
2585 _ensure_nc_success(nc_set_fill(self._grpid, NC_NOFILL, &oldmode))
2586
2587 def createDimension(self, dimname, size=None):
2588 """
2589 **`createDimension(self, dimname, size=None)`**
2590
2591 Creates a new dimension with the given `dimname` and `size`.
2592
2593 `size` must be a positive integer or `None`, which stands for
2594 "unlimited" (default is `None`). Specifying a size of 0 also
2595 results in an unlimited dimension. The return value is the `netCDF4.Dimension`
2596 class instance describing the new dimension. To determine the current
2597 maximum size of the dimension, use the `len` function on the `netCDF4.Dimension`
2598 instance. To determine if a dimension is 'unlimited', use the
2599 `netCDF4.Dimension.isunlimited` method of the `netCDF4.Dimension` instance."""
2600 self.dimensions[dimname] = Dimension(self, dimname, size=size)
2601 return self.dimensions[dimname]
2602
2603 def renameDimension(self, oldname, newname):
2604 """
2605 **`renameDimension(self, oldname, newname)`**
2606
2607 rename a `netCDF4.Dimension` named `oldname` to `newname`."""
2608 cdef char *namstring
2609 bytestr = _strencode(newname)
2610 namstring = bytestr
2611 if self.data_model != 'NETCDF4': self._redef()
2612 try:
2613 dim = self.dimensions[oldname]
2614 except KeyError:
2615 raise KeyError('%s not a valid dimension name' % oldname)
2616 ierr = nc_rename_dim(self._grpid, dim._dimid, namstring)
2617 if self.data_model != 'NETCDF4': self._enddef()
2618
2619 _ensure_nc_success(ierr)
2620 # remove old key from dimensions dict.
2621 self.dimensions.pop(oldname)
2622 # add new key.
2623 self.dimensions[newname] = dim
2624 # Variable.dimensions is determined by a method that
2625 # looks in the file, so no need to manually update.
2626
2627 def createCompoundType(self, datatype, datatype_name):
2628 """
2629 **`createCompoundType(self, datatype, datatype_name)`**
2630
2631 Creates a new compound data type named `datatype_name` from the numpy
2632 dtype object `datatype`.
2633
2634 ***Note***: If the new compound data type contains other compound data types
2635 (i.e. it is a 'nested' compound type, where not all of the elements
2636 are homogeneous numeric data types), then the 'inner' compound types **must** be
2637 created first.
2638
2639 The return value is the `netCDF4.CompoundType` class instance describing the new
2640 datatype."""
2641 self.cmptypes[datatype_name] = CompoundType(self, datatype,\
2642 datatype_name)
2643 return self.cmptypes[datatype_name]
2644
2645 def createVLType(self, datatype, datatype_name):
2646 """
2647 **`createVLType(self, datatype, datatype_name)`**
2648
2649 Creates a new VLEN data type named `datatype_name` from a numpy
2650 dtype object `datatype`.
2651
2652 The return value is the `netCDF4.VLType` class instance describing the new
2653 datatype."""
2654 self.vltypes[datatype_name] = VLType(self, datatype, datatype_name)
2655 return self.vltypes[datatype_name]
2656
2657 def createEnumType(self, datatype, datatype_name, enum_dict):
2658 """
2659 **`createEnumType(self, datatype, datatype_name, enum_dict)`**
2660
2661 Creates a new Enum data type named `datatype_name` from a numpy
2662 integer dtype object `datatype`, and a python dictionary
2663 defining the enum fields and values.
2664
2665 The return value is the `netCDF4.EnumType` class instance describing the new
2666 datatype."""
2667 self.enumtypes[datatype_name] = EnumType(self, datatype, datatype_name,
2668 enum_dict)
2669 return self.enumtypes[datatype_name]
2670
2671 def createVariable(self, varname, datatype, dimensions=(), zlib=False,
2672 complevel=4, shuffle=True, fletcher32=False, contiguous=False,
2673 chunksizes=None, endian='native', least_significant_digit=None,
2674 fill_value=None, chunk_cache=None):
2675 """
2676 **`createVariable(self, varname, datatype, dimensions=(), zlib=False,
2677 complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None,
2678 endian='native', least_significant_digit=None, fill_value=None, chunk_cache=None)`**
2679
2680 Creates a new variable with the given `varname`, `datatype`, and
2681 `dimensions`. If dimensions are not given, the variable is assumed to be
2682 a scalar.
2683
2684 If `varname` is specified as a path, using forward slashes as in unix to
2685 separate components, then intermediate groups will be created as necessary
2686 For example, `createVariable('/GroupA/GroupB/VarC', float, ('x','y'))` will create groups `GroupA`
2687 and `GroupA/GroupB`, plus the variable `GroupA/GroupB/VarC`, if the preceding
2688 groups don't already exist.
2689
2690 The `datatype` can be a numpy datatype object, or a string that describes
2691 a numpy dtype object (like the `dtype.str` attribute of a numpy array).
2692 Supported specifiers include: `'S1' or 'c' (NC_CHAR), 'i1' or 'b' or 'B'
2693 (NC_BYTE), 'u1' (NC_UBYTE), 'i2' or 'h' or 's' (NC_SHORT), 'u2'
2694 (NC_USHORT), 'i4' or 'i' or 'l' (NC_INT), 'u4' (NC_UINT), 'i8' (NC_INT64),
2695 'u8' (NC_UINT64), 'f4' or 'f' (NC_FLOAT), 'f8' or 'd' (NC_DOUBLE)`.
2696 `datatype` can also be a `netCDF4.CompoundType` instance
2697 (for a structured, or compound array), a `netCDF4.VLType` instance
2698 (for a variable-length array), or the python `str` builtin
2699 (for a variable-length string array). Numpy string and unicode datatypes with
2700 length greater than one are aliases for `str`.
2701
2702 Data from netCDF variables is presented to python as numpy arrays with
2703 the corresponding data type.
2704
2705 `dimensions` must be a tuple containing dimension names (strings) that
2706 have been defined previously using `netCDF4.Dataset.createDimension`. The default value
2707 is an empty tuple, which means the variable is a scalar.
2708
2709 If the optional keyword `zlib` is `True`, the data will be compressed in
2710 the netCDF file using gzip compression (default `False`).
2711
2712 The optional keyword `complevel` is an integer between 1 and 9 describing
2713 the level of compression desired (default 4). Ignored if `zlib=False`.
2714
2715 If the optional keyword `shuffle` is `True`, the HDF5 shuffle filter
2716 will be applied before compressing the data (default `True`). This
2717 significantly improves compression. Default is `True`. Ignored if
2718 `zlib=False`.
2719
2720 If the optional keyword `fletcher32` is `True`, the Fletcher32 HDF5
2721 checksum algorithm is activated to detect errors. Default `False`.
2722
2723 If the optional keyword `contiguous` is `True`, the variable data is
2724 stored contiguously on disk. Default `False`. Setting to `True` for
2725 a variable with an unlimited dimension will trigger an error.
2726
2727 The optional keyword `chunksizes` can be used to manually specify the
2728 HDF5 chunksizes for each dimension of the variable. A detailed
2729 discussion of HDF chunking and I/O performance is available
2730 [here](http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html).
2731 Basically, you want the chunk size for each dimension to match as
2732 closely as possible the size of the data block that users will read
2733 from the file. `chunksizes` cannot be set if `contiguous=True`.
2734
2735 The optional keyword `endian` can be used to control whether the
2736 data is stored in little or big endian format on disk. Possible
2737 values are `little, big` or `native` (default). The library
2738 will automatically handle endian conversions when the data is read,
2739 but if the data is always going to be read on a computer with the
2740 opposite format as the one used to create the file, there may be
2741 some performance advantage to be gained by setting the endian-ness.
2742
2743 The `zlib, complevel, shuffle, fletcher32, contiguous, chunksizes` and `endian`
2744 keywords are silently ignored for netCDF 3 files that do not use HDF5.
2745
2746 The optional keyword `fill_value` can be used to override the default
2747 netCDF `_FillValue` (the value that the variable gets filled with before
2748 any data is written to it, defaults given in `netCDF4.default_fillvals`).
2749 If fill_value is set to `False`, then the variable is not pre-filled.
2750
2751 If the optional keyword parameter `least_significant_digit` is
2752 specified, variable data will be truncated (quantized). In conjunction
2753 with `zlib=True` this produces 'lossy', but significantly more
2754 efficient compression. For example, if `least_significant_digit=1`,
2755 data will be quantized using `numpy.around(scale*data)/scale`, where
2756 scale = 2**bits, and bits is determined so that a precision of 0.1 is
2757 retained (in this case bits=4). From the
2758 [PSD metadata conventions](http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml):
2759 "least_significant_digit -- power of ten of the smallest decimal place
2760 in unpacked data that is a reliable value." Default is `None`, or no
2761 quantization, or 'lossless' compression.
2762
2763 When creating variables in a `NETCDF4` or `NETCDF4_CLASSIC` formatted file,
2764 HDF5 creates something called a 'chunk cache' for each variable. The
2765 default size of the chunk cache may be large enough to completely fill
2766 available memory when creating thousands of variables. The optional
2767 keyword `chunk_cache` allows you to reduce (or increase) the size of
2768 the default chunk cache when creating a variable. The setting only
2769 persists as long as the Dataset is open - you can use the set_var_chunk_cache
2770 method to change it the next time the Dataset is opened.
2771 Warning - messing with this parameter can seriously degrade performance.
2772
2773 The return value is the `netCDF4.Variable` class instance describing the new
2774 variable.
2775
2776 A list of names corresponding to netCDF variable attributes can be
2777 obtained with the `netCDF4.Variable` method `netCDF4.Variable.ncattrs`. A dictionary
2778 containing all the netCDF attribute name/value pairs is provided by
2779 the `__dict__` attribute of a `netCDF4.Variable` instance.
2780
2781 `netCDF4.Variable` instances behave much like array objects. Data can be
2782 assigned to or retrieved from a variable with indexing and slicing
2783 operations on the `netCDF4.Variable` instance. A `netCDF4.Variable` instance has six
2784 Dataset standard attributes: `dimensions, dtype, shape, ndim, name` and
2785 `least_significant_digit`. Application programs should never modify
2786 these attributes. The `dimensions` attribute is a tuple containing the
2787 names of the dimensions associated with this variable. The `dtype`
2788 attribute is a string describing the variable's data type (`i4, f8,
2789 S1,` etc). The `shape` attribute is a tuple describing the current
2790 sizes of all the variable's dimensions. The `name` attribute is a
2791 string containing the name of the Variable instance.
2792 The `least_significant_digit`
2793 attributes describes the power of ten of the smallest decimal place in
2794 the data the contains a reliable value. assigned to the `netCDF4.Variable`
2795 instance. If `None`, the data is not truncated. The `ndim` attribute
2796 is the number of variable dimensions."""
2797 # if varname specified as a path, split out group names.
2798 varname = posixpath.normpath(varname)
2799 dirname, varname = posixpath.split(varname) # varname is last.
2800 # create parent groups (like mkdir -p).
2801 if not dirname:
2802 group = self
2803 else:
2804 group = self.createGroup(dirname)
2805 # create variable.
2806 group.variables[varname] = Variable(group, varname, datatype,
2807 dimensions=dimensions, zlib=zlib, complevel=complevel, shuffle=shuffle,
2808 fletcher32=fletcher32, contiguous=contiguous, chunksizes=chunksizes,
2809 endian=endian, least_significant_digit=least_significant_digit,
2810 fill_value=fill_value, chunk_cache=chunk_cache)
2811 return group.variables[varname]
2812
2813 def renameVariable(self, oldname, newname):
2814 """
2815 **`renameVariable(self, oldname, newname)`**
2816
2817 rename a `netCDF4.Variable` named `oldname` to `newname`"""
2818 cdef char *namstring
2819 try:
2820 var = self.variables[oldname]
2821 except KeyError:
2822 raise KeyError('%s not a valid variable name' % oldname)
2823 bytestr = _strencode(newname)
2824 namstring = bytestr
2825 if self.data_model != 'NETCDF4': self._redef()
2826 ierr = nc_rename_var(self._grpid, var._varid, namstring)
2827 if self.data_model != 'NETCDF4': self._enddef()
2828
2829 _ensure_nc_success(ierr)
2830 # remove old key from dimensions dict.
2831 self.variables.pop(oldname)
2832 # add new key.
2833 self.variables[newname] = var
2834
2835 def createGroup(self, groupname):
2836 """
2837 **`createGroup(self, groupname)`**
2838
2839 Creates a new `netCDF4.Group` with the given `groupname`.
2840
2841 If `groupname` is specified as a path, using forward slashes as in unix to
2842 separate components, then intermediate groups will be created as necessary
2843 (analogous to `mkdir -p` in unix). For example,
2844 `createGroup('/GroupA/GroupB/GroupC')` will create `GroupA`,
2845 `GroupA/GroupB`, and `GroupA/GroupB/GroupC`, if they don't already exist.
2846 If the specified path describes a group that already exists, no error is
2847 raised.
2848
2849 The return value is a `netCDF4.Group` class instance."""
2850 # if group specified as a path, split out group names
2851 groupname = posixpath.normpath(groupname)
2852 nestedgroups = groupname.split('/')
2853 group = self
2854 # loop over group names, create parent groups if they do not already
2855 # exist.
2856 for g in nestedgroups:
2857 if not g: continue
2858 if g not in group.groups:
2859 group.groups[g] = Group(group, g)
2860 group = group.groups[g]
2861 # if group already exists, just return the group
2862 # (prior to 1.1.8, this would have raised an error)
2863 return group
2864
2865 def ncattrs(self):
2866 """
2867 **`ncattrs(self)`**
2868
2869 return netCDF global attribute names for this `netCDF4.Dataset` or `netCDF4.Group` in a list."""
2870 return _get_att_names(self._grpid, NC_GLOBAL)
2871
2872 def setncattr(self,name,value):
2873 """
2874 **`setncattr(self,name,value)`**
2875
2876 set a netCDF dataset or group attribute using name,value pair.
2877 Use if you need to set a netCDF attribute with the
2878 with the same name as one of the reserved python attributes."""
2879 cdef nc_type xtype
2880 xtype=-99
2881 if self.data_model != 'NETCDF4': self._redef()
2882 _set_att(self, NC_GLOBAL, name, value, xtype=xtype, force_ncstring=self._ncstring_attrs__)
2883 if self.data_model != 'NETCDF4': self._enddef()
2884
2885 def setncattr_string(self,name,value):
2886 """
2887 **`setncattr_string(self,name,value)`**
2888
2889 set a netCDF dataset or group string attribute using name,value pair.
2890 Use if you need to ensure that a netCDF attribute is created with type
2891 `NC_STRING` if the file format is `NETCDF4`."""
2892 cdef nc_type xtype
2893 xtype=-99
2894 if self.data_model != 'NETCDF4':
2895 msg='file format does not support NC_STRING attributes'
2896 raise IOError(msg)
2897 _set_att(self, NC_GLOBAL, name, value, xtype=xtype, force_ncstring=True)
2898
2899 def setncatts(self,attdict):
2900 """
2901 **`setncatts(self,attdict)`**
2902
2903 set a bunch of netCDF dataset or group attributes at once using a python dictionary.
2904 This may be faster when setting a lot of attributes for a `NETCDF3`
2905 formatted file, since nc_redef/nc_enddef is not called in between setting
2906 each attribute"""
2907 if self.data_model != 'NETCDF4': self._redef()
2908 for name, value in attdict.items():
2909 _set_att(self, NC_GLOBAL, name, value)
2910 if self.data_model != 'NETCDF4': self._enddef()
2911
2912 def getncattr(self,name,encoding='utf-8'):
2913 """
2914 **`getncattr(self,name)`**
2915
2916 retrieve a netCDF dataset or group attribute.
2917 Use if you need to get a netCDF attribute with the same
2918 name as one of the reserved python attributes.
2919
2920 option kwarg `encoding` can be used to specify the
2921 character encoding of a string attribute (default is `utf-8`)."""
2922 return _get_att(self, NC_GLOBAL, name, encoding=encoding)
2923
2924 def __delattr__(self,name):
2925 # if it's a netCDF attribute, remove it
2926 if name not in _private_atts:
2927 self.delncattr(name)
2928 else:
2929 raise AttributeError(
2930 "'%s' is one of the reserved attributes %s, cannot delete. Use delncattr instead." % (name, tuple(_private_atts)))
2931
2932 def delncattr(self, name):
2933 """
2934 **`delncattr(self,name,value)`**
2935
2936 delete a netCDF dataset or group attribute. Use if you need to delete a
2937 netCDF attribute with the same name as one of the reserved python
2938 attributes."""
2939 cdef char *attname
2940 cdef int ierr
2941 bytestr = _strencode(name)
2942 attname = bytestr
2943 if self.data_model != 'NETCDF4': self._redef()
2944 ierr = nc_del_att(self._grpid, NC_GLOBAL, attname)
2945 if self.data_model != 'NETCDF4': self._enddef()
2946 _ensure_nc_success(ierr)
2947
2948 def __setattr__(self,name,value):
2949 # if name in _private_atts, it is stored at the python
2950 # level and not in the netCDF file.
2951 if name not in _private_atts:
2952 self.setncattr(name, value)
2953 elif not name.endswith('__'):
2954 if hasattr(self,name):
2955 raise AttributeError(
2956 "'%s' is one of the reserved attributes %s, cannot rebind. Use setncattr instead." % (name, tuple(_private_atts)))
2957 else:
2958 self.__dict__[name]=value
2959
2960 def __getattr__(self,name):
2961 # if name in _private_atts, it is stored at the python
2962 # level and not in the netCDF file.
2963 if name.startswith('__') and name.endswith('__'):
2964 # if __dict__ requested, return a dict with netCDF attributes.
2965 if name == '__dict__':
2966 names = self.ncattrs()
2967 values = []
2968 for name in names:
2969 values.append(_get_att(self, NC_GLOBAL, name))
2970 gen = zip(names, values)
2971 if sys.version_info[0:2] < (3, 7):
2972 return OrderedDict(gen)
2973 else:
2974 return dict(gen)
2975 else:
2976 raise AttributeError
2977 elif name in _private_atts:
2978 return self.__dict__[name]
2979 else:
2980 return self.getncattr(name)
2981
2982 def renameAttribute(self, oldname, newname):
2983 """
2984 **`renameAttribute(self, oldname, newname)`**
2985
2986 rename a `netCDF4.Dataset` or `netCDF4.Group` attribute named `oldname` to `newname`."""
2987 cdef char *oldnamec
2988 cdef char *newnamec
2989 bytestr = _strencode(oldname)
2990 oldnamec = bytestr
2991 bytestr = _strencode(newname)
2992 newnamec = bytestr
2993 _ensure_nc_success(nc_rename_att(self._grpid, NC_GLOBAL, oldnamec, newnamec))
2994
2995 def renameGroup(self, oldname, newname):
2996 """
2997 **`renameGroup(self, oldname, newname)`**
2998
2999 rename a `netCDF4.Group` named `oldname` to `newname` (requires netcdf >= 4.3.1)."""
3000 cdef char *newnamec
3001 IF HAS_RENAME_GRP:
3002 bytestr = _strencode(newname)
3003 newnamec = bytestr
3004 try:
3005 grp = self.groups[oldname]
3006 except KeyError:
3007 raise KeyError('%s not a valid group name' % oldname)
3008 _ensure_nc_success(nc_rename_grp(grp._grpid, newnamec))
3009 # remove old key from groups dict.
3010 self.groups.pop(oldname)
3011 # add new key.
3012 self.groups[newname] = grp
3013 ELSE:
3014 msg = """
3015 renameGroup method not enabled. To enable, install Cython, make sure you have
3016 version 4.3.1 or higher of the netcdf C lib, and rebuild netcdf4-python."""
3017 raise ValueError(msg)
3018
3019 def set_auto_chartostring(self, value):
3020 """
3021 **`set_auto_chartostring(self, True_or_False)`**
3022
3023 Call `netCDF4.Variable.set_auto_chartostring` for all variables contained in this `netCDF4.Dataset` or
3024 `netCDF4.Group`, as well as for all variables in all its subgroups.
3025
3026 **`True_or_False`**: Boolean determining if automatic conversion of
3027 all character arrays <--> string arrays should be performed for
3028 character variables (variables of type `NC_CHAR` or `S1`) with the
3029 `_Encoding` attribute set.
3030
3031 ***Note***: Calling this function only affects existing variables. Variables created
3032 after calling this function will follow the default behaviour.
3033 """
3034
3035 # this is a hack to make inheritance work in MFDataset
3036 # (which stores variables in _vars)
3037 _vars = self.variables
3038 if _vars is None: _vars = self._vars
3039 for var in _vars.values():
3040 var.set_auto_chartostring(value)
3041
3042 for groups in _walk_grps(self):
3043 for group in groups:
3044 for var in group.variables.values():
3045 var.set_auto_chartostring(value)
3046
3047 def set_auto_maskandscale(self, value):
3048 """
3049 **`set_auto_maskandscale(self, True_or_False)`**
3050
3051 Call `netCDF4.Variable.set_auto_maskandscale` for all variables contained in this `netCDF4.Dataset` or
3052 `netCDF4.Group`, as well as for all variables in all its subgroups.
3053
3054 **`True_or_False`**: Boolean determining if automatic conversion to masked arrays
3055 and variable scaling shall be applied for all variables.
3056
3057 ***Note***: Calling this function only affects existing variables. Variables created
3058 after calling this function will follow the default behaviour.
3059 """
3060
3061 # this is a hack to make inheritance work in MFDataset
3062 # (which stores variables in _vars)
3063 _vars = self.variables
3064 if _vars is None: _vars = self._vars
3065 for var in _vars.values():
3066 var.set_auto_maskandscale(value)
3067
3068 for groups in _walk_grps(self):
3069 for group in groups:
3070 for var in group.variables.values():
3071 var.set_auto_maskandscale(value)
3072
3073
3074 def set_auto_mask(self, value):
3075 """
3076 **`set_auto_mask(self, True_or_False)`**
3077
3078 Call `netCDF4.Variable.set_auto_mask` for all variables contained in this `netCDF4.Dataset` or
3079 `netCDF4.Group`, as well as for all variables in all its subgroups.
3080
3081 **`True_or_False`**: Boolean determining if automatic conversion to masked arrays
3082 shall be applied for all variables.
3083
3084 ***Note***: Calling this function only affects existing variables. Variables created
3085 after calling this function will follow the default behaviour.
3086 """
3087
3088 # this is a hack to make inheritance work in MFDataset
3089 # (which stores variables in _vars)
3090 _vars = self.variables
3091 if _vars is None: _vars = self._vars
3092 for var in _vars.values():
3093 var.set_auto_mask(value)
3094
3095 for groups in _walk_grps(self):
3096 for group in groups:
3097 for var in group.variables.values():
3098 var.set_auto_mask(value)
3099
3100 def set_auto_scale(self, value):
3101 """
3102 **`set_auto_scale(self, True_or_False)`**
3103
3104 Call `netCDF4.Variable.set_auto_scale` for all variables contained in this `netCDF4.Dataset` or
3105 `netCDF4.Group`, as well as for all variables in all its subgroups.
3106
3107 **`True_or_False`**: Boolean determining if automatic variable scaling
3108 shall be applied for all variables.
3109
3110 ***Note***: Calling this function only affects existing variables. Variables created
3111 after calling this function will follow the default behaviour.
3112 """
3113
3114 # this is a hack to make inheritance work in MFDataset
3115 # (which stores variables in _vars)
3116 _vars = self.variables
3117 if _vars is None: _vars = self._vars
3118 for var in _vars.values():
3119 var.set_auto_scale(value)
3120
3121 for groups in _walk_grps(self):
3122 for group in groups:
3123 for var in group.variables.values():
3124 var.set_auto_scale(value)
3125
3126 def set_always_mask(self, value):
3127 """
3128 **`set_always_mask(self, True_or_False)`**
3129
3130 Call `netCDF4.Variable.set_always_mask` for all variables contained in
3131 this `netCDF4.Dataset` or `netCDF4.Group`, as well as for all
3132 variables in all its subgroups.
3133
3134 **`True_or_False`**: Boolean determining if automatic conversion of
3135 masked arrays with no missing values to regular numpy arrays shall be
3136 applied for all variables. Default True. Set to False to restore the default behaviour
3137 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
3138 otherwise masked array returned).
3139
3140 ***Note***: Calling this function only affects existing
3141 variables. Variables created after calling this function will follow
3142 the default behaviour.
3143 """
3144
3145 # this is a hack to make inheritance work in MFDataset
3146 # (which stores variables in _vars)
3147 _vars = self.variables
3148 if _vars is None: _vars = self._vars
3149 for var in _vars.values():
3150 var.set_always_mask(value)
3151
3152 for groups in _walk_grps(self):
3153 for group in groups:
3154 for var in group.variables.values():
3155 var.set_always_mask(value)
3156
3157 def set_ncstring_attrs(self, value):
3158 """
3159 **`set_ncstring_attrs(self, True_or_False)`**
3160
3161 Call `netCDF4.Variable.set_ncstring_attrs` for all variables contained in
3162 this `netCDF4.Dataset` or `netCDF4.Group`, as well as for all its
3163 subgroups and their variables.
3164
3165 **`True_or_False`**: Boolean determining if all string attributes are
3166 created as variable-length NC_STRINGs, (if True), or if ascii text
3167 attributes are stored as NC_CHARs (if False; default)
3168
3169 ***Note***: Calling this function only affects newly created attributes
3170 of existing (sub-) groups and their variables.
3171 """
3172
3173 self._ncstring_attrs__ = bool(value)
3174
3175 # this is a hack to make inheritance work in MFDataset
3176 # (which stores variables in _vars)
3177 _vars = self.variables
3178 if _vars is None:
3179 _vars = self._vars
3180 for var in _vars.values():
3181 var.set_ncstring_attrs(value)
3182
3183 for groups in _walk_grps(self):
3184 for group in groups:
3185 group.set_ncstring_attrs(value) # recurse into subgroups...
3186
3187 def get_variables_by_attributes(self, **kwargs):
3188 """
3189 **`get_variables_by_attribute(self, **kwargs)`**
3190
3191 Returns a list of variables that match specific conditions.
3192
3193 Can pass in key=value parameters and variables are returned that
3194 contain all of the matches. For example,
3195
3196 :::python
3197 >>> # Get variables with x-axis attribute.
3198 >>> vs = nc.get_variables_by_attributes(axis='X')
3199 >>> # Get variables with matching "standard_name" attribute
3200 >>> vs = nc.get_variables_by_attributes(standard_name='northward_sea_water_velocity')
3201
3202 Can pass in key=callable parameter and variables are returned if the
3203 callable returns True. The callable should accept a single parameter,
3204 the attribute value. None is given as the attribute value when the
3205 attribute does not exist on the variable. For example,
3206
3207 :::python
3208 >>> # Get Axis variables
3209 >>> vs = nc.get_variables_by_attributes(axis=lambda v: v in ['X', 'Y', 'Z', 'T'])
3210 >>> # Get variables that don't have an "axis" attribute
3211 >>> vs = nc.get_variables_by_attributes(axis=lambda v: v is None)
3212 >>> # Get variables that have a "grid_mapping" attribute
3213 >>> vs = nc.get_variables_by_attributes(grid_mapping=lambda v: v is not None)
3214 """
3215 vs = []
3216
3217 has_value_flag = False
3218 # this is a hack to make inheritance work in MFDataset
3219 # (which stores variables in _vars)
3220 _vars = self.variables
3221 if _vars is None: _vars = self._vars
3222 for vname in _vars:
3223 var = _vars[vname]
3224 for k, v in kwargs.items():
3225 if callable(v):
3226 has_value_flag = v(getattr(var, k, None))
3227 if has_value_flag is False:
3228 break
3229 elif hasattr(var, k) and getattr(var, k) == v:
3230 has_value_flag = True
3231 else:
3232 has_value_flag = False
3233 break
3234
3235 if has_value_flag is True:
3236 vs.append(_vars[vname])
3237
3238 return vs
3239
3240 def _getname(self):
3241 # private method to get name associated with instance.
3242 cdef int ierr
3243 cdef char namstring[NC_MAX_NAME+1]
3244 with nogil:
3245 ierr = nc_inq_grpname(self._grpid, namstring)
3246 _ensure_nc_success(ierr)
3247 return namstring.decode('utf-8')
3248
3249 property name:
3250 """string name of Group instance"""
3251 def __get__(self):
3252 return self._getname()
3253 def __set__(self,value):
3254 raise AttributeError("name cannot be altered")
3255
3256
3257 cdef class Group(Dataset):
3258 """
3259 Groups define a hierarchical namespace within a netCDF file. They are
3260 analogous to directories in a unix filesystem. Each `netCDF4.Group` behaves like
3261 a `netCDF4.Dataset` within a Dataset, and can contain it's own variables,
3262 dimensions and attributes (and other Groups). See `netCDF4.Group.__init__`
3263 for more details.
3264
3265 `netCDF4.Group` inherits from `netCDF4.Dataset`, so all the
3266 `netCDF4.Dataset` class methods and variables are available
3267 to a `netCDF4.Group` instance (except the `close` method).
3268
3269 Additional read-only class variables:
3270
3271 **`name`**: String describing the group name.
3272 """
3273 # Docstrings for class variables (used by pdoc).
3274 __pdoc__['Group.name']=\
3275 """A string describing the name of the `netCDF4.Group`."""
3276 def __init__(self, parent, name, **kwargs):
3277 """
3278 **`__init__(self, parent, name)`**
3279 `netCDF4.Group` constructor.
3280
3281 **`parent`**: `netCDF4.Group` instance for the parent group. If being created
3282 in the root group, use a `netCDF4.Dataset` instance.
3283
3284 **`name`**: - Name of the group.
3285
3286 ***Note***: `netCDF4.Group` instances should be created using the
3287 `netCDF4.Dataset.createGroup` method of a `netCDF4.Dataset` instance, or
3288 another `netCDF4.Group` instance, not using this class directly.
3289 """
3290 cdef char *groupname
3291 # flag to indicate that Variables in this Group support orthogonal indexing.
3292 self.__orthogonal_indexing__ = True
3293 # set data_model and file_format attributes.
3294 self.data_model = parent.data_model
3295 self.file_format = parent.file_format
3296 # full path to Group.
3297 self.path = posixpath.join(parent.path, name)
3298 # parent group.
3299 self.parent = parent
3300 # propagate weak reference setting from parent.
3301 self.keepweakref = parent.keepweakref
3302 # propagate _ncstring_attrs__ setting from parent.
3303 self._ncstring_attrs__ = parent._ncstring_attrs__
3304 if 'id' in kwargs:
3305 self._grpid = kwargs['id']
3306 # get compound, vlen and enum types in this Group.
3307 self.cmptypes, self.vltypes, self.enumtypes = _get_types(self)
3308 # get dimensions in this Group.
3309 self.dimensions = _get_dims(self)
3310 # get variables in this Group.
3311 self.variables = _get_vars(self)
3312 # get groups in this Group.
3313 self.groups = _get_grps(self)
3314 else:
3315 bytestr = _strencode(name)
3316 groupname = bytestr
3317 _ensure_nc_success(nc_def_grp(parent._grpid, groupname, &self._grpid))
3318 if sys.version_info[0:2] < (3, 7):
3319 self.cmptypes = OrderedDict()
3320 self.vltypes = OrderedDict()
3321 self.enumtypes = OrderedDict()
3322 self.dimensions = OrderedDict()
3323 self.variables = OrderedDict()
3324 self.groups = OrderedDict()
3325 else:
3326 self.cmptypes = dict()
3327 self.vltypes = dict()
3328 self.enumtypes = dict()
3329 self.dimensions = dict()
3330 self.variables = dict()
3331 self.groups = dict()
3332
3333
3334 def close(self):
3335 """
3336 **`close(self)`**
3337
3338 overrides `netCDF4.Dataset` close method which does not apply to `netCDF4.Group`
3339 instances, raises IOError."""
3340 raise IOError('cannot close a `netCDF4.Group` (only applies to Dataset)')
3341
3342
3343 cdef class Dimension:
3344 """
3345 A netCDF `netCDF4.Dimension` is used to describe the coordinates of a `netCDF4.Variable`.
3346 See `netCDF4.Dimension.__init__` for more details.
3347
3348 The current maximum size of a `netCDF4.Dimension` instance can be obtained by
3349 calling the python `len` function on the `netCDF4.Dimension` instance. The
3350 `netCDF4.Dimension.isunlimited` method of a `netCDF4.Dimension` instance can be used to
3351 determine if the dimension is unlimited.
3352
3353 Read-only class variables:
3354
3355 **`name`**: String name, used when creating a `netCDF4.Variable` with
3356 `netCDF4.Dataset.createVariable`.
3357
3358 **`size`**: Current `netCDF4.Dimension` size (same as `len(d)`, where `d` is a
3359 `netCDF4.Dimension` instance).
3360 """
3361 cdef public int _dimid, _grpid
3362 cdef public _data_model, _name, _grp
3363 # Docstrings for class variables (used by pdoc).
3364 __pdoc__['Dimension.name']=\
3365 """A string describing the name of the `netCDF4.Dimension` - used when creating a
3366 `netCDF4.Variable` instance with `netCDF4.Dataset.createVariable`."""
3367
3368 def __init__(self, grp, name, size=None, **kwargs):
3369 """
3370 **`__init__(self, group, name, size=None)`**
3371
3372 `netCDF4.Dimension` constructor.
3373
3374 **`group`**: `netCDF4.Group` instance to associate with dimension.
3375
3376 **`name`**: Name of the dimension.
3377
3378 **`size`**: Size of the dimension. `None` or 0 means unlimited. (Default `None`).
3379
3380 ***Note***: `netCDF4.Dimension` instances should be created using the
3381 `netCDF4.Dataset.createDimension` method of a `netCDF4.Group` or
3382 `netCDF4.Dataset` instance, not using `netCDF4.Dimension.__init__` directly.
3383 """
3384 cdef int ierr
3385 cdef char *dimname
3386 cdef size_t lendim
3387 self._grpid = grp._grpid
3388 # make a weakref to group to avoid circular ref (issue 218)
3389 # keep strong reference the default behaviour (issue 251)
3390 if grp.keepweakref:
3391 self._grp = weakref.proxy(grp)
3392 else:
3393 self._grp = grp
3394 self._data_model = grp.data_model
3395 self._name = name
3396 if 'id' in kwargs:
3397 self._dimid = kwargs['id']
3398 else:
3399 bytestr = _strencode(name)
3400 dimname = bytestr
3401 if size is not None:
3402 lendim = size
3403 else:
3404 lendim = NC_UNLIMITED
3405 if grp.data_model != 'NETCDF4': grp._redef()
3406 ierr = nc_def_dim(self._grpid, dimname, lendim, &self._dimid)
3407 if grp.data_model != 'NETCDF4': grp._enddef()
3408 _ensure_nc_success(ierr)
3409
3410 def _getname(self):
3411 # private method to get name associated with instance.
3412 cdef int err, _grpid
3413 cdef char namstring[NC_MAX_NAME+1]
3414 _grpid = self._grp._grpid
3415 with nogil:
3416 ierr = nc_inq_dimname(_grpid, self._dimid, namstring)
3417 _ensure_nc_success(ierr)
3418 return namstring.decode('utf-8')
3419
3420 property name:
3421 """string name of Dimension instance"""
3422 def __get__(self):
3423 return self._getname()
3424 def __set__(self,value):
3425 raise AttributeError("name cannot be altered")
3426
3427 property size:
3428 """current size of Dimension (calls `len` on Dimension instance)"""
3429 def __get__(self):
3430 return len(self)
3431 def __set__(self,value):
3432 raise AttributeError("size cannot be altered")
3433
3434 def __repr__(self):
3435 if python3:
3436 return self.__unicode__()
3437 else:
3438 return unicode(self).encode('utf-8')
3439
3440 def __unicode__(self):
3441 if not dir(self._grp):
3442 return 'Dimension object no longer valid'
3443 if self.isunlimited():
3444 return "%r (unlimited): name = '%s', size = %s" %\
3445 (type(self), self._name, len(self))
3446 else:
3447 return "%r: name = '%s', size = %s" %\
3448 (type(self), self._name, len(self))
3449
3450 def __len__(self):
3451 # len(`netCDF4.Dimension` instance) returns current size of dimension
3452 cdef int ierr
3453 cdef size_t lengthp
3454 with nogil:
3455 ierr = nc_inq_dimlen(self._grpid, self._dimid, &lengthp)
3456 _ensure_nc_success(ierr)
3457 return lengthp
3458
3459 def group(self):
3460 """
3461 **`group(self)`**
3462
3463 return the group that this `netCDF4.Dimension` is a member of."""
3464 return self._grp
3465
3466 def isunlimited(self):
3467 """
3468 **`isunlimited(self)`**
3469
3470 returns `True` if the `netCDF4.Dimension` instance is unlimited, `False` otherwise."""
3471 cdef int ierr, n, numunlimdims, ndims, nvars, ngatts, xdimid
3472 cdef int *unlimdimids
3473 if self._data_model == 'NETCDF4':
3474 ierr = nc_inq_unlimdims(self._grpid, &numunlimdims, NULL)
3475 _ensure_nc_success(ierr)
3476 if numunlimdims == 0:
3477 return False
3478 else:
3479 unlimdimids = <int *>malloc(sizeof(int) * numunlimdims)
3480 dimid = self._dimid
3481 with nogil:
3482 ierr = nc_inq_unlimdims(self._grpid, &numunlimdims, unlimdimids)
3483 _ensure_nc_success(ierr)
3484 unlimdim_ids = []
3485 for n from 0 <= n < numunlimdims:
3486 unlimdim_ids.append(unlimdimids[n])
3487 free(unlimdimids)
3488 if dimid in unlimdim_ids:
3489 return True
3490 else:
3491 return False
3492 else: # if not NETCDF4, there is only one unlimited dimension.
3493 # nc_inq_unlimdims only works for NETCDF4.
3494 with nogil:
3495 ierr = nc_inq(self._grpid, &ndims, &nvars, &ngatts, &xdimid)
3496 if self._dimid == xdimid:
3497 return True
3498 else:
3499 return False
3500
3501 cdef class Variable:
3502 """
3503 A netCDF `netCDF4.Variable` is used to read and write netCDF data. They are
3504 analogous to numpy array objects. See `netCDF4.Variable.__init__` for more
3505 details.
3506
3507 A list of attribute names corresponding to netCDF attributes defined for
3508 the variable can be obtained with the `netCDF4.Variable.ncattrs` method. These
3509 attributes can be created by assigning to an attribute of the
3510 `netCDF4.Variable` instance. A dictionary containing all the netCDF attribute
3511 name/value pairs is provided by the `__dict__` attribute of a
3512 `netCDF4.Variable` instance.
3513
3514 The following class variables are read-only:
3515
3516 **`dimensions`**: A tuple containing the names of the
3517 dimensions associated with this variable.
3518
3519 **`dtype`**: A numpy dtype object describing the
3520 variable's data type.
3521
3522 **`ndim`**: The number of variable dimensions.
3523
3524 **`shape`**: A tuple with the current shape (length of all dimensions).
3525
3526 **`scale`**: If True, `scale_factor` and `add_offset` are
3527 applied, and signed integer data is automatically converted to
3528 unsigned integer data if the `_Unsigned` attribute is set.
3529 Default is `True`, can be reset using `netCDF4.Variable.set_auto_scale` and
3530 `netCDF4.Variable.set_auto_maskandscale` methods.
3531
3532 **`mask`**: If True, data is automatically converted to/from masked
3533 arrays when missing values or fill values are present. Default is `True`, can be
3534 reset using `netCDF4.Variable.set_auto_mask` and `netCDF4.Variable.set_auto_maskandscale`
3535 methods.
3536
3537 **`chartostring`**: If True, data is automatically converted to/from character
3538 arrays to string arrays when the `_Encoding` variable attribute is set.
3539 Default is `True`, can be reset using
3540 `netCDF4.Variable.set_auto_chartostring` method.
3541
3542 **`least_significant_digit`**: Describes the power of ten of the
3543 smallest decimal place in the data the contains a reliable value. Data is
3544 truncated to this decimal place when it is assigned to the `netCDF4.Variable`
3545 instance. If `None`, the data is not truncated.
3546
3547 **`__orthogonal_indexing__`**: Always `True`. Indicates to client code
3548 that the object supports 'orthogonal indexing', which means that slices
3549 that are 1d arrays or lists slice along each dimension independently. This
3550 behavior is similar to Fortran or Matlab, but different than numpy.
3551
3552 **`datatype`**: numpy data type (for primitive data types) or VLType/CompoundType
3553 instance (for compound or vlen data types).
3554
3555 **`name`**: String name.
3556
3557 **`size`**: The number of stored elements.
3558 """
3559 cdef public int _varid, _grpid, _nunlimdim
3560 cdef public _name, ndim, dtype, mask, scale, always_mask, chartostring, _isprimitive, \
3561 _iscompound, _isvlen, _isenum, _grp, _cmptype, _vltype, _enumtype,\
3562 __orthogonal_indexing__, _has_lsd, _use_get_vars, _ncstring_attrs__
3563 # Docstrings for class variables (used by pdoc).
3564 __pdoc__['Variable.dimensions'] = \
3565 """A tuple containing the names of the
3566 dimensions associated with this variable."""
3567 __pdoc__['Variable.dtype'] = \
3568 """A numpy dtype object describing the
3569 variable's data type."""
3570 __pdoc__['Variable.ndim'] = \
3571 """The number of variable dimensions."""
3572 __pdoc__['Variable.scale'] = \
3573 """if True, `scale_factor` and `add_offset` are
3574 applied, and signed integer data is converted to unsigned
3575 integer data if the `_Unsigned` attribute is set.
3576 Default is `True`, can be reset using `netCDF4.Variable.set_auto_scale` and
3577 `netCDF4.Variable.set_auto_maskandscale` methods."""
3578 __pdoc__['Variable.mask'] = \
3579 """If True, data is automatically converted to/from masked
3580 arrays when missing values or fill values are present. Default is `True`, can be
3581 reset using `netCDF4.Variable.set_auto_mask` and `netCDF4.Variable.set_auto_maskandscale`
3582 methods."""
3583 __pdoc__['Variable.chartostring'] = \
3584 """If True, data is automatically converted to/from character
3585 arrays to string arrays when `_Encoding` variable attribute is set.
3586 Default is `True`, can be reset using
3587 `netCDF4.Variable.set_auto_chartostring` method."""
3588 __pdoc__['Variable._use_get_vars'] = \
3589 """If True (default), netcdf routine `nc_get_vars` is not used for strided slicing
3590 slicing. Can be re-set using `netCDF4.Variable.use_nc_get_vars` method."""
3591 __pdoc__['Variable.least_significant_digit'] = \
3592 """Describes the power of ten of the
3593 smallest decimal place in the data the contains a reliable value. Data is
3594 truncated to this decimal place when it is assigned to the `netCDF4.Variable`
3595 instance. If `None`, the data is not truncated."""
3596 __pdoc__['Variable.__orthogonal_indexing__'] = \
3597 """Always `True`. Indicates to client code
3598 that the object supports 'orthogonal indexing', which means that slices
3599 that are 1d arrays or lists slice along each dimension independently. This
3600 behavior is similar to Fortran or Matlab, but different than numpy."""
3601 __pdoc__['Variable.datatype'] = \
3602 """numpy data type (for primitive data types) or
3603 VLType/CompoundType/EnumType instance (for compound, vlen or enum
3604 data types)."""
3605 __pdoc__['Variable.name'] = \
3606 """String name."""
3607 __pdoc__['Variable.shape'] = \
3608 """A tuple with the current shape (length of all dimensions)."""
3609 __pdoc__['Variable.size'] = \
3610 """The number of stored elements."""
3611
3612 def __init__(self, grp, name, datatype, dimensions=(), zlib=False,
3613 complevel=4, shuffle=True, fletcher32=False, contiguous=False,
3614 chunksizes=None, endian='native', least_significant_digit=None,
3615 fill_value=None, chunk_cache=None, **kwargs):
3616 """
3617 **`__init__(self, group, name, datatype, dimensions=(), zlib=False,
3618 complevel=4, shuffle=True, fletcher32=False, contiguous=False,
3619 chunksizes=None, endian='native',
3620 least_significant_digit=None,fill_value=None,chunk_cache=None)`**
3621
3622 `netCDF4.Variable` constructor.
3623
3624 **`group`**: `netCDF4.Group` or `netCDF4.Dataset` instance to associate with variable.
3625
3626 **`name`**: Name of the variable.
3627
3628 **`datatype`**: `netCDF4.Variable` data type. Can be specified by providing a
3629 numpy dtype object, or a string that describes a numpy dtype object.
3630 Supported values, corresponding to `str` attribute of numpy dtype
3631 objects, include `'f4'` (32-bit floating point), `'f8'` (64-bit floating
3632 point), `'i4'` (32-bit signed integer), `'i2'` (16-bit signed integer),
3633 `'i8'` (64-bit signed integer), `'i4'` (8-bit signed integer), `'i1'`
3634 (8-bit signed integer), `'u1'` (8-bit unsigned integer), `'u2'` (16-bit
3635 unsigned integer), `'u4'` (32-bit unsigned integer), `'u8'` (64-bit
3636 unsigned integer), or `'S1'` (single-character string). From
3637 compatibility with Scientific.IO.NetCDF, the old Numeric single character
3638 typecodes can also be used (`'f'` instead of `'f4'`, `'d'` instead of
3639 `'f8'`, `'h'` or `'s'` instead of `'i2'`, `'b'` or `'B'` instead of
3640 `'i1'`, `'c'` instead of `'S1'`, and `'i'` or `'l'` instead of
3641 `'i4'`). `datatype` can also be a `netCDF4.CompoundType` instance
3642 (for a structured, or compound array), a `netCDF4.VLType` instance
3643 (for a variable-length array), or the python `str` builtin
3644 (for a variable-length string array). Numpy string and unicode datatypes with
3645 length greater than one are aliases for `str`.
3646
3647 **`dimensions`**: a tuple containing the variable's dimension names
3648 (defined previously with `createDimension`). Default is an empty tuple
3649 which means the variable is a scalar (and therefore has no dimensions).
3650
3651 **`zlib`**: if `True`, data assigned to the `netCDF4.Variable`
3652 instance is compressed on disk. Default `False`.
3653
3654 **`complevel`**: the level of zlib compression to use (1 is the fastest,
3655 but poorest compression, 9 is the slowest but best compression). Default 4.
3656 Ignored if `zlib=False`.
3657
3658 **`shuffle`**: if `True`, the HDF5 shuffle filter is applied
3659 to improve compression. Default `True`. Ignored if `zlib=False`.
3660
3661 **`fletcher32`**: if `True` (default `False`), the Fletcher32 checksum
3662 algorithm is used for error detection.
3663
3664 **`contiguous`**: if `True` (default `False`), the variable data is
3665 stored contiguously on disk. Default `False`. Setting to `True` for
3666 a variable with an unlimited dimension will trigger an error.
3667
3668 **`chunksizes`**: Can be used to specify the HDF5 chunksizes for each
3669 dimension of the variable. A detailed discussion of HDF chunking and I/O
3670 performance is available
3671 [here](http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html).
3672 Basically, you want the chunk size for each dimension to match as
3673 closely as possible the size of the data block that users will read
3674 from the file. `chunksizes` cannot be set if `contiguous=True`.
3675
3676 **`endian`**: Can be used to control whether the
3677 data is stored in little or big endian format on disk. Possible
3678 values are `little, big` or `native` (default). The library
3679 will automatically handle endian conversions when the data is read,
3680 but if the data is always going to be read on a computer with the
3681 opposite format as the one used to create the file, there may be
3682 some performance advantage to be gained by setting the endian-ness.
3683 For netCDF 3 files (that don't use HDF5), only `endian='native'` is allowed.
3684
3685 The `zlib, complevel, shuffle, fletcher32, contiguous` and `chunksizes`
3686 keywords are silently ignored for netCDF 3 files that do not use HDF5.
3687
3688 **`least_significant_digit`**: If specified, variable data will be
3689 truncated (quantized). In conjunction with `zlib=True` this produces
3690 'lossy', but significantly more efficient compression. For example, if
3691 `least_significant_digit=1`, data will be quantized using
3692 around(scale*data)/scale, where scale = 2**bits, and bits is determined
3693 so that a precision of 0.1 is retained (in this case bits=4). Default is
3694 `None`, or no quantization.
3695
3696 **`fill_value`**: If specified, the default netCDF `_FillValue` (the
3697 value that the variable gets filled with before any data is written to it)
3698 is replaced with this value. If fill_value is set to `False`, then
3699 the variable is not pre-filled. The default netCDF fill values can be found
3700 in `netCDF4.default_fillvals`.
3701
3702 **`chunk_cache`**: If specified, sets the chunk cache size for this variable.
3703 Persists as long as Dataset is open. Use `netCDF4.set_var_chunk_cache` to
3704 change it when Dataset is re-opened.
3705
3706 ***Note***: `netCDF4.Variable` instances should be created using the
3707 `netCDF4.Dataset.createVariable` method of a `netCDF4.Dataset` or
3708 `netCDF4.Group` instance, not using this class directly.
3709 """
3710 cdef int ierr, ndims, icontiguous, ideflate_level, numdims, _grpid
3711 cdef char namstring[NC_MAX_NAME+1]
3712 cdef char *varname
3713 cdef nc_type xtype
3714 cdef int *dimids
3715 cdef size_t sizep, nelemsp
3716 cdef size_t *chunksizesp
3717 cdef float preemptionp
3718 # flag to indicate that orthogonal indexing is supported
3719 self.__orthogonal_indexing__ = True
3720 # if complevel is set to zero, set zlib to False.
3721 if not complevel:
3722 zlib = False
3723 # if dimensions is a string, convert to a tuple
3724 # this prevents a common error that occurs when
3725 # dimensions = 'lat' instead of ('lat',)
3726 if type(dimensions) == str or type(dimensions) == bytes or type(dimensions) == unicode:
3727 dimensions = dimensions,
3728 self._grpid = grp._grpid
3729 # make a weakref to group to avoid circular ref (issue 218)
3730 # keep strong reference the default behaviour (issue 251)
3731 if grp.keepweakref:
3732 self._grp = weakref.proxy(grp)
3733 else:
3734 self._grp = grp
3735 user_type = isinstance(datatype, CompoundType) or \
3736 isinstance(datatype, VLType) or \
3737 isinstance(datatype, EnumType) or \
3738 datatype == str
3739 # convert to a real numpy datatype object if necessary.
3740 if not user_type and type(datatype) != numpy.dtype:
3741 datatype = numpy.dtype(datatype)
3742 # convert numpy string dtype with length > 1
3743 # or any numpy unicode dtype into str
3744 if (isinstance(datatype, numpy.dtype) and
3745 ((datatype.kind == 'S' and datatype.itemsize > 1) or
3746 datatype.kind == 'U')):
3747 datatype = str
3748 user_type = True
3749 # check if endian keyword consistent with datatype specification.
3750 dtype_endian = getattr(datatype,'byteorder',None)
3751 if dtype_endian == '=': dtype_endian='native'
3752 if dtype_endian == '>': dtype_endian='big'
3753 if dtype_endian == '<': dtype_endian='little'
3754 if dtype_endian == '|': dtype_endian=None
3755 if dtype_endian is not None and dtype_endian != endian:
3756 if dtype_endian == 'native' and endian == sys.byteorder:
3757 pass
3758 else:
3759 # endian keyword prevails, issue warning
3760 msg = 'endian-ness of dtype and endian kwarg do not match, using endian kwarg'
3761 #msg = 'endian-ness of dtype and endian kwarg do not match, dtype over-riding endian kwarg'
3762 warnings.warn(msg)
3763 #endian = dtype_endian # dtype prevails
3764 # check validity of datatype.
3765 self._isprimitive = False
3766 self._iscompound = False
3767 self._isvlen = False
3768 self._isenum = False
3769 if user_type:
3770 if isinstance(datatype, CompoundType):
3771 self._iscompound = True
3772 self._cmptype = datatype
3773 if isinstance(datatype, VLType) or datatype==str:
3774 self._isvlen = True
3775 self._vltype = datatype
3776 if isinstance(datatype, EnumType):
3777 self._isenum = True
3778 self._enumtype = datatype
3779 if datatype==str:
3780 if grp.data_model != 'NETCDF4':
3781 raise ValueError(
3782 'Variable length strings are only supported for the '
3783 'NETCDF4 format. For other formats, consider using '
3784 'netCDF4.stringtochar to convert string arrays into '
3785 'character arrays with an additional dimension.')
3786 datatype = VLType(self._grp, str, None)
3787 self._vltype = datatype
3788 xtype = datatype._nc_type
3789 # make sure this a valid user defined datatype defined in this Group
3790 ierr = nc_inq_type(self._grpid, xtype, namstring, NULL)
3791 _ensure_nc_success(ierr)
3792 # dtype variable attribute is a numpy datatype object.
3793 self.dtype = datatype.dtype
3794 elif datatype.str[1:] in _supportedtypes:
3795 self._isprimitive = True
3796 # find netCDF primitive data type corresponding to
3797 # specified numpy data type.
3798 xtype = _nptonctype[datatype.str[1:]]
3799 # dtype variable attribute is a numpy datatype object.
3800 self.dtype = datatype
3801 else:
3802 raise TypeError('illegal primitive data type, must be one of %s, got %s' % (_supportedtypes,datatype))
3803 if 'id' in kwargs:
3804 self._varid = kwargs['id']
3805 else:
3806 bytestr = _strencode(name)
3807 varname = bytestr
3808 ndims = len(dimensions)
3809 # find dimension ids.
3810 if ndims:
3811 dims = []
3812 dimids = <int *>malloc(sizeof(int) * ndims)
3813 for n from 0 <= n < ndims:
3814 dimname = dimensions[n]
3815 # look for dimension in this group, and if not
3816 # found there, look in parent (and it's parent, etc, back to root).
3817 dim = _find_dim(grp, dimname)
3818 if dim is None:
3819 raise KeyError("dimension %s not defined in group %s or any group in it's family tree" % (dimname, grp.path))
3820 dimids[n] = dim._dimid
3821 dims.append(dim)
3822 # go into define mode if it's a netCDF 3 compatible
3823 # file format. Be careful to exit define mode before
3824 # any exceptions are raised.
3825 if grp.data_model != 'NETCDF4': grp._redef()
3826 # define variable.
3827 if ndims:
3828 ierr = nc_def_var(self._grpid, varname, xtype, ndims,
3829 dimids, &self._varid)
3830 free(dimids)
3831 else: # a scalar variable.
3832 ierr = nc_def_var(self._grpid, varname, xtype, ndims,
3833 NULL, &self._varid)
3834 # set chunk cache size if desired
3835 # default is 1mb per var, can cause problems when many (1000's)
3836 # of vars are created. This change only lasts as long as file is
3837 # open.
3838 if grp.data_model.startswith('NETCDF4') and chunk_cache is not None:
3839 ierr = nc_get_var_chunk_cache(self._grpid, self._varid, &sizep,
3840 &nelemsp, &preemptionp)
3841 _ensure_nc_success(ierr)
3842 # reset chunk cache size, leave other parameters unchanged.
3843 sizep = chunk_cache
3844 ierr = nc_set_var_chunk_cache(self._grpid, self._varid, sizep,
3845 nelemsp, preemptionp)
3846 _ensure_nc_success(ierr)
3847 if ierr != NC_NOERR:
3848 if grp.data_model != 'NETCDF4': grp._enddef()
3849 _ensure_nc_success(ierr)
3850 # set zlib, shuffle, chunking, fletcher32 and endian
3851 # variable settings.
3852 # don't bother for NETCDF3* formats.
3853 # for NETCDF3* formats, the zlib,shuffle,chunking,
3854 # and fletcher32 are silently ignored. Only
3855 # endian='native' allowed for NETCDF3.
3856 if grp.data_model in ['NETCDF4','NETCDF4_CLASSIC']:
3857 # set zlib and shuffle parameters.
3858 if zlib and ndims: # don't bother for scalar variable
3859 ideflate_level = complevel
3860 if shuffle:
3861 ierr = nc_def_var_deflate(self._grpid, self._varid, 1, 1, ideflate_level)
3862 else:
3863 ierr = nc_def_var_deflate(self._grpid, self._varid, 0, 1, ideflate_level)
3864 if ierr != NC_NOERR:
3865 if grp.data_model != 'NETCDF4': grp._enddef()
3866 _ensure_nc_success(ierr)
3867 # set checksum.
3868 if fletcher32 and ndims: # don't bother for scalar variable
3869 ierr = nc_def_var_fletcher32(self._grpid, self._varid, 1)
3870 if ierr != NC_NOERR:
3871 if grp.data_model != 'NETCDF4': grp._enddef()
3872 _ensure_nc_success(ierr)
3873 # set chunking stuff.
3874 if ndims: # don't bother for scalar variable.
3875 if contiguous:
3876 icontiguous = NC_CONTIGUOUS
3877 if chunksizes is not None:
3878 raise ValueError('cannot specify chunksizes for a contiguous dataset')
3879 else:
3880 icontiguous = NC_CHUNKED
3881 if chunksizes is None:
3882 chunksizesp = NULL
3883 else:
3884 if len(chunksizes) != len(dimensions):
3885 if grp.data_model != 'NETCDF4': grp._enddef()
3886 raise ValueError('chunksizes must be a sequence with the same length as dimensions')
3887 chunksizesp = <size_t *>malloc(sizeof(size_t) * ndims)
3888 for n from 0 <= n < ndims:
3889 if not dims[n].isunlimited() and \
3890 chunksizes[n] > dims[n].size:
3891 msg = 'chunksize cannot exceed dimension size'
3892 raise ValueError(msg)
3893 chunksizesp[n] = chunksizes[n]
3894 if chunksizes is not None or contiguous:
3895 ierr = nc_def_var_chunking(self._grpid, self._varid, icontiguous, chunksizesp)
3896 free(chunksizesp)
3897 if ierr != NC_NOERR:
3898 if grp.data_model != 'NETCDF4': grp._enddef()
3899 _ensure_nc_success(ierr)
3900 # set endian-ness of variable
3901 if endian == 'little':
3902 ierr = nc_def_var_endian(self._grpid, self._varid, NC_ENDIAN_LITTLE)
3903 elif endian == 'big':
3904 ierr = nc_def_var_endian(self._grpid, self._varid, NC_ENDIAN_BIG)
3905 elif endian == 'native':
3906 pass # this is the default format.
3907 else:
3908 raise ValueError("'endian' keyword argument must be 'little','big' or 'native', got '%s'" % endian)
3909 if ierr != NC_NOERR:
3910 if grp.data_model != 'NETCDF4': grp._enddef()
3911 _ensure_nc_success(ierr)
3912 else:
3913 if endian != 'native':
3914 msg="only endian='native' allowed for NETCDF3 files"
3915 raise RuntimeError(msg)
3916 # set a fill value for this variable if fill_value keyword
3917 # given. This avoids the HDF5 overhead of deleting and
3918 # recreating the dataset if it is set later (after the enddef).
3919 if fill_value is not None:
3920 if not fill_value and isinstance(fill_value,bool):
3921 # no filling for this variable if fill_value==False.
3922 if not self._isprimitive:
3923 # no fill values for VLEN and compound variables
3924 # anyway.
3925 ierr = 0
3926 else:
3927 ierr = nc_def_var_fill(self._grpid, self._varid, 1, NULL)
3928 if ierr != NC_NOERR:
3929 if grp.data_model != 'NETCDF4': grp._enddef()
3930 _ensure_nc_success(ierr)
3931 else:
3932 if self._isprimitive or self._isenum or \
3933 (self._isvlen and self.dtype == str):
3934 if self._isvlen and self.dtype == str:
3935 _set_att(self._grp, self._varid, '_FillValue',\
3936 _tostr(fill_value), xtype=xtype, force_ncstring=True)
3937 else:
3938 fillval = numpy.array(fill_value, self.dtype)
3939 if not fillval.dtype.isnative: fillval.byteswap(True)
3940 _set_att(self._grp, self._varid, '_FillValue',\
3941 fillval, xtype=xtype)
3942 else:
3943 raise AttributeError("cannot set _FillValue attribute for VLEN or compound variable")
3944 if least_significant_digit is not None:
3945 self.least_significant_digit = least_significant_digit
3946 # leave define mode if not a NETCDF4 format file.
3947 if grp.data_model != 'NETCDF4': grp._enddef()
3948 # count how many unlimited dimensions there are.
3949 self._nunlimdim = 0
3950 for dimname in dimensions:
3951 # look in current group, and parents for dim.
3952 dim = _find_dim(self._grp, dimname)
3953 if dim.isunlimited(): self._nunlimdim = self._nunlimdim + 1
3954 # set ndim attribute (number of dimensions).
3955 with nogil:
3956 ierr = nc_inq_varndims(self._grpid, self._varid, &numdims)
3957 _ensure_nc_success(ierr)
3958 self.ndim = numdims
3959 self._name = name
3960 # default for automatically applying scale_factor and
3961 # add_offset, and converting to/from masked arrays is True.
3962 self.scale = True
3963 self.mask = True
3964 # issue 809: default for converting arrays with no missing values to
3965 # regular numpy arrays
3966 self.always_mask = True
3967 # default is to automatically convert to/from character
3968 # to string arrays when _Encoding variable attribute is set.
3969 self.chartostring = True
3970 # propagate _ncstring_attrs__ setting from parent group.
3971 self._ncstring_attrs__ = grp._ncstring_attrs__
3972 if 'least_significant_digit' in self.ncattrs():
3973 self._has_lsd = True
3974 # avoid calling nc_get_vars for strided slices by default.
3975 # a fix for strided slice access using HDF5 was added
3976 # in 4.6.2.
3977 # always use nc_get_vars for strided access with OpenDAP (issue #838).
3978 if __netcdf4libversion__ >= "4.6.2" or\
3979 self._grp.filepath().startswith('http'):
3980 self._use_get_vars = True
3981 else:
3982 self._use_get_vars = False
3983
3984 def __array__(self):
3985 # numpy special method that returns a numpy array.
3986 # allows numpy ufuncs to work faster on Variable objects
3987 # (issue 216).
3988 return self[...]
3989
3990 def __repr__(self):
3991 if python3:
3992 return self.__unicode__()
3993 else:
3994 return unicode(self).encode('utf-8')
3995
3996 def __unicode__(self):
3997 cdef int ierr, no_fill
3998 if not dir(self._grp):
3999 return 'Variable object no longer valid'
4000 ncdump = [repr(type(self))]
4001 show_more_dtype = True
4002 if self._iscompound:
4003 kind = 'compound'
4004 elif self._isvlen:
4005 kind = 'vlen'
4006 elif self._isenum:
4007 kind = 'enum'
4008 else:
4009 show_more_dtype = False
4010 kind = str(self.dtype)
4011 dimnames = tuple(_tostr(dimname) for dimname in self.dimensions)
4012 ncdump.append('%s %s(%s)' %\
4013 (kind, self._name, ', '.join(dimnames)))
4014 for name in self.ncattrs():
4015 ncdump.append(' %s: %s' % (name, self.getncattr(name)))
4016 if show_more_dtype:
4017 ncdump.append('%s data type: %s' % (kind, self.dtype))
4018 unlimdims = []
4019 for dimname in self.dimensions:
4020 dim = _find_dim(self._grp, dimname)
4021 if dim.isunlimited():
4022 unlimdims.append(dimname)
4023 if (self._grp.path != '/'): ncdump.append('path = %s' % self._grp.path)
4024 ncdump.append('unlimited dimensions: %s' % ', '.join(unlimdims))
4025 ncdump.append('current shape = %r' % (self.shape,))
4026 if __netcdf4libversion__ < '4.5.1' and\
4027 self._grp.file_format.startswith('NETCDF3'):
4028 # issue #908: no_fill not correct for NETCDF3 files before 4.5.1
4029 # before 4.5.1 there was no way to turn off filling on a
4030 # per-variable basis for classic files.
4031 no_fill=0
4032 else:
4033 with nogil:
4034 ierr = nc_inq_var_fill(self._grpid,self._varid,&no_fill,NULL)
4035 _ensure_nc_success(ierr)
4036 if self._isprimitive:
4037 if no_fill != 1:
4038 try:
4039 fillval = self._FillValue
4040 msg = 'filling on'
4041 except AttributeError:
4042 fillval = default_fillvals[self.dtype.str[1:]]
4043 if self.dtype.str[1:] in ['u1','i1']:
4044 msg = 'filling on, default _FillValue of %s ignored' % fillval
4045 else:
4046 msg = 'filling on, default _FillValue of %s used' % fillval
4047 ncdump.append(msg)
4048 else:
4049 ncdump.append('filling off')
4050
4051
4052 return '\n'.join(ncdump)
4053
4054 def _getdims(self):
4055 # Private method to get variables's dimension names
4056 cdef int ierr, numdims, n, nn
4057 cdef char namstring[NC_MAX_NAME+1]
4058 cdef int *dimids
4059 # get number of dimensions for this variable.
4060 with nogil:
4061 ierr = nc_inq_varndims(self._grpid, self._varid, &numdims)
4062 _ensure_nc_success(ierr)
4063 dimids = <int *>malloc(sizeof(int) * numdims)
4064 # get dimension ids.
4065 with nogil:
4066 ierr = nc_inq_vardimid(self._grpid, self._varid, dimids)
4067 _ensure_nc_success(ierr)
4068 # loop over dimensions, retrieve names.
4069 dimensions = ()
4070 for nn from 0 <= nn < numdims:
4071 with nogil:
4072 ierr = nc_inq_dimname(self._grpid, dimids[nn], namstring)
4073 _ensure_nc_success(ierr)
4074 name = namstring.decode('utf-8')
4075 dimensions = dimensions + (name,)
4076 free(dimids)
4077 return dimensions
4078
4079 def _getname(self):
4080 # Private method to get name associated with instance
4081 cdef int err, _grpid
4082 cdef char namstring[NC_MAX_NAME+1]
4083 _grpid = self._grp._grpid
4084 with nogil:
4085 ierr = nc_inq_varname(_grpid, self._varid, namstring)
4086 _ensure_nc_success(ierr)
4087 return namstring.decode('utf-8')
4088
4089 property name:
4090 """string name of Variable instance"""
4091 def __get__(self):
4092 return self._getname()
4093 def __set__(self,value):
4094 raise AttributeError("name cannot be altered")
4095
4096 property datatype:
4097 """numpy data type (for primitive data types) or
4098 VLType/CompoundType/EnumType instance
4099 (for compound, vlen or enum data types)"""
4100 def __get__(self):
4101 if self._iscompound:
4102 return self._cmptype
4103 elif self._isvlen:
4104 return self._vltype
4105 elif self._isenum:
4106 return self._enumtype
4107 elif self._isprimitive:
4108 return self.dtype
4109
4110 property shape:
4111 """find current sizes of all variable dimensions"""
4112 def __get__(self):
4113 shape = ()
4114 for dimname in self._getdims():
4115 # look in current group, and parents for dim.
4116 dim = _find_dim(self._grp,dimname)
4117 shape = shape + (len(dim),)
4118 return shape
4119 def __set__(self,value):
4120 raise AttributeError("shape cannot be altered")
4121
4122 property size:
4123 """Return the number of stored elements."""
4124 def __get__(self):
4125 # issue #957: add int since prod(())=1.0
4126 return int(numpy.prod(self.shape))
4127
4128 property dimensions:
4129 """get variables's dimension names"""
4130 def __get__(self):
4131 return self._getdims()
4132 def __set__(self,value):
4133 raise AttributeError("dimensions cannot be altered")
4134
4135
4136 def group(self):
4137 """
4138 **`group(self)`**
4139
4140 return the group that this `netCDF4.Variable` is a member of."""
4141 return self._grp
4142
4143 def ncattrs(self):
4144 """
4145 **`ncattrs(self)`**
4146
4147 return netCDF attribute names for this `netCDF4.Variable` in a list."""
4148 return _get_att_names(self._grpid, self._varid)
4149
4150 def setncattr(self,name,value):
4151 """
4152 **`setncattr(self,name,value)`**
4153
4154 set a netCDF variable attribute using name,value pair. Use if you need to set a
4155 netCDF attribute with the same name as one of the reserved python
4156 attributes."""
4157 cdef nc_type xtype
4158 xtype=-99
4159 # issue #959 - trying to set _FillValue results in mysterious
4160 # error when close method is called so catch it here. It is
4161 # already caught in __setattr__.
4162 if name == '_FillValue':
4163 msg='_FillValue attribute must be set when variable is '+\
4164 'created (using fill_value keyword to createVariable)'
4165 raise AttributeError(msg)
4166 if self._grp.data_model != 'NETCDF4': self._grp._redef()
4167 _set_att(self._grp, self._varid, name, value, xtype=xtype, force_ncstring=self._ncstring_attrs__)
4168 if self._grp.data_model != 'NETCDF4': self._grp._enddef()
4169
4170 def setncattr_string(self,name,value):
4171 """
4172 **`setncattr_string(self,name,value)`**
4173
4174 set a netCDF variable string attribute using name,value pair.
4175 Use if you need to ensure that a netCDF attribute is created with type
4176 `NC_STRING` if the file format is `NETCDF4`.
4177 Use if you need to set an attribute to an array of variable-length strings."""
4178 cdef nc_type xtype
4179 xtype=-99
4180 if self._grp.data_model != 'NETCDF4':
4181 msg='file format does not support NC_STRING attributes'
4182 raise IOError(msg)
4183 _set_att(self._grp, self._varid, name, value, xtype=xtype, force_ncstring=True)
4184
4185 def setncatts(self,attdict):
4186 """
4187 **`setncatts(self,attdict)`**
4188
4189 set a bunch of netCDF variable attributes at once using a python dictionary.
4190 This may be faster when setting a lot of attributes for a `NETCDF3`
4191 formatted file, since nc_redef/nc_enddef is not called in between setting
4192 each attribute"""
4193 if self._grp.data_model != 'NETCDF4': self._grp._redef()
4194 for name, value in attdict.items():
4195 _set_att(self._grp, self._varid, name, value)
4196 if self._grp.data_model != 'NETCDF4': self._grp._enddef()
4197
4198 def getncattr(self,name,encoding='utf-8'):
4199 """
4200 **`getncattr(self,name)`**
4201
4202 retrieve a netCDF variable attribute. Use if you need to set a
4203 netCDF attribute with the same name as one of the reserved python
4204 attributes.
4205
4206 option kwarg `encoding` can be used to specify the
4207 character encoding of a string attribute (default is `utf-8`)."""
4208 return _get_att(self._grp, self._varid, name, encoding=encoding)
4209
4210 def delncattr(self, name):
4211 """
4212 **`delncattr(self,name,value)`**
4213
4214 delete a netCDF variable attribute. Use if you need to delete a
4215 netCDF attribute with the same name as one of the reserved python
4216 attributes."""
4217 cdef char *attname
4218 bytestr = _strencode(name)
4219 attname = bytestr
4220 if self._grp.data_model != 'NETCDF4': self._grp._redef()
4221 ierr = nc_del_att(self._grpid, self._varid, attname)
4222 if self._grp.data_model != 'NETCDF4': self._grp._enddef()
4223 _ensure_nc_success(ierr)
4224
4225 def filters(self):
4226 """
4227 **`filters(self)`**
4228
4229 return dictionary containing HDF5 filter parameters."""
4230 cdef int ierr,ideflate,ishuffle,ideflate_level,ifletcher32
4231 filtdict = {'zlib':False,'shuffle':False,'complevel':0,'fletcher32':False}
4232 if self._grp.data_model not in ['NETCDF4_CLASSIC','NETCDF4']: return
4233 with nogil:
4234 ierr = nc_inq_var_deflate(self._grpid, self._varid, &ishuffle, &ideflate, &ideflate_level)
4235 _ensure_nc_success(ierr)
4236 with nogil:
4237 ierr = nc_inq_var_fletcher32(self._grpid, self._varid, &ifletcher32)
4238 _ensure_nc_success(ierr)
4239 if ideflate:
4240 filtdict['zlib']=True
4241 filtdict['complevel']=ideflate_level
4242 if ishuffle:
4243 filtdict['shuffle']=True
4244 if ifletcher32:
4245 filtdict['fletcher32']=True
4246 return filtdict
4247
4248 def endian(self):
4249 """
4250 **`endian(self)`**
4251
4252 return endian-ness (`little,big,native`) of variable (as stored in HDF5 file)."""
4253 cdef int ierr, iendian
4254 if self._grp.data_model not in ['NETCDF4_CLASSIC','NETCDF4']:
4255 return 'native'
4256 with nogil:
4257 ierr = nc_inq_var_endian(self._grpid, self._varid, &iendian)
4258 _ensure_nc_success(ierr)
4259 if iendian == NC_ENDIAN_LITTLE:
4260 return 'little'
4261 elif iendian == NC_ENDIAN_BIG:
4262 return 'big'
4263 else:
4264 return 'native'
4265
4266 def chunking(self):
4267 """
4268 **`chunking(self)`**
4269
4270 return variable chunking information. If the dataset is
4271 defined to be contiguous (and hence there is no chunking) the word 'contiguous'
4272 is returned. Otherwise, a sequence with the chunksize for
4273 each dimension is returned."""
4274 cdef int ierr, icontiguous, ndims
4275 cdef size_t *chunksizesp
4276 if self._grp.data_model not in ['NETCDF4_CLASSIC','NETCDF4']: return None
4277 ndims = self.ndim
4278 chunksizesp = <size_t *>malloc(sizeof(size_t) * ndims)
4279 with nogil:
4280 ierr = nc_inq_var_chunking(self._grpid, self._varid, &icontiguous, chunksizesp)
4281 _ensure_nc_success(ierr)
4282 chunksizes=[]
4283 for n from 0 <= n < ndims:
4284 chunksizes.append(chunksizesp[n])
4285 free(chunksizesp)
4286 if icontiguous:
4287 return 'contiguous'
4288 else:
4289 return chunksizes
4290
4291 def get_var_chunk_cache(self):
4292 """
4293 **`get_var_chunk_cache(self)`**
4294
4295 return variable chunk cache information in a tuple (size,nelems,preemption).
4296 See netcdf C library documentation for `nc_get_var_chunk_cache` for
4297 details."""
4298 cdef int ierr
4299 cdef size_t sizep, nelemsp
4300 cdef float preemptionp
4301 with nogil:
4302 ierr = nc_get_var_chunk_cache(self._grpid, self._varid, &sizep,
4303 &nelemsp, &preemptionp)
4304 _ensure_nc_success(ierr)
4305 size = sizep; nelems = nelemsp; preemption = preemptionp
4306 return (size,nelems,preemption)
4307
4308 def set_var_chunk_cache(self,size=None,nelems=None,preemption=None):
4309 """
4310 **`set_var_chunk_cache(self,size=None,nelems=None,preemption=None)`**
4311
4312 change variable chunk cache settings.
4313 See netcdf C library documentation for `nc_set_var_chunk_cache` for
4314 details."""
4315 cdef int ierr
4316 cdef size_t sizep, nelemsp
4317 cdef float preemptionp
4318 # reset chunk cache size, leave other parameters unchanged.
4319 size_orig, nelems_orig, preemption_orig = self.get_var_chunk_cache()
4320 if size is not None:
4321 sizep = size
4322 else:
4323 sizep = size_orig
4324 if nelems is not None:
4325 nelemsp = nelems
4326 else:
4327 nelemsp = nelems_orig
4328 if preemption is not None:
4329 preemptionp = preemption
4330 else:
4331 preemptionp = preemption_orig
4332 ierr = nc_set_var_chunk_cache(self._grpid, self._varid, sizep,
4333 nelemsp, preemptionp)
4334 _ensure_nc_success(ierr)
4335
4336 def __delattr__(self,name):
4337 # if it's a netCDF attribute, remove it
4338 if name not in _private_atts:
4339 self.delncattr(name)
4340 else:
4341 raise AttributeError(
4342 "'%s' is one of the reserved attributes %s, cannot delete. Use delncattr instead." % (name, tuple(_private_atts)))
4343
4344 def __setattr__(self,name,value):
4345 # if name in _private_atts, it is stored at the python
4346 # level and not in the netCDF file.
4347 if name not in _private_atts:
4348 # if setting _FillValue or missing_value, make sure value
4349 # has same type and byte order as variable.
4350 if name == '_FillValue':
4351 msg='_FillValue attribute must be set when variable is '+\
4352 'created (using fill_value keyword to createVariable)'
4353 raise AttributeError(msg)
4354 #if self._isprimitive:
4355 # value = numpy.array(value, self.dtype)
4356 #else:
4357 # msg="cannot set _FillValue attribute for "+\
4358 # "VLEN or compound variable"
4359 # raise AttributeError(msg)
4360 elif name in ['valid_min','valid_max','valid_range','missing_value'] and self._isprimitive:
4361 # make sure these attributes written in same data type as variable.
4362 # also make sure it is written in native byte order
4363 # (the same as the data)
4364 valuea = numpy.array(value, self.dtype)
4365 # check to see if array cast is safe
4366 if _safecast(numpy.array(value),valuea):
4367 value = valuea
4368 if not value.dtype.isnative: value.byteswap(True)
4369 else: # otherwise don't do it, but issue a warning
4370 msg="WARNING: %s cannot be safely cast to variable dtype" \
4371 % name
4372 warnings.warn(msg)
4373 self.setncattr(name, value)
4374 elif not name.endswith('__'):
4375 if hasattr(self,name):
4376 raise AttributeError(
4377 "'%s' is one of the reserved attributes %s, cannot rebind. Use setncattr instead." % (name, tuple(_private_atts)))
4378 else:
4379 self.__dict__[name]=value
4380
4381 def __getattr__(self,name):
4382 # if name in _private_atts, it is stored at the python
4383 # level and not in the netCDF file.
4384 if name.startswith('__') and name.endswith('__'):
4385 # if __dict__ requested, return a dict with netCDF attributes.
4386 if name == '__dict__':
4387 names = self.ncattrs()
4388 values = []
4389 for name in names:
4390 values.append(_get_att(self._grp, self._varid, name))
4391 gen = zip(names, values)
4392 if sys.version_info[0:2] < (3, 7):
4393 return OrderedDict(gen)
4394 else:
4395 return dict(gen)
4396
4397 else:
4398 raise AttributeError
4399 elif name in _private_atts:
4400 return self.__dict__[name]
4401 else:
4402 return self.getncattr(name)
4403
4404 def renameAttribute(self, oldname, newname):
4405 """
4406 **`renameAttribute(self, oldname, newname)`**
4407
4408 rename a `netCDF4.Variable` attribute named `oldname` to `newname`."""
4409 cdef int ierr
4410 cdef char *oldnamec
4411 cdef char *newnamec
4412 bytestr = _strencode(oldname)
4413 oldnamec = bytestr
4414 bytestr = _strencode(newname)
4415 newnamec = bytestr
4416 ierr = nc_rename_att(self._grpid, self._varid, oldnamec, newnamec)
4417 _ensure_nc_success(ierr)
4418
4419 def __getitem__(self, elem):
4420 # This special method is used to index the netCDF variable
4421 # using the "extended slice syntax". The extended slice syntax
4422 # is a perfect match for the "start", "count" and "stride"
4423 # arguments to the nc_get_var() function, and is much more easy
4424 # to use.
4425 start, count, stride, put_ind =\
4426 _StartCountStride(elem,self.shape,dimensions=self.dimensions,grp=self._grp,use_get_vars=self._use_get_vars)
4427 datashape = _out_array_shape(count)
4428 if self._isvlen:
4429 data = numpy.empty(datashape, dtype='O')
4430 else:
4431 data = numpy.empty(datashape, dtype=self.dtype)
4432
4433 # Determine which dimensions need to be
4434 # squeezed (those for which elem is an integer scalar).
4435 # The convention used is that for those cases,
4436 # put_ind for this dimension is set to -1 by _StartCountStride.
4437 squeeze = data.ndim * [slice(None),]
4438 for i,n in enumerate(put_ind.shape[:-1]):
4439 if n == 1 and put_ind[...,i].ravel()[0] == -1:
4440 squeeze[i] = 0
4441
4442 # Reshape the arrays so we can iterate over them.
4443 start = start.reshape((-1, self.ndim or 1))
4444 count = count.reshape((-1, self.ndim or 1))
4445 stride = stride.reshape((-1, self.ndim or 1))
4446 put_ind = put_ind.reshape((-1, self.ndim or 1))
4447
4448 # Fill output array with data chunks.
4449 for (a,b,c,i) in zip(start, count, stride, put_ind):
4450 datout = self._get(a,b,c)
4451 if not hasattr(datout,'shape') or data.shape == datout.shape:
4452 data = datout
4453 else:
4454 shape = getattr(data[tuple(i)], 'shape', ())
4455 if self._isvlen and not len(self.dimensions):
4456 # special case of scalar VLEN
4457 data[0] = datout
4458 else:
4459 data[tuple(i)] = datout.reshape(shape)
4460
4461 # Remove extra singleton dimensions.
4462 if hasattr(data,'shape'):
4463 data = data[tuple(squeeze)]
4464 if hasattr(data,'ndim') and self.ndim == 0:
4465 # Make sure a numpy scalar array is returned instead of a 1-d array of
4466 # length 1.
4467 if data.ndim != 0: data = numpy.asarray(data[0])
4468
4469 # if auto_scale mode set to True, (through
4470 # a call to set_auto_scale or set_auto_maskandscale),
4471 # perform automatic unpacking using scale_factor/add_offset.
4472 # if auto_mask mode is set to True (through a call to
4473 # set_auto_mask or set_auto_maskandscale), perform
4474 # automatic conversion to masked array using
4475 # missing_value/_Fill_Value.
4476 # applied for primitive and (non-string) vlen,
4477 # ignored for compound and enum datatypes.
4478 try: # check to see if scale_factor and add_offset is valid (issue 176).
4479 if hasattr(self,'scale_factor'): float(self.scale_factor)
4480 if hasattr(self,'add_offset'): float(self.add_offset)
4481 valid_scaleoffset = True
4482 except:
4483 valid_scaleoffset = False
4484 if self.scale:
4485 msg = 'invalid scale_factor or add_offset attribute, no unpacking done...'
4486 warnings.warn(msg)
4487
4488 if self.mask and\
4489 (self._isprimitive or self._isenum or\
4490 (self._isvlen and self.dtype != str)):
4491 data = self._toma(data)
4492 else:
4493 # if attribute _Unsigned is True, and variable has signed integer
4494 # dtype, return view with corresponding unsigned dtype (issue #656)
4495 if self.scale: # only do this if autoscale option is on.
4496 is_unsigned = getattr(self, '_Unsigned', False)
4497 if is_unsigned and data.dtype.kind == 'i':
4498 data=data.view('%su%s'%(data.dtype.byteorder,data.dtype.itemsize))
4499
4500 if self.scale and\
4501 (self._isprimitive or (self._isvlen and self.dtype != str)) and\
4502 valid_scaleoffset:
4503 # if variable has scale_factor and add_offset attributes, apply
4504 # them.
4505 if hasattr(self, 'scale_factor') and hasattr(self, 'add_offset'):
4506 if self.add_offset != 0.0 or self.scale_factor != 1.0:
4507 data = data*self.scale_factor + self.add_offset
4508 else:
4509 data = data.astype(self.scale_factor.dtype) # issue 913
4510 # else if variable has only scale_factor attribute, rescale.
4511 elif hasattr(self, 'scale_factor') and self.scale_factor != 1.0:
4512 data = data*self.scale_factor
4513 # else if variable has only add_offset attribute, add offset.
4514 elif hasattr(self, 'add_offset') and self.add_offset != 0.0:
4515 data = data + self.add_offset
4516
4517 # if _Encoding is specified for a character variable, return
4518 # a numpy array of strings with one less dimension.
4519 if self.chartostring and getattr(self.dtype,'kind',None) == 'S' and\
4520 getattr(self.dtype,'itemsize',None) == 1:
4521 encoding = getattr(self,'_Encoding',None)
4522 # should this only be done if self.scale = True?
4523 # should there be some other way to disable this?
4524 if encoding is not None:
4525 # only try to return a string array if rightmost dimension of
4526 # sliced data matches rightmost dimension of char variable
4527 if len(data.shape) > 0 and data.shape[-1] == self.shape[-1]:
4528 # also make sure slice is along last dimension
4529 matchdim = True
4530 for cnt in count:
4531 if cnt[-1] != self.shape[-1]:
4532 matchdim = False
4533 break
4534 if matchdim:
4535 data = chartostring(data, encoding=encoding)
4536
4537 # if structure array contains char arrays, return view as strings
4538 # if _Encoding att set (issue #773)
4539 if self._iscompound and \
4540 self._cmptype.dtype != self._cmptype.dtype_view and \
4541 self.chartostring:
4542 # self.chartostring and getattr(self,'_Encoding',None) is not None:
4543 data = data.view(self._cmptype.dtype_view)
4544 return data
4545
4546 def _toma(self,data):
4547 cdef int ierr, no_fill
4548 # if attribute _Unsigned is True, and variable has signed integer
4549 # dtype, return view with corresponding unsigned dtype (issues #656,
4550 # #794)
4551 is_unsigned = getattr(self, '_Unsigned', False)
4552 is_unsigned_int = is_unsigned and data.dtype.kind == 'i'
4553 if self.scale and is_unsigned_int: # only do this if autoscale option is on.
4554 dtype_unsigned_int='%su%s' % (data.dtype.byteorder,data.dtype.itemsize)
4555 data = data.view(dtype_unsigned_int)
4556 # private function for creating a masked array, masking missing_values
4557 # and/or _FillValues.
4558 totalmask = numpy.zeros(data.shape, numpy.bool)
4559 fill_value = None
4560 safe_missval = self._check_safecast('missing_value')
4561 if safe_missval:
4562 mval = numpy.array(self.missing_value, self.dtype)
4563 if self.scale and is_unsigned_int:
4564 mval = mval.view(dtype_unsigned_int)
4565 # create mask from missing values.
4566 mvalmask = numpy.zeros(data.shape, numpy.bool)
4567 if mval.shape == (): # mval a scalar.
4568 mval = [mval] # make into iterable.
4569 for m in mval:
4570 # is scalar missing value a NaN?
4571 try:
4572 mvalisnan = numpy.isnan(m)
4573 except TypeError: # isnan fails on some dtypes (issue 206)
4574 mvalisnan = False
4575 if mvalisnan:
4576 mvalmask += numpy.isnan(data)
4577 else:
4578 mvalmask += data==m
4579 if mvalmask.any():
4580 # set fill_value for masked array
4581 # to missing_value (or 1st element
4582 # if missing_value is a vector).
4583 fill_value = mval[0]
4584 totalmask += mvalmask
4585 # set mask=True for data == fill value
4586 safe_fillval = self._check_safecast('_FillValue')
4587 if safe_fillval:
4588 fval = numpy.array(self._FillValue, self.dtype)
4589 if self.scale and is_unsigned_int:
4590 fval = fval.view(dtype_unsigned_int)
4591 # is _FillValue a NaN?
4592 try:
4593 fvalisnan = numpy.isnan(fval)
4594 except: # isnan fails on some dtypes (issue 202)
4595 fvalisnan = False
4596 if fvalisnan:
4597 mask = numpy.isnan(data)
4598 elif (data == fval).any():
4599 mask = data==fval
4600 else:
4601 mask = None
4602 if mask is not None:
4603 if fill_value is None:
4604 fill_value = fval
4605 totalmask += mask
4606 # issue 209: don't return masked array if variable filling
4607 # is disabled.
4608 else:
4609 if __netcdf4libversion__ < '4.5.1' and\
4610 self._grp.file_format.startswith('NETCDF3'):
4611 # issue #908: no_fill not correct for NETCDF3 files before 4.5.1
4612 # before 4.5.1 there was no way to turn off filling on a
4613 # per-variable basis for classic files.
4614 no_fill=0
4615 else:
4616 with nogil:
4617 ierr = nc_inq_var_fill(self._grpid,self._varid,&no_fill,NULL)
4618 _ensure_nc_success(ierr)
4619 # if no_fill is not 1, and not a byte variable, then use default fill value.
4620 # from http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-c/Fill-Values.html#Fill-Values
4621 # "If you need a fill value for a byte variable, it is recommended
4622 # that you explicitly define an appropriate _FillValue attribute, as
4623 # generic utilities such as ncdump will not assume a default fill
4624 # value for byte variables."
4625 # Explained here too:
4626 # http://www.unidata.ucar.edu/software/netcdf/docs/known_problems.html#ncdump_ubyte_fill
4627 # "There should be no default fill values when reading any byte
4628 # type, signed or unsigned, because the byte ranges are too
4629 # small to assume one of the values should appear as a missing
4630 # value unless a _FillValue attribute is set explicitly."
4631 if no_fill != 1 or self.dtype.str[1:] not in ['u1','i1']:
4632 fillval = numpy.array(default_fillvals[self.dtype.str[1:]],self.dtype)
4633 has_fillval = data == fillval
4634 # if data is an array scalar, has_fillval will be a boolean.
4635 # in that case convert to an array.
4636 if type(has_fillval) == bool: has_fillval=numpy.asarray(has_fillval)
4637 if has_fillval.any():
4638 if fill_value is None:
4639 fill_value = fillval
4640 mask=data==fillval
4641 totalmask += mask
4642 # set mask=True for data outside valid_min,valid_max.
4643 # (issue #576)
4644 validmin = None; validmax = None
4645 # if valid_range exists use that, otherwise
4646 # look for valid_min, valid_max. No special
4647 # treatment of byte data as described at
4648 # http://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html).
4649 safe_validrange = self._check_safecast('valid_range')
4650 safe_validmin = self._check_safecast('valid_min')
4651 safe_validmax = self._check_safecast('valid_max')
4652 if safe_validrange and self.valid_range.size == 2:
4653 validmin = numpy.array(self.valid_range[0], self.dtype)
4654 validmax = numpy.array(self.valid_range[1], self.dtype)
4655 else:
4656 if safe_validmin:
4657 validmin = numpy.array(self.valid_min, self.dtype)
4658 if safe_validmax:
4659 validmax = numpy.array(self.valid_max, self.dtype)
4660 if validmin is not None and self.scale and is_unsigned_int:
4661 validmin = validmin.view(dtype_unsigned_int)
4662 if validmax is not None and self.scale and is_unsigned_int:
4663 validmax = validmax.view(dtype_unsigned_int)
4664 # http://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html).
4665 # "If the data type is byte and _FillValue
4666 # is not explicitly defined,
4667 # then the valid range should include all possible values.
4668 # Otherwise, the valid range should exclude the _FillValue
4669 # (whether defined explicitly or by default) as follows.
4670 # If the _FillValue is positive then it defines a valid maximum,
4671 # otherwise it defines a valid minimum."
4672 byte_type = self.dtype.str[1:] in ['u1','i1']
4673 if safe_fillval:
4674 fval = numpy.array(self._FillValue, self.dtype)
4675 else:
4676 fval = numpy.array(default_fillvals[self.dtype.str[1:]],self.dtype)
4677 if byte_type: fval = None
4678 if self.dtype.kind != 'S': # don't set mask for character data
4679 # issues #761 and #748: setting valid_min/valid_max to the
4680 # _FillVaue is too surprising for many users (despite the
4681 # netcdf docs attribute best practices suggesting clients
4682 # should do this).
4683 #if validmin is None and (fval is not None and fval <= 0):
4684 # validmin = fval
4685 #if validmax is None and (fval is not None and fval > 0):
4686 # validmax = fval
4687 if validmin is not None:
4688 totalmask += data < validmin
4689 if validmax is not None:
4690 totalmask += data > validmax
4691 if fill_value is None and fval is not None:
4692 fill_value = fval
4693 # if all else fails, use default _FillValue as fill_value
4694 # for masked array.
4695 if fill_value is None:
4696 fill_value = default_fillvals[self.dtype.str[1:]]
4697 # create masked array with computed mask
4698 masked_values = bool(totalmask.any())
4699 if masked_values:
4700 data = ma.masked_array(data,mask=totalmask,fill_value=fill_value)
4701 else:
4702 # issue #785: always return masked array, if no values masked
4703 data = ma.masked_array(data)
4704 # issue 515 scalar array with mask=True should be converted
4705 # to numpy.ma.MaskedConstant to be consistent with slicing
4706 # behavior of masked arrays.
4707 if data.shape == () and data.mask.all():
4708 # return a scalar numpy masked constant not a 0-d masked array,
4709 # so that data == numpy.ma.masked.
4710 data = data[()] # changed from [...] (issue #662)
4711 elif not self.always_mask and not masked_values:
4712 # issue #809: return a regular numpy array if requested
4713 # and there are no missing values
4714 data = numpy.array(data, copy=False)
4715
4716 return data
4717
4718 def _pack(self,data):
4719 # pack non-masked values using scale_factor and add_offset
4720 if hasattr(self, 'scale_factor') and hasattr(self, 'add_offset'):
4721 data = (data - self.add_offset)/self.scale_factor
4722 if self.dtype.kind in 'iu': data = numpy.around(data)
4723 elif hasattr(self, 'scale_factor'):
4724 data = data/self.scale_factor
4725 if self.dtype.kind in 'iu': data = numpy.around(data)
4726 elif hasattr(self, 'add_offset'):
4727 data = data - self.add_offset
4728 if self.dtype.kind in 'iu': data = numpy.around(data)
4729 if ma.isMA(data):
4730 # if underlying data in masked regions of masked array
4731 # corresponds to missing values, don't fill masked array -
4732 # just use underlying data instead
4733 if hasattr(self, 'missing_value') and \
4734 numpy.all(numpy.in1d(data.data[data.mask],self.missing_value)):
4735 data = data.data
4736 else:
4737 if hasattr(self, 'missing_value'):
4738 # if missing value is a scalar, use it as fill_value.
4739 # if missing value is a vector, raise an exception
4740 # since we then don't know how to fill in masked values.
4741 if numpy.array(self.missing_value).shape == ():
4742 fillval = self.missing_value
4743 else:
4744 msg="cannot assign fill_value for masked array when missing_value attribute is not a scalar"
4745 raise RuntimeError(msg)
4746 if numpy.array(fillval).shape != ():
4747 fillval = fillval[0]
4748 elif hasattr(self, '_FillValue'):
4749 fillval = self._FillValue
4750 else:
4751 fillval = default_fillvals[self.dtype.str[1:]]
4752 # some versions of numpy have trouble handling
4753 # MaskedConstants when filling - this is is
4754 # a workaround (issue #850)
4755 if data.shape == (1,) and data.mask.all():
4756 data = numpy.array([fillval],self.dtype)
4757 else:
4758 data = data.filled(fill_value=fillval)
4759 if self.dtype != data.dtype:
4760 data = data.astype(self.dtype) # cast data to var type, if necessary.
4761 return data
4762
4763 def _assign_vlen(self, elem, data):
4764 """private method to assign data to a single item in a VLEN variable"""
4765 cdef size_t *startp
4766 cdef size_t *countp
4767 cdef int ndims, n
4768 cdef nc_vlen_t *vldata
4769 cdef char **strdata
4770 cdef ndarray data2
4771 if not self._isvlen:
4772 raise TypeError('_assign_vlen method only for use with VLEN variables')
4773 ndims = self.ndim
4774 msg="data can only be assigned to VLEN variables using integer indices"
4775 # check to see that elem is a tuple of integers.
4776 # handle negative integers.
4777 if _is_int(elem):
4778 if ndims > 1:
4779 raise IndexError(msg)
4780 if elem < 0:
4781 if self.shape[0]+elem >= 0:
4782 elem = self.shape[0]+elem
4783 else:
4784 raise IndexError("Illegal index")
4785 elif isinstance(elem, tuple):
4786 if len(elem) != ndims:
4787 raise IndexError("Illegal index")
4788 elemnew = []
4789 for n,e in enumerate(elem):
4790 if not _is_int(e):
4791 raise IndexError(msg)
4792 elif e < 0:
4793 enew = self.shape[n]+e
4794 if enew < 0:
4795 raise IndexError("Illegal index")
4796 else:
4797 elemnew.append(self.shape[n]+e)
4798 else:
4799 elemnew.append(e)
4800 elem = tuple(elemnew)
4801 else:
4802 raise IndexError(msg)
4803 # set start, count
4804 if isinstance(elem, tuple):
4805 start = list(elem)
4806 else:
4807 start = [elem]
4808 count = [1]*ndims
4809 startp = <size_t *>malloc(sizeof(size_t) * ndims)
4810 countp = <size_t *>malloc(sizeof(size_t) * ndims)
4811 for n from 0 <= n < ndims:
4812 startp[n] = start[n]
4813 countp[n] = count[n]
4814 if self.dtype == str: # VLEN string
4815 strdata = <char **>malloc(sizeof(char *))
4816 # use _Encoding attribute to specify string encoding - if
4817 # not given, use 'utf-8'.
4818 encoding = getattr(self,'_Encoding','utf-8')
4819 bytestr = _strencode(data,encoding=encoding)
4820 strdata[0] = bytestr
4821 ierr = nc_put_vara(self._grpid, self._varid,
4822 startp, countp, strdata)
4823 _ensure_nc_success(ierr)
4824 free(strdata)
4825 else: # regular VLEN
4826 if data.dtype != self.dtype:
4827 raise TypeError("wrong data type: should be %s, got %s" % (self.dtype,data.dtype))
4828 data2 = data
4829 vldata = <nc_vlen_t *>malloc(sizeof(nc_vlen_t))
4830 vldata[0].len = PyArray_SIZE(data2)
4831 vldata[0].p = data2.data
4832 ierr = nc_put_vara(self._grpid, self._varid,
4833 startp, countp, vldata)
4834 _ensure_nc_success(ierr)
4835 free(vldata)
4836 free(startp)
4837 free(countp)
4838
4839 def _check_safecast(self, attname):
4840 # check to see that variable attribute exists
4841 # can can be safely cast to variable data type.
4842 if hasattr(self, attname):
4843 att = numpy.array(self.getncattr(attname))
4844 else:
4845 return False
4846 atta = numpy.array(att, self.dtype)
4847 is_safe = _safecast(att,atta)
4848 if not is_safe:
4849 msg="""WARNING: %s not used since it
4850 cannot be safely cast to variable data type""" % attname
4851 warnings.warn(msg)
4852 return is_safe
4853
4854 def __setitem__(self, elem, data):
4855 # This special method is used to assign to the netCDF variable
4856 # using "extended slice syntax". The extended slice syntax
4857 # is a perfect match for the "start", "count" and "stride"
4858 # arguments to the nc_put_var() function, and is much more easy
4859 # to use.
4860
4861 # if _Encoding is specified for a character variable, convert
4862 # numpy array of strings to a numpy array of characters with one more
4863 # dimension.
4864 if self.chartostring and getattr(self.dtype,'kind',None) == 'S' and\
4865 getattr(self.dtype,'itemsize',None) == 1:
4866 # NC_CHAR variable
4867 encoding = getattr(self,'_Encoding',None)
4868 if encoding is not None:
4869 # _Encoding attribute is set
4870 # if data is a string or a bytes object, convert to a numpy string array
4871 # whose length is equal to the rightmost dimension of the
4872 # variable.
4873 if type(data) in [str,bytes]: data = numpy.asarray(data,dtype='S'+repr(self.shape[-1]))
4874 if data.dtype.kind in ['S','U'] and data.dtype.itemsize > 1:
4875 # if data is a numpy string array, convert it to an array
4876 # of characters with one more dimension.
4877 data = stringtochar(data, encoding=encoding)
4878
4879 # if structured data has strings (and _Encoding att set), create view as char arrays
4880 # (issue #773)
4881 if self._iscompound and \
4882 self._cmptype.dtype != self._cmptype.dtype_view and \
4883 _set_viewdtype(data.dtype) == self._cmptype.dtype_view and \
4884 self.chartostring:
4885 # self.chartostring and getattr(self,'_Encoding',None) is not None:
4886 # may need to cast input data to aligned type
4887 data = data.astype(self._cmptype.dtype_view).view(self._cmptype.dtype)
4888
4889 if self._isvlen: # if vlen, should be object array (don't try casting)
4890 if self.dtype == str:
4891 # for string vars, if data is not an array
4892 # assume it is a python string and raise an error
4893 # if it is an array, but not an object array.
4894 if not isinstance(data, numpy.ndarray):
4895 # issue 458, allow Ellipsis to be used for scalar var
4896 if type(elem) == type(Ellipsis) and not\
4897 len(self.dimensions): elem = 0
4898 self._assign_vlen(elem, data)
4899 return
4900 elif data.dtype.kind in ['S', 'U']:
4901 if ma.isMA(data):
4902 msg='masked arrays cannot be assigned by VLEN str slices'
4903 raise TypeError(msg)
4904 data = data.astype(object)
4905 elif data.dtype.kind != 'O':
4906 msg = ('only numpy string, unicode or object arrays can '
4907 'be assigned to VLEN str var slices')
4908 raise TypeError(msg)
4909 else:
4910 # for non-string vlen arrays, if data is not multi-dim, or
4911 # not an object array, assume it represents a single element
4912 # of the vlen var.
4913 if not isinstance(data, numpy.ndarray) or data.dtype.kind != 'O':
4914 # issue 458, allow Ellipsis to be used for scalar var
4915 if type(elem) == type(Ellipsis) and not\
4916 len(self.dimensions): elem = 0
4917 # pack as integers if desired.
4918 if self.scale:
4919 data = self._pack(data)
4920 self._assign_vlen(elem, data)
4921 return
4922
4923 # A numpy or masked array (or an object supporting the buffer interface) is needed.
4924 # Convert if necessary.
4925 if not ma.isMA(data) and not (hasattr(data,'data') and isinstance(data.data,buffer)):
4926 # if auto scaling is to be done, don't cast to an integer yet.
4927 if self.scale and self.dtype.kind in 'iu' and \
4928 hasattr(self, 'scale_factor') or hasattr(self, 'add_offset'):
4929 data = numpy.array(data,numpy.float)
4930 else:
4931 data = numpy.array(data,self.dtype)
4932
4933 # for Enum variable, make sure data is valid.
4934 if self._isenum:
4935 test = numpy.zeros(data.shape,numpy.bool)
4936 if ma.isMA(data):
4937 # fix for new behaviour in numpy.ma in 1.13 (issue #662)
4938 for val in self.datatype.enum_dict.values():
4939 test += data.filled() == val
4940 else:
4941 for val in self.datatype.enum_dict.values():
4942 test += data == val
4943 if not numpy.all(test):
4944 msg="trying to assign illegal value to Enum variable"
4945 raise ValueError(msg)
4946
4947 start, count, stride, put_ind =\
4948 _StartCountStride(elem,self.shape,self.dimensions,self._grp,datashape=data.shape,put=True)
4949 datashape = _out_array_shape(count)
4950
4951 # if a numpy scalar, create an array of the right size
4952 # and fill with scalar values.
4953 if data.shape == ():
4954 data = numpy.tile(data,datashape)
4955 # reshape data array by adding extra dimensions
4956 # if needed to conform with start,count,stride.
4957 if len(data.shape) != len(datashape):
4958 # create a view so shape in caller is not modified (issue 90)
4959 try: # if extra singleton dims, just reshape
4960 data = data.view()
4961 data.shape = tuple(datashape)
4962 except ValueError: # otherwise broadcast
4963 data = numpy.broadcast_to(data, datashape)
4964
4965 # Reshape these arrays so we can iterate over them.
4966 start = start.reshape((-1, self.ndim or 1))
4967 count = count.reshape((-1, self.ndim or 1))
4968 stride = stride.reshape((-1, self.ndim or 1))
4969 put_ind = put_ind.reshape((-1, self.ndim or 1))
4970
4971 # quantize data if least_significant_digit attribute
4972 # exists (improves compression).
4973 if self._has_lsd:
4974 data = _quantize(data,self.least_significant_digit)
4975
4976 if self.scale and self._isprimitive:
4977 # pack non-masked values using scale_factor and add_offset
4978 data = self._pack(data)
4979
4980 # Fill output array with data chunks.
4981 for (a,b,c,i) in zip(start, count, stride, put_ind):
4982 dataput = data[tuple(i)]
4983 if dataput.size == 0: continue # nothing to write
4984 # convert array scalar to regular array with one element.
4985 if dataput.shape == ():
4986 if self._isvlen:
4987 dataput=numpy.array(dataput,'O')
4988 else:
4989 dataput=numpy.array(dataput,dataput.dtype)
4990 self._put(dataput,a,b,c)
4991
4992
4993 def __len__(self):
4994 if not self.shape:
4995 raise TypeError('len() of unsized object')
4996 else:
4997 return self.shape[0]
4998
4999
5000 def assignValue(self,val):
5001 """
5002 **`assignValue(self, val)`**
5003
5004 assign a value to a scalar variable. Provided for compatibility with
5005 Scientific.IO.NetCDF, can also be done by assigning to an Ellipsis slice ([...])."""
5006 if len(self.dimensions):
5007 raise IndexError('to assign values to a non-scalar variable, use a slice')
5008 self[:]=val
5009
5010 def getValue(self):
5011 """
5012 **`getValue(self)`**
5013
5014 get the value of a scalar variable. Provided for compatibility with
5015 Scientific.IO.NetCDF, can also be done by slicing with an Ellipsis ([...])."""
5016 if len(self.dimensions):
5017 raise IndexError('to retrieve values from a non-scalar variable, use slicing')
5018 return self[slice(None)]
5019
5020 def set_auto_chartostring(self,chartostring):
5021 """
5022 **`set_auto_chartostring(self,chartostring)`**
5023
5024 turn on or off automatic conversion of character variable data to and
5025 from numpy fixed length string arrays when the `_Encoding` variable attribute
5026 is set.
5027
5028 If `chartostring` is set to `True`, when data is read from a character variable
5029 (dtype = `S1`) that has an `_Encoding` attribute, it is converted to a numpy
5030 fixed length unicode string array (dtype = `UN`, where `N` is the length
5031 of the the rightmost dimension of the variable). The value of `_Encoding`
5032 is the unicode encoding that is used to decode the bytes into strings.
5033
5034 When numpy string data is written to a variable it is converted back to
5035 indiviual bytes, with the number of bytes in each string equalling the
5036 rightmost dimension of the variable.
5037
5038 The default value of `chartostring` is `True`
5039 (automatic conversions are performed).
5040 """
5041 self.chartostring = bool(chartostring)
5042
5043 def use_nc_get_vars(self,use_nc_get_vars):
5044 """
5045 **`use_nc_get_vars(self,_use_get_vars)`**
5046
5047 enable the use of netcdf library routine `nc_get_vars`
5048 to retrieve strided variable slices. By default,
5049 `nc_get_vars` may not used by default (depending on the
5050 version of the netcdf-c library being used) since it may be
5051 slower than multiple calls to the unstrided read routine `nc_get_vara`.
5052 """
5053 self._use_get_vars = bool(use_nc_get_vars)
5054
5055 def set_auto_maskandscale(self,maskandscale):
5056 """
5057 **`set_auto_maskandscale(self,maskandscale)`**
5058
5059 turn on or off automatic conversion of variable data to and
5060 from masked arrays, automatic packing/unpacking of variable
5061 data using `scale_factor` and `add_offset` attributes and
5062 automatic conversion of signed integer data to unsigned integer
5063 data if the `_Unsigned` attribute exists.
5064
5065 If `maskandscale` is set to `True`, when data is read from a variable
5066 it is converted to a masked array if any of the values are exactly
5067 equal to the either the netCDF _FillValue or the value specified by the
5068 missing_value variable attribute. The fill_value of the masked array
5069 is set to the missing_value attribute (if it exists), otherwise
5070 the netCDF _FillValue attribute (which has a default value
5071 for each data type). When data is written to a variable, the masked
5072 array is converted back to a regular numpy array by replacing all the
5073 masked values by the missing_value attribute of the variable (if it
5074 exists). If the variable has no missing_value attribute, the _FillValue
5075 is used instead. If the variable has valid_min/valid_max and
5076 missing_value attributes, data outside the specified range will be
5077 set to missing_value.
5078
5079 If `maskandscale` is set to `True`, and the variable has a
5080 `scale_factor` or an `add_offset` attribute, then data read
5081 from that variable is unpacked using::
5082
5083 data = self.scale_factor*data + self.add_offset
5084
5085 When data is written to a variable it is packed using::
5086
5087 data = (data - self.add_offset)/self.scale_factor
5088
5089 If either scale_factor is present, but add_offset is missing, add_offset
5090 is assumed zero. If add_offset is present, but scale_factor is missing,
5091 scale_factor is assumed to be one.
5092 For more information on how `scale_factor` and `add_offset` can be
5093 used to provide simple compression, see the
5094 [PSD metadata conventions](http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml).
5095
5096 In addition, if `maskandscale` is set to `True`, and if the variable has an
5097 attribute `_Unsigned` set, and the variable has a signed integer data type,
5098 a view to the data is returned with the corresponding unsigned integer data type.
5099 This convention is used by the netcdf-java library to save unsigned integer
5100 data in `NETCDF3` or `NETCDF4_CLASSIC` files (since the `NETCDF3`
5101 data model does not have unsigned integer data types).
5102
5103 The default value of `maskandscale` is `True`
5104 (automatic conversions are performed).
5105 """
5106 self.scale = self.mask = bool(maskandscale)
5107
5108 def set_auto_scale(self,scale):
5109 """
5110 **`set_auto_scale(self,scale)`**
5111
5112 turn on or off automatic packing/unpacking of variable
5113 data using `scale_factor` and `add_offset` attributes.
5114 Also turns on and off automatic conversion of signed integer data
5115 to unsigned integer data if the variable has an `_Unsigned`
5116 attribute.
5117
5118 If `scale` is set to `True`, and the variable has a
5119 `scale_factor` or an `add_offset` attribute, then data read
5120 from that variable is unpacked using::
5121
5122 data = self.scale_factor*data + self.add_offset
5123
5124 When data is written to a variable it is packed using::
5125
5126 data = (data - self.add_offset)/self.scale_factor
5127
5128 If either scale_factor is present, but add_offset is missing, add_offset
5129 is assumed zero. If add_offset is present, but scale_factor is missing,
5130 scale_factor is assumed to be one.
5131 For more information on how `scale_factor` and `add_offset` can be
5132 used to provide simple compression, see the
5133 [PSD metadata conventions](http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml).
5134
5135 In addition, if `scale` is set to `True`, and if the variable has an
5136 attribute `_Unsigned` set, and the variable has a signed integer data type,
5137 a view to the data is returned with the corresponding unsigned integer datatype.
5138 This convention is used by the netcdf-java library to save unsigned integer
5139 data in `NETCDF3` or `NETCDF4_CLASSIC` files (since the `NETCDF3`
5140 data model does not have unsigned integer data types).
5141
5142 The default value of `scale` is `True`
5143 (automatic conversions are performed).
5144 """
5145 self.scale = bool(scale)
5146
5147 def set_auto_mask(self,mask):
5148 """
5149 **`set_auto_mask(self,mask)`**
5150
5151 turn on or off automatic conversion of variable data to and
5152 from masked arrays .
5153
5154 If `mask` is set to `True`, when data is read from a variable
5155 it is converted to a masked array if any of the values are exactly
5156 equal to the either the netCDF _FillValue or the value specified by the
5157 missing_value variable attribute. The fill_value of the masked array
5158 is set to the missing_value attribute (if it exists), otherwise
5159 the netCDF _FillValue attribute (which has a default value
5160 for each data type). When data is written to a variable, the masked
5161 array is converted back to a regular numpy array by replacing all the
5162 masked values by the missing_value attribute of the variable (if it
5163 exists). If the variable has no missing_value attribute, the _FillValue
5164 is used instead. If the variable has valid_min/valid_max and
5165 missing_value attributes, data outside the specified range will be
5166 set to missing_value.
5167
5168 The default value of `mask` is `True`
5169 (automatic conversions are performed).
5170 """
5171 self.mask = bool(mask)
5172
5173 def set_always_mask(self,always_mask):
5174 """
5175 **`set_always_mask(self,always_mask)`**
5176
5177 turn on or off conversion of data without missing values to regular
5178 numpy arrays.
5179
5180 `always_mask` is a Boolean determining if automatic conversion of
5181 masked arrays with no missing values to regular numpy arrays shall be
5182 applied. Default is True. Set to False to restore the default behaviour
5183 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
5184 otherwise masked array returned).
5185 """
5186 self.always_mask = bool(always_mask)
5187
5188 def set_ncstring_attrs(self,ncstring_attrs):
5189 """
5190 **`set_always_mask(self,ncstring_attrs)`**
5191
5192 turn on or off creating NC_STRING string attributes.
5193
5194 If `ncstring_attrs` is set to `True` then text attributes will be variable-length
5195 NC_STRINGs.
5196
5197 The default value of `ncstring_attrs` is `False` (writing ascii text attributes as
5198 NC_CHAR).
5199
5200 """
5201 self._ncstring_attrs__ = bool(ncstring_attrs)
5202
5203 def _put(self,ndarray data,start,count,stride):
5204 """Private method to put data into a netCDF variable"""
5205 cdef int ierr, ndims
5206 cdef npy_intp totelem
5207 cdef size_t *startp
5208 cdef size_t *countp
5209 cdef ptrdiff_t *stridep
5210 cdef char **strdata
5211 cdef void* elptr
5212 cdef char* databuff
5213 cdef ndarray dataarr
5214 cdef nc_vlen_t *vldata
5215 # rank of variable.
5216 ndims = len(self.dimensions)
5217 # make sure data is contiguous.
5218 # if not, make a local copy.
5219 if not PyArray_ISCONTIGUOUS(data):
5220 data = data.copy()
5221 # fill up startp,countp,stridep.
5222 totelem = 1
5223 negstride = 0
5224 sl = []
5225 startp = <size_t *>malloc(sizeof(size_t) * ndims)
5226 countp = <size_t *>malloc(sizeof(size_t) * ndims)
5227 stridep = <ptrdiff_t *>malloc(sizeof(ptrdiff_t) * ndims)
5228 for n from 0 <= n < ndims:
5229 count[n] = abs(count[n]) # make -1 into +1
5230 countp[n] = count[n]
5231 # for neg strides, reverse order (then flip that axis after data read in)
5232 if stride[n] < 0:
5233 negstride = 1
5234 stridep[n] = -stride[n]
5235 startp[n] = start[n]+stride[n]*(count[n]-1)
5236 stride[n] = -stride[n]
5237 sl.append(slice(None, None, -1)) # this slice will reverse the data
5238 else:
5239 startp[n] = start[n]
5240 stridep[n] = stride[n]
5241 sl.append(slice(None,None, 1))
5242 totelem = totelem*countp[n]
5243 # check to see that size of data array is what is expected
5244 # for slice given.
5245 dataelem = PyArray_SIZE(data)
5246 if totelem != dataelem:
5247 raise IndexError('size of data array does not conform to slice')
5248 if negstride:
5249 # reverse data along axes with negative strides.
5250 data = data[tuple(sl)].copy() # make sure a copy is made.
5251 if self._isprimitive or self._iscompound or self._isenum:
5252 # primitive, enum or compound data type.
5253 # if data type of array doesn't match variable,
5254 # try to cast the data.
5255 if self.dtype != data.dtype:
5256 data = data.astype(self.dtype) # cast data, if necessary.
5257 # byte-swap data in numpy array so that is has native
5258 # endian byte order (this is what netcdf-c expects -
5259 # issue #554, pull request #555)
5260 if not data.dtype.isnative:
5261 data = data.byteswap()
5262 # strides all 1 or scalar variable, use put_vara (faster)
5263 if sum(stride) == ndims or ndims == 0:
5264 ierr = nc_put_vara(self._grpid, self._varid,
5265 startp, countp, data.data)
5266 else:
5267 ierr = nc_put_vars(self._grpid, self._varid,
5268 startp, countp, stridep, data.data)
5269 _ensure_nc_success(ierr)
5270 elif self._isvlen:
5271 if data.dtype.char !='O':
5272 raise TypeError('data to put in string variable must be an object array containing Python strings')
5273 # flatten data array.
5274 data = data.flatten()
5275 if self.dtype == str:
5276 # convert all elements from strings to bytes
5277 # use _Encoding attribute to specify string encoding - if
5278 # not given, use 'utf-8'.
5279 encoding = getattr(self,'_Encoding','utf-8')
5280 for n in range(data.shape[0]):
5281 data[n] = _strencode(data[n],encoding=encoding)
5282 # vlen string (NC_STRING)
5283 # loop over elements of object array, put data buffer for
5284 # each element in struct.
5285 # allocate struct array to hold vlen data.
5286 strdata = <char **>malloc(sizeof(char *)*totelem)
5287 for i from 0<=i<totelem:
5288 strdata[i] = data[i]
5289 # strides all 1 or scalar variable, use put_vara (faster)
5290 if sum(stride) == ndims or ndims == 0:
5291 ierr = nc_put_vara(self._grpid, self._varid,
5292 startp, countp, strdata)
5293 else:
5294 raise IndexError('strides must all be 1 for string variables')
5295 #ierr = nc_put_vars(self._grpid, self._varid,
5296 # startp, countp, stridep, strdata)
5297 _ensure_nc_success(ierr)
5298 free(strdata)
5299 else:
5300 # regular vlen.
5301 # loop over elements of object array, put data buffer for
5302 # each element in struct.
5303 databuff = data.data
5304 # allocate struct array to hold vlen data.
5305 vldata = <nc_vlen_t *>malloc(<size_t>totelem*sizeof(nc_vlen_t))
5306 for i from 0<=i<totelem:
5307 elptr = (<void**>databuff)[0]
5308 dataarr = <ndarray>elptr
5309 if self.dtype != dataarr.dtype.str[1:]:
5310 #dataarr = dataarr.astype(self.dtype) # cast data, if necessary.
5311 # casting doesn't work ?? just raise TypeError
5312 raise TypeError("wrong data type in object array: should be %s, got %s" % (self.dtype,dataarr.dtype))
5313 vldata[i].len = PyArray_SIZE(dataarr)
5314 vldata[i].p = dataarr.data
5315 databuff = databuff + data.strides[0]
5316 # strides all 1 or scalar variable, use put_vara (faster)
5317 if sum(stride) == ndims or ndims == 0:
5318 ierr = nc_put_vara(self._grpid, self._varid,
5319 startp, countp, vldata)
5320 else:
5321 raise IndexError('strides must all be 1 for vlen variables')
5322 #ierr = nc_put_vars(self._grpid, self._varid,
5323 # startp, countp, stridep, vldata)
5324 _ensure_nc_success(ierr)
5325 # free the pointer array.
5326 free(vldata)
5327 free(startp)
5328 free(countp)
5329 free(stridep)
5330
5331 def _get(self,start,count,stride):
5332 """Private method to retrieve data from a netCDF variable"""
5333 cdef int ierr, ndims
5334 cdef size_t *startp
5335 cdef size_t *countp
5336 cdef ptrdiff_t *stridep
5337 cdef ndarray data, dataarr
5338 cdef void *elptr
5339 cdef char **strdata
5340 cdef nc_vlen_t *vldata
5341 # if one of the counts is negative, then it is an index
5342 # and not a slice so the resulting array
5343 # should be 'squeezed' to remove the singleton dimension.
5344 shapeout = ()
5345 squeeze_out = False
5346 for lendim in count:
5347 if lendim == -1:
5348 shapeout = shapeout + (1,)
5349 squeeze_out = True
5350 else:
5351 shapeout = shapeout + (lendim,)
5352 # rank of variable.
5353 ndims = len(self.dimensions)
5354 # fill up startp,countp,stridep.
5355 negstride = 0
5356 sl = []
5357 startp = <size_t *>malloc(sizeof(size_t) * ndims)
5358 countp = <size_t *>malloc(sizeof(size_t) * ndims)
5359 stridep = <ptrdiff_t *>malloc(sizeof(ptrdiff_t) * ndims)
5360 for n from 0 <= n < ndims:
5361 count[n] = abs(count[n]) # make -1 into +1
5362 countp[n] = count[n]
5363 # for neg strides, reverse order (then flip that axis after data read in)
5364 if stride[n] < 0:
5365 negstride = 1
5366 stridep[n] = -stride[n]
5367 startp[n] = start[n]+stride[n]*(count[n]-1)
5368 stride[n] = -stride[n]
5369 sl.append(slice(None, None, -1)) # this slice will reverse the data
5370 else:
5371 startp[n] = start[n]
5372 stridep[n] = stride[n]
5373 sl.append(slice(None,None, 1))
5374 if self._isprimitive or self._iscompound or self._isenum:
5375 data = numpy.empty(shapeout, self.dtype)
5376 # strides all 1 or scalar variable, use get_vara (faster)
5377 # if count contains a zero element, no data is being read
5378 if 0 not in count:
5379 if sum(stride) == ndims or ndims == 0:
5380 with nogil:
5381 ierr = nc_get_vara(self._grpid, self._varid,
5382 startp, countp, data.data)
5383 else:
5384 with nogil:
5385 ierr = nc_get_vars(self._grpid, self._varid,
5386 startp, countp, stridep, data.data)
5387 else:
5388 ierr = 0
5389 if ierr == NC_EINVALCOORDS:
5390 raise IndexError('index exceeds dimension bounds')
5391 elif ierr != NC_NOERR:
5392 _ensure_nc_success(ierr)
5393 elif self._isvlen:
5394 # allocate array of correct primitive type.
5395 data = numpy.empty(shapeout, 'O')
5396 # flatten data array.
5397 data = data.flatten()
5398 totelem = PyArray_SIZE(data)
5399 if self.dtype == str:
5400 # vlen string (NC_STRING)
5401 # allocate pointer array to hold string data.
5402 strdata = <char **>malloc(sizeof(char *) * totelem)
5403 # strides all 1 or scalar variable, use get_vara (faster)
5404 if sum(stride) == ndims or ndims == 0:
5405 with nogil:
5406 ierr = nc_get_vara(self._grpid, self._varid,
5407 startp, countp, strdata)
5408 else:
5409 # FIXME: is this a bug in netCDF4?
5410 raise IndexError('strides must all be 1 for string variables')
5411 #ierr = nc_get_vars(self._grpid, self._varid,
5412 # startp, countp, stridep, strdata)
5413 if ierr == NC_EINVALCOORDS:
5414 raise IndexError
5415 elif ierr != NC_NOERR:
5416 _ensure_nc_success(ierr)
5417 # loop over elements of object array, fill array with
5418 # contents of strdata.
5419 # use _Encoding attribute to decode string to bytes - if
5420 # not given, use 'utf-8'.
5421 encoding = getattr(self,'_Encoding','utf-8')
5422 for i from 0<=i<totelem:
5423 if strdata[i]:
5424 data[i] = strdata[i].decode(encoding)
5425 else:
5426 data[i] = "" # issue 915
5427 # reshape the output array
5428 data = numpy.reshape(data, shapeout)
5429 # free string data internally allocated in netcdf C lib
5430 ierr = nc_free_string(totelem, strdata)
5431 # free the pointer array
5432 free(strdata)
5433 else:
5434 # regular vlen
5435 # allocate struct array to hold vlen data.
5436 vldata = <nc_vlen_t *>malloc(totelem*sizeof(nc_vlen_t))
5437 for i in range(totelem):
5438 vldata[i].len = 0
5439 vldata[i].p = <void*>0
5440 # strides all 1 or scalar variable, use get_vara (faster)
5441 if sum(stride) == ndims or ndims == 0:
5442 with nogil:
5443 ierr = nc_get_vara(self._grpid, self._varid,
5444 startp, countp, vldata)
5445 else:
5446 raise IndexError('strides must all be 1 for vlen variables')
5447 #ierr = nc_get_vars(self._grpid, self._varid,
5448 # startp, countp, stridep, vldata)
5449 if ierr == NC_EINVALCOORDS:
5450 raise IndexError
5451 elif ierr != NC_NOERR:
5452 _ensure_nc_success(ierr)
5453 # loop over elements of object array, fill array with
5454 # contents of vlarray struct, put array in object array.
5455 for i from 0<=i<totelem:
5456 arrlen = vldata[i].len
5457 dataarr = numpy.empty(arrlen, self.dtype)
5458 #dataarr.data = <char *>vldata[i].p
5459 memcpy(<void*>dataarr.data, vldata[i].p, dataarr.nbytes)
5460 data[i] = dataarr
5461 # reshape the output array
5462 data = numpy.reshape(data, shapeout)
5463 # free vlen data internally allocated in netcdf C lib
5464 ierr = nc_free_vlens(totelem, vldata)
5465 # free the pointer array
5466 free(vldata)
5467 free(startp)
5468 free(countp)
5469 free(stridep)
5470 if negstride:
5471 # reverse data along axes with negative strides.
5472 data = data[tuple(sl)].copy() # make a copy so data is contiguous.
5473 # netcdf-c always returns data in native byte order,
5474 # regardless of variable endian-ness. Here we swap the
5475 # bytes if the variable dtype is not native endian, so the
5476 # dtype of the returned numpy array matches the variable dtype.
5477 # (pull request #555, issue #554).
5478 if not data.dtype.isnative:
5479 data.byteswap(True) # in-place byteswap
5480 if not self.dimensions:
5481 return data[0] # a scalar
5482 elif squeeze_out:
5483 return numpy.squeeze(data)
5484 else:
5485 return data
5486
5487 def set_collective(self, value):
5488 """
5489 **`set_collective(self,True_or_False)`**
5490
5491 turn on or off collective parallel IO access. Ignored if file is not
5492 open for parallel access.
5493 """
5494 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
5495 # set collective MPI IO mode on or off
5496 if value:
5497 ierr = nc_var_par_access(self._grpid, self._varid,
5498 NC_COLLECTIVE)
5499 else:
5500 ierr = nc_var_par_access(self._grpid, self._varid,
5501 NC_INDEPENDENT)
5502 _ensure_nc_success(ierr)
5503 ELSE:
5504 pass # does nothing
5505
5506 def get_dims(self):
5507 """
5508 **`get_dims(self)`**
5509
5510 return a tuple of `netCDF4.Dimension` instances associated with this
5511 `netCDF4.Variable.
5512 """
5513 return tuple(_find_dim(self._grp, dim) for dim in self.dimensions)
5514
5515 def __reduce__(self):
5516 # raise error is user tries to pickle a Variable object.
5517 raise NotImplementedError('Variable is not picklable')
5518
5519 # Compound datatype support.
5520
5521 cdef class CompoundType:
5522 """
5523 A `netCDF4.CompoundType` instance is used to describe a compound data
5524 type, and can be passed to the the `netCDF4.Dataset.createVariable` method of
5525 a `netCDF4.Dataset` or `netCDF4.Group` instance.
5526 Compound data types map to numpy structured arrays.
5527 See `netCDF4.CompoundType.__init__` for more details.
5528
5529 The instance variables `dtype` and `name` should not be modified by
5530 the user.
5531 """
5532 cdef public nc_type _nc_type
5533 cdef public dtype, dtype_view, name
5534 __pdoc__['CompoundType.name'] = \
5535 """String name."""
5536 __pdoc__['CompoundType.dtype'] = \
5537 """A numpy dtype object describing the compound data type."""
5538 def __init__(self, grp, object dt, object dtype_name, **kwargs):
5539 """
5540 ***`__init__(group, datatype, datatype_name)`***
5541
5542 CompoundType constructor.
5543
5544 **`group`**: `netCDF4.Group` instance to associate with the compound datatype.
5545
5546 **`datatype`**: A numpy dtype object describing a structured (a.k.a record)
5547 array. Can be composed of homogeneous numeric or character data types, or
5548 other structured array data types.
5549
5550 **`datatype_name`**: a Python string containing a description of the
5551 compound data type.
5552
5553 ***Note 1***: When creating nested compound data types,
5554 the inner compound data types must already be associated with CompoundType
5555 instances (so create CompoundType instances for the innermost structures
5556 first).
5557
5558 ***Note 2***: `netCDF4.CompoundType` instances should be created using the
5559 `netCDF4.Dataset.createCompoundType`
5560 method of a `netCDF4.Dataset` or `netCDF4.Group` instance, not using this class directly.
5561 """
5562 cdef nc_type xtype
5563 # convert dt to a numpy datatype object
5564 # and make sure the isalignedstruct flag is set to True
5565 # (so padding is added to the fields to match what a
5566 # C compiler would output for a similar C-struct).
5567 # This is needed because nc_get_vara is
5568 # apparently expecting the data buffer to include
5569 # padding to match what a C struct would have.
5570 # (this may or may not be still true, but empirical
5571 # evidence suggests that segfaults occur if this
5572 # alignment step is skipped - see issue #705).
5573 # numpy string subdtypes (i.e. 'S80') are
5574 # automatically converted to character array
5575 # subtypes (i.e. ('S1',80)). If '_Encoding'
5576 # variable attribute is set, data will be converted
5577 # to and from the string array representation with views.
5578 dt = _set_alignment(numpy.dtype(dt))
5579 # create a view datatype for converting char arrays to/from strings
5580 dtview = _set_viewdtype(numpy.dtype(dt))
5581 if 'typeid' in kwargs:
5582 xtype = kwargs['typeid']
5583 else:
5584 xtype = _def_compound(grp, dt, dtype_name)
5585 self._nc_type = xtype
5586 self.dtype = dt
5587 self.dtype_view = dtview
5588 self.name = dtype_name
5589
5590 def __repr__(self):
5591 if python3:
5592 return self.__unicode__()
5593 else:
5594 return unicode(self).encode('utf-8')
5595
5596 def __unicode__(self):
5597 return "%r: name = '%s', numpy dtype = %s" %\
5598 (type(self), self.name, self.dtype)
5599
5600 def __reduce__(self):
5601 # raise error is user tries to pickle a CompoundType object.
5602 raise NotImplementedError('CompoundType is not picklable')
5603
5604 def _set_alignment(dt):
5605 # recursively set alignment flag in nested structured data type
5606 names = dt.names; formats = []
5607 for name in names:
5608 fmt = dt.fields[name][0]
5609 if fmt.kind == 'V':
5610 if fmt.shape == ():
5611 dtx = _set_alignment(dt.fields[name][0])
5612 else:
5613 if fmt.subdtype[0].kind == 'V': # structured dtype
5614 raise TypeError('nested structured dtype arrays not supported')
5615 else:
5616 dtx = dt.fields[name][0]
5617 else:
5618 # convert character string elements to char arrays
5619 if fmt.kind == 'S' and fmt.itemsize != 1:
5620 dtx = numpy.dtype('(%s,)S1' % fmt.itemsize)
5621 else:
5622 # primitive data type
5623 dtx = dt.fields[name][0]
5624 formats.append(dtx)
5625 # leave out offsets, they will be re-computed to preserve alignment.
5626 dtype_dict = {'names':names,'formats':formats}
5627 return numpy.dtype(dtype_dict, align=True)
5628
5629 def _set_viewdtype(dt):
5630 # recursively change character array dtypes to string dtypes
5631 names = dt.names; formats = []
5632 for name in names:
5633 fmt = dt.fields[name][0]
5634 if fmt.kind == 'V':
5635 if fmt.shape == ():
5636 dtx = _set_viewdtype(dt.fields[name][0])
5637 else:
5638 if fmt.subdtype[0].kind == 'V': # structured dtype
5639 raise TypeError('nested structured dtype arrays not supported')
5640 elif fmt.subdtype[0].kind == 'S' and len(dt.fields[name][0].shape) == 1:
5641 lenchar = dt.fields[name][0].shape[0]
5642 dtx = numpy.dtype('S%s' % lenchar)
5643 else:
5644 dtx = dt.fields[name][0]
5645 else:
5646 # primitive data type
5647 dtx = dt.fields[name][0]
5648 formats.append(dtx)
5649 dtype_dict = {'names':names,'formats':formats}
5650 return numpy.dtype(dtype_dict, align=True)
5651
5652 cdef _def_compound(grp, object dt, object dtype_name):
5653 # private function used to construct a netcdf compound data type
5654 # from a numpy dtype object by CompoundType.__init__.
5655 cdef nc_type xtype, xtype_tmp
5656 cdef int ierr, ndims
5657 cdef size_t offset, size
5658 cdef char *namstring
5659 cdef char *nested_namstring
5660 cdef int *dim_sizes
5661 bytestr = _strencode(dtype_name)
5662 namstring = bytestr
5663 size = dt.itemsize
5664 ierr = nc_def_compound(grp._grpid, size, namstring, &xtype)
5665 _ensure_nc_success(ierr)
5666 names = list(dt.fields.keys())
5667 formats = [v[0] for v in dt.fields.values()]
5668 offsets = [v[1] for v in dt.fields.values()]
5669 # make sure entries in lists sorted by offset.
5670 # (don't know why this is necessary, but it is for version 4.0.1)
5671 names = _sortbylist(names, offsets)
5672 formats = _sortbylist(formats, offsets)
5673 offsets.sort()
5674 for name, format, offset in zip(names, formats, offsets):
5675 bytestr = _strencode(name)
5676 namstring = bytestr
5677 if format.kind != 'V': # scalar primitive type
5678 try:
5679 xtype_tmp = _nptonctype[format.str[1:]]
5680 except KeyError:
5681 raise ValueError('Unsupported compound type element')
5682 ierr = nc_insert_compound(grp._grpid, xtype, namstring,
5683 offset, xtype_tmp)
5684 _ensure_nc_success(ierr)
5685 else:
5686 if format.shape == (): # nested scalar compound type
5687 # find this compound type in this group or it's parents.
5688 xtype_tmp = _find_cmptype(grp, format)
5689 bytestr = _strencode(name)
5690 nested_namstring = bytestr
5691 ierr = nc_insert_compound(grp._grpid, xtype,\
5692 nested_namstring,\
5693 offset, xtype_tmp)
5694 _ensure_nc_success(ierr)
5695 else: # nested array compound element
5696 ndims = len(format.shape)
5697 dim_sizes = <int *>malloc(sizeof(int) * ndims)
5698 for n from 0 <= n < ndims:
5699 dim_sizes[n] = format.shape[n]
5700 if format.subdtype[0].kind != 'V': # primitive type.
5701 try:
5702 xtype_tmp = _nptonctype[format.subdtype[0].str[1:]]
5703 except KeyError:
5704 raise ValueError('Unsupported compound type element')
5705 ierr = nc_insert_array_compound(grp._grpid,xtype,namstring,
5706 offset,xtype_tmp,ndims,dim_sizes)
5707 _ensure_nc_success(ierr)
5708 else: # nested array compound type.
5709 raise TypeError('nested structured dtype arrays not supported')
5710 # this code is untested and probably does not work, disable
5711 # for now...
5712 # # find this compound type in this group or it's parents.
5713 # xtype_tmp = _find_cmptype(grp, format.subdtype[0])
5714 # bytestr = _strencode(name)
5715 # nested_namstring = bytestr
5716 # ierr = nc_insert_array_compound(grp._grpid,xtype,\
5717 # nested_namstring,\
5718 # offset,xtype_tmp,\
5719 # ndims,dim_sizes)
5720 # _ensure_nc_success(ierr)
5721 free(dim_sizes)
5722 return xtype
5723
5724 cdef _find_cmptype(grp, dtype):
5725 # look for data type in this group and it's parents.
5726 # return datatype id when found, if not found, raise exception.
5727 cdef nc_type xtype
5728 match = False
5729 for cmpname, cmpdt in grp.cmptypes.items():
5730 xtype = cmpdt._nc_type
5731 names1 = dtype.fields.keys()
5732 names2 = cmpdt.dtype.fields.keys()
5733 formats1 = [v[0] for v in dtype.fields.values()]
5734 formats2 = [v[0] for v in cmpdt.dtype.fields.values()]
5735 formats2v = [v[0] for v in cmpdt.dtype_view.fields.values()]
5736 # match names, formats, but not offsets (they may be changed
5737 # by netcdf lib).
5738 if names1==names2 and formats1==formats2 or (formats1 == formats2v):
5739 match = True
5740 break
5741 if not match:
5742 try:
5743 parent_grp = grp.parent
5744 except AttributeError:
5745 raise ValueError("cannot find compound type in this group or parent groups")
5746 if parent_grp is None:
5747 raise ValueError("cannot find compound type in this group or parent groups")
5748 else:
5749 xtype = _find_cmptype(parent_grp,dtype)
5750 return xtype
5751
5752 cdef _read_compound(group, nc_type xtype, endian=None):
5753 # read a compound data type id from an existing file,
5754 # construct a corresponding numpy dtype instance,
5755 # then use that to create a CompoundType instance.
5756 # called by _get_vars, _get_types and _get_att.
5757 # Calls itself recursively for nested compound types.
5758 cdef int ierr, nf, numdims, ndim, classp, _grpid
5759 cdef size_t nfields, offset
5760 cdef nc_type field_typeid
5761 cdef int *dim_sizes
5762 cdef char field_namstring[NC_MAX_NAME+1]
5763 cdef char cmp_namstring[NC_MAX_NAME+1]
5764 # get name and number of fields.
5765 _grpid = group._grpid
5766 with nogil:
5767 ierr = nc_inq_compound(_grpid, xtype, cmp_namstring, NULL, &nfields)
5768 _ensure_nc_success(ierr)
5769 name = cmp_namstring.decode('utf-8')
5770 # loop over fields.
5771 names = []
5772 formats = []
5773 offsets = []
5774 for nf from 0 <= nf < nfields:
5775 with nogil:
5776 ierr = nc_inq_compound_field(_grpid,
5777 xtype,
5778 nf,
5779 field_namstring,
5780 &offset,
5781 &field_typeid,
5782 &numdims,
5783 NULL)
5784 _ensure_nc_success(ierr)
5785 dim_sizes = <int *>malloc(sizeof(int) * numdims)
5786 with nogil:
5787 ierr = nc_inq_compound_field(_grpid,
5788 xtype,
5789 nf,
5790 field_namstring,
5791 &offset,
5792 &field_typeid,
5793 &numdims,
5794 dim_sizes)
5795 _ensure_nc_success(ierr)
5796 field_name = field_namstring.decode('utf-8')
5797 names.append(field_name)
5798 offsets.append(offset)
5799 # if numdims=0, not an array.
5800 field_shape = ()
5801 if numdims != 0:
5802 for ndim from 0 <= ndim < numdims:
5803 field_shape = field_shape + (dim_sizes[ndim],)
5804 free(dim_sizes)
5805 # check to see if this field is a nested compound type.
5806 try:
5807 field_type = _nctonptype[field_typeid]
5808 if endian is not None:
5809 format = endian + format
5810 except KeyError:
5811 with nogil:
5812 ierr = nc_inq_user_type(_grpid,
5813 field_typeid,NULL,NULL,NULL,NULL,&classp)
5814 if classp == NC_COMPOUND: # a compound type
5815 # recursively call this function?
5816 field_type = _read_compound(group, field_typeid, endian=endian)
5817 else:
5818 raise KeyError('compound field of an unsupported data type')
5819 if field_shape != ():
5820 formats.append((field_type,field_shape))
5821 else:
5822 formats.append(field_type)
5823 # make sure entries in lists sorted by offset.
5824 names = _sortbylist(names, offsets)
5825 formats = _sortbylist(formats, offsets)
5826 offsets.sort()
5827 # create a dict that can be converted into a numpy dtype.
5828 dtype_dict = {'names':names,'formats':formats,'offsets':offsets}
5829 return CompoundType(group, dtype_dict, name, typeid=xtype)
5830
5831 # VLEN datatype support.
5832
5833 cdef class VLType:
5834 """
5835 A `netCDF4.VLType` instance is used to describe a variable length (VLEN) data
5836 type, and can be passed to the the `netCDF4.Dataset.createVariable` method of
5837 a `netCDF4.Dataset` or `netCDF4.Group` instance. See
5838 `netCDF4.VLType.__init__` for more details.
5839
5840 The instance variables `dtype` and `name` should not be modified by
5841 the user.
5842 """
5843 cdef public nc_type _nc_type
5844 cdef public dtype, name
5845 __pdoc__['VLType.name'] = \
5846 """String name."""
5847 __pdoc__['VLType.dtype'] = \
5848 """A numpy dtype object describing the component type for the VLEN."""
5849 def __init__(self, grp, object dt, object dtype_name, **kwargs):
5850 """
5851 **`__init__(group, datatype, datatype_name)`**
5852
5853 VLType constructor.
5854
5855 **`group`**: `netCDF4.Group` instance to associate with the VLEN datatype.
5856
5857 **`datatype`**: An numpy dtype object describing the component type for the
5858 variable length array.
5859
5860 **`datatype_name`**: a Python string containing a description of the
5861 VLEN data type.
5862
5863 ***`Note`***: `netCDF4.VLType` instances should be created using the
5864 `netCDF4.Dataset.createVLType`
5865 method of a `netCDF4.Dataset` or `netCDF4.Group` instance, not using this class directly.
5866 """
5867 cdef nc_type xtype
5868 if 'typeid' in kwargs:
5869 xtype = kwargs['typeid']
5870 else:
5871 xtype, dt = _def_vlen(grp, dt, dtype_name)
5872 self._nc_type = xtype
5873 self.dtype = dt
5874 if dt == str:
5875 self.name = None
5876 else:
5877 self.name = dtype_name
5878
5879 def __repr__(self):
5880 if python3:
5881 return self.__unicode__()
5882 else:
5883 return unicode(self).encode('utf-8')
5884
5885 def __unicode__(self):
5886 if self.dtype == str:
5887 return '%r: string type' % (type(self),)
5888 else:
5889 return "%r: name = '%s', numpy dtype = %s" %\
5890 (type(self), self.name, self.dtype)
5891
5892 def __reduce__(self):
5893 # raise error is user tries to pickle a VLType object.
5894 raise NotImplementedError('VLType is not picklable')
5895
5896 cdef _def_vlen(grp, object dt, object dtype_name):
5897 # private function used to construct a netcdf VLEN data type
5898 # from a numpy dtype object or python str object by VLType.__init__.
5899 cdef nc_type xtype, xtype_tmp
5900 cdef int ierr, ndims
5901 cdef size_t offset, size
5902 cdef char *namstring
5903 cdef char *nested_namstring
5904 if dt == str: # python string, use NC_STRING
5905 xtype = NC_STRING
5906 # dtype_name ignored
5907 else: # numpy datatype
5908 bytestr = _strencode(dtype_name)
5909 namstring = bytestr
5910 dt = numpy.dtype(dt) # convert to numpy datatype.
5911 if dt.str[1:] in _supportedtypes:
5912 # find netCDF primitive data type corresponding to
5913 # specified numpy data type.
5914 xtype_tmp = _nptonctype[dt.str[1:]]
5915 ierr = nc_def_vlen(grp._grpid, namstring, xtype_tmp, &xtype);
5916 _ensure_nc_success(ierr)
5917 else:
5918 raise KeyError("unsupported datatype specified for VLEN")
5919 return xtype, dt
5920
5921 cdef _read_vlen(group, nc_type xtype, endian=None):
5922 # read a VLEN data type id from an existing file,
5923 # construct a corresponding numpy dtype instance,
5924 # then use that to create a VLType instance.
5925 # called by _get_types, _get_vars.
5926 cdef int ierr, _grpid
5927 cdef size_t vlsize
5928 cdef nc_type base_xtype
5929 cdef char vl_namstring[NC_MAX_NAME+1]
5930 _grpid = group._grpid
5931 if xtype == NC_STRING:
5932 dt = str
5933 name = None
5934 else:
5935 with nogil:
5936 ierr = nc_inq_vlen(_grpid, xtype, vl_namstring, &vlsize, &base_xtype)
5937 _ensure_nc_success(ierr)
5938 name = vl_namstring.decode('utf-8')
5939 try:
5940 datatype = _nctonptype[base_xtype]
5941 if endian is not None: datatype = endian + datatype
5942 dt = numpy.dtype(datatype) # see if it is a primitive type
5943 except KeyError:
5944 raise KeyError("unsupported component type for VLEN")
5945 return VLType(group, dt, name, typeid=xtype)
5946
5947 # Enum datatype support.
5948
5949 cdef class EnumType:
5950 """
5951 A `netCDF4.EnumType` instance is used to describe an Enum data
5952 type, and can be passed to the the `netCDF4.Dataset.createVariable` method of
5953 a `netCDF4.Dataset` or `netCDF4.Group` instance. See
5954 `netCDF4.EnumType.__init__` for more details.
5955
5956 The instance variables `dtype`, `name` and `enum_dict` should not be modified by
5957 the user.
5958 """
5959 cdef public nc_type _nc_type
5960 cdef public dtype, name, enum_dict
5961 __pdoc__['EnumType.name'] = \
5962 """String name."""
5963 __pdoc__['EnumType.dtype'] = \
5964 """A numpy integer dtype object describing the base type for the Enum."""
5965 __pdoc__['EnumType.enum_dict'] = \
5966 """A python dictionary describing the enum fields and values."""
5967 def __init__(self, grp, object dt, object dtype_name, object enum_dict, **kwargs):
5968 """
5969 **`__init__(group, datatype, datatype_name, enum_dict)`**
5970
5971 EnumType constructor.
5972
5973 **`group`**: `netCDF4.Group` instance to associate with the VLEN datatype.
5974
5975 **`datatype`**: An numpy integer dtype object describing the base type
5976 for the Enum.
5977
5978 **`datatype_name`**: a Python string containing a description of the
5979 Enum data type.
5980
5981 **`enum_dict`**: a Python dictionary containing the Enum field/value
5982 pairs.
5983
5984 ***`Note`***: `netCDF4.EnumType` instances should be created using the
5985 `netCDF4.Dataset.createEnumType`
5986 method of a `netCDF4.Dataset` or `netCDF4.Group` instance, not using this class directly.
5987 """
5988 cdef nc_type xtype
5989 if 'typeid' in kwargs:
5990 xtype = kwargs['typeid']
5991 else:
5992 xtype, dt = _def_enum(grp, dt, dtype_name, enum_dict)
5993 self._nc_type = xtype
5994 self.dtype = dt
5995 self.name = dtype_name
5996 self.enum_dict = enum_dict
5997
5998 def __repr__(self):
5999 if python3:
6000 return self.__unicode__()
6001 else:
6002 return unicode(self).encode('utf-8')
6003
6004 def __unicode__(self):
6005 return "%r: name = '%s', numpy dtype = %s, fields/values =%s" %\
6006 (type(self), self.name, self.dtype, self.enum_dict)
6007
6008 def __reduce__(self):
6009 # raise error is user tries to pickle a EnumType object.
6010 raise NotImplementedError('EnumType is not picklable')
6011
6012 cdef _def_enum(grp, object dt, object dtype_name, object enum_dict):
6013 # private function used to construct a netCDF Enum data type
6014 # from a numpy dtype object or python str object by EnumType.__init__.
6015 cdef nc_type xtype, xtype_tmp
6016 cdef int ierr
6017 cdef char *namstring
6018 cdef ndarray value_arr
6019 bytestr = _strencode(dtype_name)
6020 namstring = bytestr
6021 dt = numpy.dtype(dt) # convert to numpy datatype.
6022 if dt.str[1:] in _intnptonctype.keys():
6023 # find netCDF primitive data type corresponding to
6024 # specified numpy data type.
6025 xtype_tmp = _intnptonctype[dt.str[1:]]
6026 ierr = nc_def_enum(grp._grpid, xtype_tmp, namstring, &xtype);
6027 _ensure_nc_success(ierr)
6028 else:
6029 msg="unsupported datatype specified for ENUM (must be integer)"
6030 raise KeyError(msg)
6031 # insert named members into enum type.
6032 for field in enum_dict:
6033 value_arr = numpy.array(enum_dict[field],dt)
6034 bytestr = _strencode(field)
6035 namstring = bytestr
6036 ierr = nc_insert_enum(grp._grpid, xtype, namstring, value_arr.data)
6037 _ensure_nc_success(ierr)
6038 return xtype, dt
6039
6040 cdef _read_enum(group, nc_type xtype, endian=None):
6041 # read a Enum data type id from an existing file,
6042 # construct a corresponding numpy dtype instance,
6043 # then use that to create a EnumType instance.
6044 # called by _get_types, _get_vars.
6045 cdef int ierr, _grpid, nmem
6046 cdef char enum_val
6047 cdef nc_type base_xtype
6048 cdef char enum_namstring[NC_MAX_NAME+1]
6049 cdef size_t nmembers
6050 _grpid = group._grpid
6051 # get name, datatype, and number of members.
6052 with nogil:
6053 ierr = nc_inq_enum(_grpid, xtype, enum_namstring, &base_xtype, NULL,\
6054 &nmembers)
6055 _ensure_nc_success(ierr)
6056 enum_name = enum_namstring.decode('utf-8')
6057 try:
6058 datatype = _nctonptype[base_xtype]
6059 if endian is not None: datatype = endian + datatype
6060 dt = numpy.dtype(datatype) # see if it is a primitive type
6061 except KeyError:
6062 raise KeyError("unsupported component type for ENUM")
6063 # loop over members, build dict.
6064 enum_dict = {}
6065 for nmem from 0 <= nmem < nmembers:
6066 with nogil:
6067 ierr = nc_inq_enum_member(_grpid, xtype, nmem, \
6068 enum_namstring, &enum_val)
6069 _ensure_nc_success(ierr)
6070 name = enum_namstring.decode('utf-8')
6071 enum_dict[name] = int(enum_val)
6072 return EnumType(group, dt, enum_name, enum_dict, typeid=xtype)
6073
6074 cdef _strencode(pystr,encoding=None):
6075 # encode a string into bytes. If already bytes, do nothing.
6076 # uses 'utf-8' for default encoding.
6077 if encoding is None:
6078 encoding = 'utf-8'
6079 try:
6080 return pystr.encode(encoding)
6081 except (AttributeError, UnicodeDecodeError):
6082 return pystr # already bytes or unicode?
6083
6084 def _to_ascii(bytestr):
6085 # encode a byte string to an ascii encoded string.
6086 if python3:
6087 return str(bytestr,encoding='ascii')
6088 else:
6089 return bytestr.encode('ascii')
6090
6091 def stringtoarr(string,NUMCHARS,dtype='S'):
6092 """
6093 **`stringtoarr(a, NUMCHARS,dtype='S')`**
6094
6095 convert a string to a character array of length `NUMCHARS`
6096
6097 **`a`**: Input python string.
6098
6099 **`NUMCHARS`**: number of characters used to represent string
6100 (if len(a) < `NUMCHARS`, it will be padded on the right with blanks).
6101
6102 **`dtype`**: type of numpy array to return. Default is `'S'`, which
6103 means an array of dtype `'S1'` will be returned. If dtype=`'U'`, a
6104 unicode array (dtype = `'U1'`) will be returned.
6105
6106 returns a rank 1 numpy character array of length NUMCHARS with datatype `'S1'`
6107 (default) or `'U1'` (if dtype=`'U'`)"""
6108 if dtype not in ["S","U"]:
6109 raise ValueError("dtype must string or unicode ('S' or 'U')")
6110 arr = numpy.zeros(NUMCHARS,dtype+'1')
6111 arr[0:len(string)] = tuple(string)
6112 return arr
6113
6114 def stringtochar(a,encoding='utf-8'):
6115 """
6116 **`stringtochar(a,encoding='utf-8')`**
6117
6118 convert a string array to a character array with one extra dimension
6119
6120 **`a`**: Input numpy string array with numpy datatype `'SN'` or `'UN'`, where N
6121 is the number of characters in each string. Will be converted to
6122 an array of characters (datatype `'S1'` or `'U1'`) of shape `a.shape + (N,)`.
6123
6124 optional kwarg `encoding` can be used to specify character encoding (default
6125 `utf-8`). If `encoding` is 'none' or 'bytes', a `numpy.string_` the input array
6126 is treated a raw byte strings (`numpy.string_`).
6127
6128 returns a numpy character array with datatype `'S1'` or `'U1'`
6129 and shape `a.shape + (N,)`, where N is the length of each string in a."""
6130 dtype = a.dtype.kind
6131 if dtype not in ["S","U"]:
6132 raise ValueError("type must string or unicode ('S' or 'U')")
6133 if encoding in ['none','None','bytes']:
6134 b = numpy.array(tuple(a.tobytes()),'S1')
6135 else:
6136 b = numpy.array(tuple(a.tobytes().decode(encoding)),dtype+'1')
6137 b.shape = a.shape + (a.itemsize,)
6138 return b
6139
6140 def chartostring(b,encoding='utf-8'):
6141 """
6142 **`chartostring(b,encoding='utf-8')`**
6143
6144 convert a character array to a string array with one less dimension.
6145
6146 **`b`**: Input character array (numpy datatype `'S1'` or `'U1'`).
6147 Will be converted to a array of strings, where each string has a fixed
6148 length of `b.shape[-1]` characters.
6149
6150 optional kwarg `encoding` can be used to specify character encoding (default
6151 `utf-8`). If `encoding` is 'none' or 'bytes', a `numpy.string_` btye array is
6152 returned.
6153
6154 returns a numpy string array with datatype `'UN'` (or `'SN'`) and shape
6155 `b.shape[:-1]` where where `N=b.shape[-1]`."""
6156 dtype = b.dtype.kind
6157 if dtype not in ["S","U"]:
6158 raise ValueError("type must be string or unicode ('S' or 'U')")
6159 if encoding in ['none','None','bytes']:
6160 bs = b.tobytes()
6161 else:
6162 bs = b.tobytes().decode(encoding)
6163 slen = int(b.shape[-1])
6164 if encoding in ['none','None','bytes']:
6165 a = numpy.array([bs[n1:n1+slen] for n1 in range(0,len(bs),slen)],'S'+repr(slen))
6166 else:
6167 a = numpy.array([bs[n1:n1+slen] for n1 in range(0,len(bs),slen)],'U'+repr(slen))
6168 a.shape = b.shape[:-1]
6169 return a
6170
6171 class MFDataset(Dataset):
6172 """
6173 Class for reading multi-file netCDF Datasets, making variables
6174 spanning multiple files appear as if they were in one file.
6175 Datasets must be in `NETCDF4_CLASSIC, NETCDF3_CLASSIC, NETCDF3_64BIT_OFFSET
6176 or NETCDF3_64BIT_DATA` format (`NETCDF4` Datasets won't work).
6177
6178 Adapted from [pycdf](http://pysclint.sourceforge.net/pycdf) by Andre Gosselin.
6179
6180 Example usage (See `netCDF4.MFDataset.__init__` for more details):
6181
6182 :::python
6183 >>> import numpy as np
6184 >>> # create a series of netCDF files with a variable sharing
6185 >>> # the same unlimited dimension.
6186 >>> for nf in range(10):
6187 ... with Dataset("mftest%s.nc" % nf, "w", format='NETCDF4_CLASSIC') as f:
6188 ... f.createDimension("x",None)
6189 ... x = f.createVariable("x","i",("x",))
6190 ... x[0:10] = np.arange(nf*10,10*(nf+1))
6191 >>> # now read all those files in at once, in one Dataset.
6192 >>> f = MFDataset("mftest*nc")
6193 >>> print(f.variables["x"][:])
6194 [ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
6195 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
6196 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
6197 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
6198 96 97 98 99]
6199 """
6200
6201 def __init__(self, files, check=False, aggdim=None, exclude=[],
6202 master_file=None):
6203 """
6204 **`__init__(self, files, check=False, aggdim=None, exclude=[],
6205 master_file=None)`**
6206
6207 Open a Dataset spanning multiple files, making it look as if it was a
6208 single file. Variables in the list of files that share the same
6209 dimension (specified with the keyword `aggdim`) are aggregated. If
6210 `aggdim` is not specified, the unlimited is aggregated. Currently,
6211 `aggdim` must be the leftmost (slowest varying) dimension of each
6212 of the variables to be aggregated.
6213
6214 **`files`**: either a sequence of netCDF files or a string with a
6215 wildcard (converted to a sorted list of files using glob) If
6216 the `master_file` kwarg is not specified, the first file
6217 in the list will become the "master" file, defining all the
6218 variables with an aggregation dimension which may span
6219 subsequent files. Attribute access returns attributes only from "master"
6220 file. The files are always opened in read-only mode.
6221
6222 **`check`**: True if you want to do consistency checking to ensure the
6223 correct variables structure for all of the netcdf files. Checking makes
6224 the initialization of the MFDataset instance much slower. Default is
6225 False.
6226
6227 **`aggdim`**: The name of the dimension to aggregate over (must
6228 be the leftmost dimension of each of the variables to be aggregated).
6229 If None (default), aggregate over the unlimited dimension.
6230
6231 **`exclude`**: A list of variable names to exclude from aggregation.
6232 Default is an empty list.
6233
6234 **`master_file`**: file to use as "master file", defining all the
6235 variables with an aggregation dimension and all global attributes.
6236 """
6237
6238 # Open the master file in the base class, so that the CDFMF instance
6239 # can be used like a CDF instance.
6240 if isinstance(files, str):
6241 if files.startswith('http'):
6242 msg='cannot using file globbing for remote (OPeNDAP) datasets'
6243 raise ValueError(msg)
6244 else:
6245 files = sorted(glob(files))
6246
6247 if not files:
6248 msg='no files specified (file list is empty)'
6249 raise IOError(msg)
6250
6251 if master_file is not None:
6252 if master_file not in files:
6253 raise ValueError('master_file not in files list')
6254 else:
6255 master = master_file
6256 else:
6257 master = files[0]
6258
6259 # Open the master again, this time as a classic CDF instance. This will avoid
6260 # calling methods of the CDFMF subclass when querying the master file.
6261 cdfm = Dataset(master)
6262 # copy attributes from master.
6263 for name, value in cdfm.__dict__.items():
6264 self.__dict__[name] = value
6265
6266 # Make sure the master defines a dim with name aggdim,
6267 # or an unlimited dimension.
6268 aggDimId = None
6269 for dimname,dim in cdfm.dimensions.items():
6270 if aggdim is None:
6271 if dim.isunlimited():
6272 aggDimId = dim
6273 aggDimName = dimname
6274 else:
6275 if dimname == aggdim:
6276 aggDimId = dim
6277 aggDimName = dimname
6278 if aggDimId is None:
6279 raise IOError("master dataset %s does not have a aggregation dimension" % master)
6280
6281 # Get info on all aggregation variables defined in the master.
6282 # Make sure the master defines at least one aggregation variable.
6283 masterRecVar = {}
6284 for vName,v in cdfm.variables.items():
6285 # skip variables specified in exclude list.
6286 if vName in exclude: continue
6287 dims = v.dimensions
6288 shape = v.shape
6289 dtype = v.dtype
6290 # Be careful: we may deal with a scalar (dimensionless) variable.
6291 # Unlimited dimension always occupies index 0.
6292 if (len(dims) > 0 and aggDimName == dims[0]):
6293 masterRecVar[vName] = (dims, shape, dtype)
6294 if len(masterRecVar) == 0:
6295 raise IOError("master dataset %s does not have any variables to aggregate" % master)
6296
6297 # Create the following:
6298 # cdf list of Dataset instances
6299 # cdfVLen list unlimited dimension lengths in each CDF instance
6300 # cdfRecVar dictionary indexed by the aggregation var names; each key holds
6301 # a list of the corresponding Variable instance, one for each
6302 # cdf file of the file set
6303 cdf = []
6304 self._cdf = cdf # Store this now, because dim() method needs it
6305 cdfVLen = []
6306 cdfRecVar = {}
6307
6308 # Open each remaining file in read-only mode.
6309 # Make sure each file defines the same aggregation variables as the master
6310 # and that the variables are defined in the same way (name, shape and type)
6311 for f in files:
6312 if f == master:
6313 part = cdfm
6314 else:
6315 part = Dataset(f)
6316 if cdfRecVar == {}:
6317 empty_cdfRecVar = True
6318 else:
6319 empty_cdfRecVar = False
6320 varInfo = part.variables
6321 for v in masterRecVar.keys():
6322 if check:
6323 # Make sure master rec var is also defined here.
6324 if v not in varInfo.keys():
6325 raise IOError("aggregation variable %s not defined in %s" % (v, f))
6326
6327 #if not vInst.dimensions[0] != aggDimName:
6328
6329 masterDims, masterShape, masterType = masterRecVar[v][:3]
6330 extDims = varInfo[v].dimensions
6331 extShape = varInfo[v].shape
6332 extType = varInfo[v].dtype
6333 # Check that dimension names are identical.
6334 if masterDims != extDims:
6335 raise IOError("variable %s : dimensions mismatch between "
6336 "master %s (%s) and extension %s (%s)" %
6337 (v, master, masterDims, f, extDims))
6338
6339 # Check that the ranks are identical, and the dimension lengths are
6340 # identical (except for that of the unlimited dimension, which of
6341 # course may vary.
6342 if len(masterShape) != len(extShape):
6343 raise IOError("variable %s : rank mismatch between "
6344 "master %s (%s) and extension %s (%s)" %
6345 (v, master, len(masterShape), f, len(extShape)))
6346 if masterShape[1:] != extShape[1:]:
6347 raise IOError("variable %s : shape mismatch between "
6348 "master %s (%s) and extension %s (%s)" %
6349 (v, master, masterShape, f, extShape))
6350
6351 # Check that the data types are identical.
6352 if masterType != extType:
6353 raise IOError("variable %s : data type mismatch between "
6354 "master %s (%s) and extension %s (%s)" %
6355 (v, master, masterType, f, extType))
6356
6357 # Everything ok.
6358 if empty_cdfRecVar:
6359 cdfRecVar[v] = [part.variables[v]]
6360 else:
6361 cdfRecVar[v].append(part.variables[v])
6362 else:
6363 # No making sure of anything -- assume this is ok..
6364 if empty_cdfRecVar:
6365 cdfRecVar[v] = [part.variables[v]]
6366 else:
6367 cdfRecVar[v].append(part.variables[v])
6368
6369 cdf.append(part)
6370 cdfVLen.append(len(part.dimensions[aggDimName]))
6371
6372 # Attach attributes to the MFDataset instance.
6373 # A local __setattr__() method is required for them.
6374 self._files = files # list of cdf file names in the set
6375 self._cdfVLen = cdfVLen # list of unlimited lengths
6376 self._cdfTLen = sum(cdfVLen) # total length
6377 self._cdfRecVar = cdfRecVar # dictionary of Variable instances for all
6378 # the aggregation variables
6379 self._dims = cdfm.dimensions
6380 self._grps = cdfm.groups
6381 for dimname, dim in self._dims.items():
6382 if dimname == aggDimName:
6383 self._dims[dimname] = _Dimension(dimname, dim, self._cdfVLen, self._cdfTLen)
6384 self._vars = cdfm.variables
6385 for varname,var in self._vars.items():
6386 if varname in self._cdfRecVar.keys():
6387 self._vars[varname] = _Variable(self, varname, var, aggDimName)
6388 self._file_format = []
6389 self._data_model = []
6390 self._disk_format = []
6391 for dset in self._cdf:
6392 if dset.file_format == 'NETCDF4' or dset.data_model == 'NETCDF4':
6393 raise ValueError('MFNetCDF4 only works with NETCDF3_* and NETCDF4_CLASSIC formatted files, not NETCDF4')
6394 self._file_format.append(dset.file_format)
6395 self._data_model.append(dset.data_model)
6396 self._disk_format.append(dset.disk_format)
6397 self._path = '/'
6398
6399 def __setattr__(self, name, value):
6400 """override base class attribute creation"""
6401 self.__dict__[name] = value
6402
6403 def __getattribute__(self, name):
6404 if name in ['variables','dimensions','file_format','groups',\
6405 'data_model','disk_format','path']:
6406 if name == 'dimensions': return self._dims
6407 if name == 'variables': return self._vars
6408 if name == 'file_format': return self._file_format
6409 if name == 'data_model': return self._data_model
6410 if name == 'disk_format': return self._disk_format
6411 if name == 'path': return self._path
6412 if name == 'groups': return self._grps
6413 else:
6414 return Dataset.__getattribute__(self, name)
6415
6416 def ncattrs(self):
6417 """
6418 **`ncattrs(self)`**
6419
6420 return the netcdf attribute names from the master file.
6421 """
6422 return self._cdf[0].__dict__.keys()
6423
6424 def close(self):
6425 """
6426 **`close(self)`**
6427
6428 close all the open files.
6429 """
6430 for dset in self._cdf:
6431 dset.close()
6432
6433 def __repr__(self):
6434 ncdump = [repr(type(self))]
6435 dimnames = tuple(str(dimname) for dimname in self.dimensions.keys())
6436 varnames = tuple(str(varname) for varname in self.variables.keys())
6437 grpnames = ()
6438 if self.path == '/':
6439 ncdump.append('root group (%s data model, file format %s):' %
6440 (self.data_model[0], self.disk_format[0]))
6441 else:
6442 ncdump.append('group %s:' % self.path)
6443 for name in self.ncattrs():
6444 ncdump.append(' %s: %s' % (name, self.__dict__[name]))
6445 ncdump.append(' dimensions = %s' % str(dimnames))
6446 ncdump.append(' variables = %s' % str(varnames))
6447 ncdump.append(' groups = %s' % str(grpnames))
6448 return '\n'.join(ncdump)
6449
6450 def __reduce__(self):
6451 # raise error is user tries to pickle a MFDataset object.
6452 raise NotImplementedError('MFDataset is not picklable')
6453
6454 class _Dimension(object):
6455 def __init__(self, dimname, dim, dimlens, dimtotlen):
6456 self.dimlens = dimlens
6457 self.dimtotlen = dimtotlen
6458 self._name = dimname
6459 def __len__(self):
6460 return self.dimtotlen
6461 def isunlimited(self):
6462 return True
6463 def __repr__(self):
6464 if self.isunlimited():
6465 return "%r (unlimited): name = '%s', size = %s" %\
6466 (type(self), self._name, len(self))
6467 else:
6468 return "%r: name = '%s', size = %s" %\
6469 (type(self), self._name, len(self))
6470
6471 class _Variable(object):
6472 def __init__(self, dset, varname, var, recdimname):
6473 self.dimensions = var.dimensions
6474 self._dset = dset
6475 self._grp = dset
6476 self._mastervar = var
6477 self._recVar = dset._cdfRecVar[varname]
6478 self._recdimname = recdimname
6479 self._recLen = dset._cdfVLen
6480 self.dtype = var.dtype
6481 self._name = var._name
6482 # copy attributes from master.
6483 for name, value in var.__dict__.items():
6484 self.__dict__[name] = value
6485 def typecode(self):
6486 return self.dtype
6487 def ncattrs(self):
6488 return self._mastervar.__dict__.keys()
6489 def __getattr__(self,name):
6490 if name == 'shape': return self._shape()
6491 if name == 'ndim': return len(self._shape())
6492 try:
6493 return self.__dict__[name]
6494 except:
6495 raise AttributeError(name)
6496 def __repr__(self):
6497 ncdump = [repr(type(self))]
6498 dimnames = tuple(str(dimname) for dimname in self.dimensions)
6499 ncdump.append('%s %s%s' % (self.dtype, self._name, dimnames))
6500 for name in self.ncattrs():
6501 ncdump.append(' %s: %s' % (name, self.__dict__[name]))
6502 unlimdims = []
6503 for dimname in self.dimensions:
6504 dim = _find_dim(self._grp, dimname)
6505 if dim.isunlimited():
6506 unlimdims.append(str(dimname))
6507 ncdump.append('unlimited dimensions = %r' % (tuple(unlimdims),))
6508 ncdump.append('current size = %r' % (self.shape,))
6509 return '\n'.join(ncdump)
6510 def __len__(self):
6511 if not self._shape:
6512 raise TypeError('len() of unsized object')
6513 else:
6514 return self._shape()[0]
6515 def _shape(self):
6516 recdimlen = len(self._dset.dimensions[self._recdimname])
6517 return (recdimlen,) + self._mastervar.shape[1:]
6518 def set_auto_chartostring(self,val):
6519 for v in self._recVar:
6520 v.set_auto_chartostring(val)
6521 def set_auto_maskandscale(self,val):
6522 for v in self._recVar:
6523 v.set_auto_maskandscale(val)
6524 def set_auto_mask(self,val):
6525 for v in self._recVar:
6526 v.set_auto_mask(val)
6527 def set_auto_scale(self,val):
6528 for v in self._recVar:
6529 v.set_auto_scale(val)
6530 def set_always_mask(self,val):
6531 for v in self._recVar:
6532 v.set_always_mask(val)
6533 def __getitem__(self, elem):
6534 """Get records from a concatenated set of variables."""
6535
6536 # This special method is used to index the netCDF variable
6537 # using the "extended slice syntax". The extended slice syntax
6538 # is a perfect match for the "start", "count" and "stride"
6539 # arguments to the nc_get_var() function, and is much more easy
6540 # to use.
6541 start, count, stride, put_ind =\
6542 _StartCountStride(elem, self.shape)
6543 datashape = _out_array_shape(count)
6544 data = ma.empty(datashape, dtype=self.dtype)
6545
6546 # Determine which dimensions need to be squeezed
6547 # (those for which elem is an integer scalar).
6548 # The convention used is that for those cases,
6549 # put_ind for this dimension is set to -1 by _StartCountStride.
6550 squeeze = data.ndim * [slice(None),]
6551 for i,n in enumerate(put_ind.shape[:-1]):
6552 if n == 1 and put_ind[...,i].ravel()[0] == -1:
6553 squeeze[i] = 0
6554
6555 # Reshape the arrays so we can iterate over them.
6556 strt = start.reshape((-1, self.ndim or 1))
6557 cnt = count.reshape((-1, self.ndim or 1))
6558 strd = stride.reshape((-1, self.ndim or 1))
6559 put_ind = put_ind.reshape((-1, self.ndim or 1))
6560
6561 # Fill output array with data chunks.
6562 # Number of variables making up the MFVariable.Variable.
6563 nv = len(self._recLen)
6564 for (start,count,stride,ind) in zip(strt, cnt, strd, put_ind):
6565 # make sure count=-1 becomes count=1
6566 count = [abs(cnt) for cnt in count]
6567 if (numpy.array(stride) < 0).any():
6568 raise IndexError('negative strides not allowed when slicing MFVariable Variable instance')
6569 # Start, stop and step along 1st dimension, eg the unlimited
6570 # dimension.
6571 sta = start[0]
6572 step = stride[0]
6573 stop = sta + count[0] * step
6574
6575 # Build a list representing the concatenated list of all records in
6576 # the MFVariable variable set. The list is composed of 2-elem lists
6577 # each holding:
6578 # the record index inside the variables, from 0 to n
6579 # the index of the Variable instance to which each record belongs
6580 idx = [] # list of record indices
6581 vid = [] # list of Variable indices
6582 for n in range(nv):
6583 k = self._recLen[n] # number of records in this variable
6584 idx.extend(range(k))
6585 vid.extend([n] * k)
6586
6587 # Merge the two lists to get a list of 2-elem lists.
6588 # Slice this list along the first dimension.
6589 lst = list(zip(idx, vid)).__getitem__(slice(sta, stop, step))
6590
6591 # Rebuild the slicing expression for dimensions 1 and ssq.
6592 newSlice = [slice(None, None, None)]
6593 for n in range(1, len(start)): # skip dimension 0
6594 s = slice(start[n],start[n] + count[n] * stride[n], stride[n])
6595 newSlice.append(s)
6596
6597 # Apply the slicing expression to each var in turn, extracting records
6598 # in a list of arrays.
6599 lstArr = []
6600 ismasked = False
6601 for n in range(nv):
6602 # Get the list of indices for variable 'n'.
6603 idx = [i for i,numv in lst if numv == n]
6604 if idx:
6605 # Rebuild slicing expression for dimension 0.
6606 newSlice[0] = slice(idx[0], idx[-1] + 1, step)
6607 # Extract records from the var, and append them to a list
6608 # of arrays.
6609 dat = Variable.__getitem__(self._recVar[n],tuple(newSlice))
6610 if ma.isMA(dat) and not ismasked:
6611 ismasked=True
6612 fill_value = dat.fill_value
6613 lstArr.append(dat)
6614 if ismasked:
6615 lstArr = ma.concatenate(lstArr)
6616 else:
6617 lstArr = numpy.concatenate(lstArr)
6618 if lstArr.dtype != data.dtype: data = data.astype(lstArr.dtype)
6619 # sometimes there are legitimate singleton dimensions, in which
6620 # case the array shapes won't conform. If so, a ValueError will
6621 # result, and no squeeze will be done.
6622 try:
6623 data[tuple(ind)] = lstArr.squeeze()
6624 except ValueError:
6625 data[tuple(ind)] = lstArr
6626
6627 # Remove extra singleton dimensions.
6628 data = data[tuple(squeeze)]
6629
6630 # if no masked elements, return numpy array.
6631 if ma.isMA(data) and not data.mask.any():
6632 data = data.filled()
6633
6634 return data
6635
6636
6637 class MFTime(_Variable):
6638 """
6639 Class providing an interface to a MFDataset time Variable by imposing a unique common
6640 time unit and/or calendar to all files.
6641
6642 Example usage (See `netCDF4.MFTime.__init__` for more details):
6643
6644 :::python
6645 >>> import numpy
6646 >>> f1 = Dataset("mftest_1.nc","w", format="NETCDF4_CLASSIC")
6647 >>> f2 = Dataset("mftest_2.nc","w", format="NETCDF4_CLASSIC")
6648 >>> f1.createDimension("time",None)
6649 >>> f2.createDimension("time",None)
6650 >>> t1 = f1.createVariable("time","i",("time",))
6651 >>> t2 = f2.createVariable("time","i",("time",))
6652 >>> t1.units = "days since 2000-01-01"
6653 >>> t2.units = "days since 2000-02-01"
6654 >>> t1.calendar = "standard"
6655 >>> t2.calendar = "standard"
6656 >>> t1[:] = numpy.arange(31)
6657 >>> t2[:] = numpy.arange(30)
6658 >>> f1.close()
6659 >>> f2.close()
6660 >>> # Read the two files in at once, in one Dataset.
6661 >>> f = MFDataset("mftest_*nc")
6662 >>> t = f.variables["time"]
6663 >>> print(t.units)
6664 days since 2000-01-01
6665 >>> print(t[32]) # The value written in the file, inconsistent with the MF time units.
6666 1
6667 >>> T = MFTime(t)
6668 >>> print(T[32])
6669 32
6670 """
6671
6672 def __init__(self, time, units=None, calendar=None):
6673 """
6674 **`__init__(self, time, units=None, calendar=None)`**
6675
6676 Create a time Variable with units consistent across a multifile
6677 dataset.
6678
6679 **`time`**: Time variable from a `netCDF4.MFDataset`.
6680
6681 **`units`**: Time units, for example, `'days since 1979-01-01'`. If `None`,
6682 use the units from the master variable.
6683
6684 **`calendar`**: Calendar overload to use across all files, for example,
6685 `'standard'` or `'gregorian'`. If `None`, check that the calendar attribute
6686 is present on each variable and values are unique across files raising a
6687 `ValueError` otherwise.
6688 """
6689 import datetime
6690 self.__time = time
6691
6692 # copy attributes from master time variable.
6693 for name, value in time.__dict__.items():
6694 self.__dict__[name] = value
6695
6696 # Make sure calendar attribute present in all files if no default calendar
6697 # is provided. Also assert this value is the same across files.
6698 if calendar is None:
6699 calendars = [None] * len(self._recVar)
6700 for idx, t in enumerate(self._recVar):
6701 if not hasattr(t, 'calendar'):
6702 msg = 'MFTime requires that the time variable in all files ' \
6703 'have a calendar attribute if no default calendar is provided.'
6704 raise ValueError(msg)
6705 else:
6706 calendars[idx] = t.calendar
6707 calendars = set(calendars)
6708 if len(calendars) > 1:
6709 msg = 'MFTime requires that the same time calendar is ' \
6710 'used by all files if no default calendar is provided.'
6711 raise ValueError(msg)
6712 else:
6713 calendar = list(calendars)[0]
6714
6715 # Set calendar using the default or the unique calendar value across all files.
6716 self.calendar = calendar
6717
6718 # Override units if units is specified.
6719 self.units = units or time.units
6720
6721 # Reference date to compute the difference between different time units.
6722 ref_date = datetime.datetime(1900,1,1)
6723 ref_num = date2num(ref_date, self.units, self.calendar)
6724
6725 # Create delta vector: delta = ref_num(ref_date) - num(ref_date)
6726 # So that ref_num(date) = num(date) + delta
6727 self.__delta = numpy.empty(len(self), time.dtype)
6728
6729 i0 = 0; i1 = 0
6730 for i,v in enumerate(self._recVar):
6731 n = self._recLen[i] # Length of time vector.
6732 num = date2num(ref_date, v.units, self.calendar)
6733 i1 += n
6734 self.__delta[i0:i1] = ref_num - num
6735 i0 += n
6736
6737
6738 def __getitem__(self, elem):
6739 return self.__time[elem] + self.__delta[elem]
+0
-973
netCDF4/utils.py less more
0 from __future__ import print_function
1
2 import sys
3 import numpy as np
4 from numpy import ma
5 from numpy.lib.stride_tricks import as_strided
6 import warnings
7 import getopt
8 import os
9
10 python3 = sys.version_info[0] > 2
11 if python3:
12 # no unicode type in python 3, use bytes instead when testing
13 # for a string-like object
14 unicode = str
15 else:
16 range = xrange
17 try:
18 bytes
19 except NameError:
20 # no bytes type in python < 2.6
21 bytes = str
22
23 def _safecast(a,b):
24 # check to see if array a can be safely cast
25 # to array b. A little less picky than numpy.can_cast.
26 try:
27 is_safe = ((a == b) | (np.isnan(a) & np.isnan(b))).all()
28 #is_safe = np.allclose(a, b, equal_nan=True) # numpy 1.10.0
29 except:
30 try:
31 is_safe = (a == b).all() # string arrays.
32 except:
33 is_safe = False
34 return is_safe
35
36 def _sortbylist(A,B):
37 # sort one list (A) using the values from another list (B)
38 return [A[i] for i in sorted(range(len(A)), key=B.__getitem__)]
39
40 def _find_dim(grp, dimname):
41 # find Dimension instance given group and name.
42 # look in current group, and parents.
43 group = grp
44 dim = None
45 while 1:
46 try:
47 dim = group.dimensions[dimname]
48 break
49 except:
50 try:
51 group = group.parent
52 except:
53 raise ValueError("cannot find dimension %s in this group or parent groups" % dimname)
54 return dim
55
56 def _walk_grps(topgrp):
57 """Iterate through all (sub-) groups of topgrp, similar to os.walktree.
58
59 """
60 grps = topgrp.groups.values()
61 yield grps
62 for grp in topgrp.groups.values():
63 for children in _walk_grps(grp):
64 yield children
65
66 def _quantize(data,least_significant_digit):
67 """
68 quantize data to improve compression. data is quantized using
69 around(scale*data)/scale, where scale is 2**bits, and bits is determined
70 from the least_significant_digit. For example, if
71 least_significant_digit=1, bits will be 4.
72 """
73 precision = pow(10.,-least_significant_digit)
74 exp = np.log10(precision)
75 if exp < 0:
76 exp = int(np.floor(exp))
77 else:
78 exp = int(np.ceil(exp))
79 bits = np.ceil(np.log2(pow(10.,-exp)))
80 scale = pow(2.,bits)
81 datout = np.around(scale*data)/scale
82 if ma.isMA(datout):
83 datout.set_fill_value(data.fill_value)
84 return datout
85 else:
86 return datout
87
88 def _StartCountStride(elem, shape, dimensions=None, grp=None, datashape=None,\
89 put=False, use_get_vars = False):
90 """Return start, count, stride and indices needed to store/extract data
91 into/from a netCDF variable.
92
93 This function is used to convert a slicing expression into a form that is
94 compatible with the nc_get_vars function. Specifically, it needs
95 to interpret integers, slices, Ellipses, and 1-d sequences of integers
96 and booleans.
97
98 Numpy uses "broadcasting indexing" to handle array-valued indices.
99 "Broadcasting indexing" (a.k.a "fancy indexing") treats all multi-valued
100 indices together to allow arbitrary points to be extracted. The index
101 arrays can be multidimensional, and more than one can be specified in a
102 slice, as long as they can be "broadcast" against each other.
103 This style of indexing can be very powerful, but it is very hard
104 to understand, explain, and implement (and can lead to hard to find bugs).
105 Most other python packages and array processing
106 languages (such as netcdf4-python, xray, biggus, matlab and fortran)
107 use "orthogonal indexing" which only allows for 1-d index arrays and
108 treats these arrays of indices independently along each dimension.
109
110 The implementation of "orthogonal indexing" used here requires that
111 index arrays be 1-d boolean or integer. If integer arrays are used,
112 the index values must be sorted and contain no duplicates.
113
114 In summary, slicing netcdf4-python variable objects with 1-d integer or
115 boolean arrays is allowed, but may give a different result than slicing a
116 numpy array.
117
118 Numpy also supports slicing an array with a boolean array of the same
119 shape. For example x[x>0] returns a 1-d array with all the positive values of x.
120 This is also not supported in netcdf4-python, if x.ndim > 1.
121
122 Orthogonal indexing can be used in to select netcdf variable slices
123 using the dimension variables. For example, you can use v[lat>60,lon<180]
124 to fetch the elements of v obeying conditions on latitude and longitude.
125 Allow for this sort of simple variable subsetting is the reason we decided to
126 deviate from numpy's slicing rules.
127
128 This function is used both by the __setitem__ and __getitem__ method of
129 the Variable class.
130
131 Parameters
132 ----------
133 elem : tuple of integer, slice, ellipsis or 1-d boolean or integer
134 sequences used to slice the netCDF Variable (Variable[elem]).
135 shape : tuple containing the current shape of the netCDF variable.
136 dimensions : sequence
137 The name of the dimensions.
138 __setitem__.
139 grp : netCDF Group
140 The netCDF group to which the variable being set belongs to.
141 datashape : sequence
142 The shape of the data that is being stored. Only needed by __setitem__
143 put : True|False (default False). If called from __setitem__, put is True.
144
145 Returns
146 -------
147 start : ndarray (..., n)
148 A starting indices array of dimension n+1. The first n
149 dimensions identify different independent data chunks. The last dimension
150 can be read as the starting indices.
151 count : ndarray (..., n)
152 An array of dimension (n+1) storing the number of elements to get.
153 stride : ndarray (..., n)
154 An array of dimension (n+1) storing the steps between each datum.
155 indices : ndarray (..., n)
156 An array storing the indices describing the location of the
157 data chunk in the target/source array (__getitem__/__setitem__).
158
159 Notes:
160
161 netCDF data is accessed via the function:
162 nc_get_vars(grpid, varid, start, count, stride, data)
163
164 Assume that the variable has dimension n, then
165
166 start is a n-tuple that contains the indices at the beginning of data chunk.
167 count is a n-tuple that contains the number of elements to be accessed.
168 stride is a n-tuple that contains the step length between each element.
169
170 """
171 # Adapted from pycdf (http://pysclint.sourceforge.net/pycdf)
172 # by Andre Gosselin..
173 # Modified by David Huard to handle efficiently fancy indexing with
174 # sequences of integers or booleans.
175
176 nDims = len(shape)
177 if nDims == 0:
178 nDims = 1
179 shape = (1,)
180
181 # is there an unlimited dimension? (only defined for __setitem__)
182 if put:
183 hasunlim = False
184 unlimd={}
185 if dimensions:
186 for i in range(nDims):
187 dimname = dimensions[i]
188 # is this dimension unlimited?
189 # look in current group, and parents for dim.
190 dim = _find_dim(grp, dimname)
191 unlimd[dimname]=dim.isunlimited()
192 if unlimd[dimname]:
193 hasunlim = True
194 else:
195 hasunlim = False
196
197 # When a single array or (non-tuple) sequence of integers is given
198 # as a slice, assume it applies to the first dimension,
199 # and use ellipsis for remaining dimensions.
200 if np.iterable(elem):
201 if type(elem) == np.ndarray or (type(elem) != tuple and \
202 np.array([_is_int(e) for e in elem]).all()):
203 elem = [elem]
204 for n in range(len(elem)+1,nDims+1):
205 elem.append(slice(None,None,None))
206 else: # Convert single index to sequence
207 elem = [elem]
208
209 # ensure there is at most 1 ellipse
210 # we cannot use elem.count(Ellipsis), as with fancy indexing would occur
211 # np.array() == Ellipsis which gives ValueError: The truth value of an
212 # array with more than one element is ambiguous. Use a.any() or a.all()
213 if sum(1 for e in elem if e is Ellipsis) > 1:
214 raise IndexError("At most one ellipsis allowed in a slicing expression")
215
216 # replace boolean arrays with sequences of integers.
217 newElem = []
218 IndexErrorMsg=\
219 "only integers, slices (`:`), ellipsis (`...`), and 1-d integer or boolean arrays are valid indices"
220 i=0
221 for e in elem:
222 # string-like object try to cast to int
223 # needs to be done first, since strings are iterable and
224 # hard to distinguish from something castable to an iterable numpy array.
225 if type(e) in [str,bytes,unicode]:
226 try:
227 e = int(e)
228 except:
229 raise IndexError(IndexErrorMsg)
230 ea = np.asarray(e)
231 # Raise error if multidimensional indexing is used.
232 if ea.ndim > 1:
233 raise IndexError("Index cannot be multidimensional")
234 # set unlim to True if dimension is unlimited and put==True
235 # (called from __setitem__)
236 if hasunlim and put and dimensions:
237 try:
238 dimname = dimensions[i]
239 unlim = unlimd[dimname]
240 except IndexError: # more slices than dimensions (issue 371)
241 unlim = False
242 else:
243 unlim = False
244 # convert boolean index to integer array.
245 if np.iterable(ea) and ea.dtype.kind =='b':
246 # check that boolen array not too long
247 if not unlim and shape[i] != len(ea):
248 msg="""
249 Boolean array must have the same shape as the data along this dimension."""
250 raise IndexError(msg)
251 ea = np.flatnonzero(ea)
252 # an iterable (non-scalar) integer array.
253 if np.iterable(ea) and ea.dtype.kind == 'i':
254 # convert negative indices in 1d array to positive ones.
255 ea = np.where(ea < 0, ea + shape[i], ea)
256 if np.any(ea < 0):
257 raise IndexError("integer index out of range")
258 # if unlim, let integer index be longer than current dimension
259 # length.
260 if ea.shape != (0,):
261 elen = shape[i]
262 if unlim:
263 elen = max(ea.max()+1,elen)
264 if ea.max()+1 > elen:
265 msg="integer index exceeds dimension size"
266 raise IndexError(msg)
267 newElem.append(ea)
268 # integer scalar
269 elif ea.dtype.kind == 'i':
270 newElem.append(e)
271 # slice or ellipsis object
272 elif type(e) == slice or type(e) == type(Ellipsis):
273 if not use_get_vars and type(e) == slice and e.step not in [None,-1,1] and\
274 dimensions is not None and grp is not None:
275 # convert strided slice to integer sequence if possible
276 # (this will avoid nc_get_vars, which is slow - issue #680).
277 start = e.start if e.start is not None else 0
278 step = e.step
279 if e.stop is None and dimensions is not None and grp is not None:
280 stop = len(_find_dim(grp, dimensions[i]))
281 else:
282 stop = e.stop
283 if stop < 0:
284 stop = len(_find_dim(grp, dimensions[i])) + stop
285 try:
286 ee = np.arange(start,stop,e.step)
287 if len(ee) > 0:
288 e = ee
289 except:
290 pass
291 newElem.append(e)
292 else: # castable to a scalar int, otherwise invalid
293 try:
294 e = int(e)
295 newElem.append(e)
296 except:
297 raise IndexError(IndexErrorMsg)
298 if type(e)==type(Ellipsis):
299 i+=1+nDims-len(elem)
300 else:
301 i+=1
302 elem = newElem
303
304 # replace Ellipsis and integer arrays with slice objects, if possible.
305 newElem = []
306 for e in elem:
307 ea = np.asarray(e)
308 # Replace ellipsis with slices.
309 if type(e) == type(Ellipsis):
310 # The ellipsis stands for the missing dimensions.
311 newElem.extend((slice(None, None, None),) * (nDims - len(elem) + 1))
312 # Replace sequence of indices with slice object if possible.
313 elif np.iterable(e) and len(e) > 1:
314 start = e[0]
315 stop = e[-1]+1
316 step = e[1]-e[0]
317 try:
318 ee = range(start,stop,step)
319 except ValueError: # start, stop or step is not valid for a range
320 ee = False
321 if ee and len(e) == len(ee) and (e == np.arange(start,stop,step)).all():
322 # don't convert to slice unless abs(stride) == 1
323 # (nc_get_vars is very slow, issue #680)
324 if not use_get_vars and step not in [1,-1]:
325 newElem.append(e)
326 else:
327 newElem.append(slice(start,stop,step))
328 else:
329 newElem.append(e)
330 elif np.iterable(e) and len(e) == 1:
331 newElem.append(slice(e[0], e[0] + 1, 1))
332 else:
333 newElem.append(e)
334 elem = newElem
335
336 # If slice doesn't cover all dims, assume ellipsis for rest of dims.
337 if len(elem) < nDims:
338 for n in range(len(elem)+1,nDims+1):
339 elem.append(slice(None,None,None))
340
341 # make sure there are not too many dimensions in slice.
342 if len(elem) > nDims:
343 raise ValueError("slicing expression exceeds the number of dimensions of the variable")
344
345 # Compute the dimensions of the start, count, stride and indices arrays.
346 # The number of elements in the first n dimensions corresponds to the
347 # number of times the _get method will be called.
348 sdim = []
349 for i, e in enumerate(elem):
350 # at this stage e is a slice, a scalar integer, or a 1d integer array.
351 # integer array: _get call for each True value
352 if np.iterable(e):
353 sdim.append(len(e))
354 # Scalar int or slice, just a single _get call
355 else:
356 sdim.append(1)
357
358 # broadcast data shape when assigned to full variable (issue #919)
359 try:
360 fullslice = elem.count(slice(None,None,None)) == len(elem)
361 except: # fails if elem contains a numpy array.
362 fullslice = False
363 if fullslice and datashape and put and not hasunlim:
364 datashape = broadcasted_shape(shape, datashape)
365
366 # pad datashape with zeros for dimensions not being sliced (issue #906)
367 # only used when data covers slice over subset of dimensions
368 if datashape and len(datashape) != len(elem) and\
369 len(datashape) == sum(1 for e in elem if type(e) == slice):
370 datashapenew = (); i=0
371 for e in elem:
372 if type(e) != slice and not np.iterable(e): # scalar integer slice
373 datashapenew = datashapenew + (0,)
374 else: # slice object
375 datashapenew = datashapenew + (datashape[i],)
376 i+=1
377 datashape = datashapenew
378
379 # Create the start, count, stride and indices arrays.
380
381 sdim.append(max(nDims, 1))
382 start = np.empty(sdim, dtype=int)
383 count = np.empty(sdim, dtype=int)
384 stride = np.empty(sdim, dtype=int)
385 indices = np.empty(sdim, dtype=object)
386
387 for i, e in enumerate(elem):
388
389 ea = np.asarray(e)
390
391 # set unlim to True if dimension is unlimited and put==True
392 # (called from __setitem__). Note: grp and dimensions must be set.
393 if hasunlim and put and dimensions:
394 dimname = dimensions[i]
395 unlim = unlimd[dimname]
396 else:
397 unlim = False
398
399 # SLICE #
400 if type(e) == slice:
401
402 # determine length parameter for slice.indices.
403
404 # shape[i] can be zero for unlim dim that hasn't been written to
405 # yet.
406 # length of slice may be longer than current shape
407 # if dimension is unlimited (and we are writing, not reading).
408 if unlim and e.stop is not None and e.stop > shape[i]:
409 length = e.stop
410 elif unlim and e.stop is None and datashape != ():
411 try:
412 if e.start is None:
413 length = datashape[i]
414 else:
415 length = e.start+datashape[i]
416 except IndexError:
417 raise IndexError("shape of data does not conform to slice")
418 else:
419 if unlim and datashape == () and len(dim) == 0:
420 # writing scalar along unlimited dimension using slicing
421 # syntax (var[:] = 1, when var.shape = ())
422 length = 1
423 else:
424 length = shape[i]
425
426 beg, end, inc = e.indices(length)
427 n = len(range(beg,end,inc))
428
429 start[...,i] = beg
430 count[...,i] = n
431 stride[...,i] = inc
432 indices[...,i] = slice(None)
433
434 # ITERABLE #
435 elif np.iterable(e) and np.array(e).dtype.kind in 'i': # Sequence of integers
436 start[...,i] = np.apply_along_axis(lambda x: e*x, i, np.ones(sdim[:-1]))
437 indices[...,i] = np.apply_along_axis(lambda x: np.arange(sdim[i])*x, i, np.ones(sdim[:-1], int))
438
439 count[...,i] = 1
440 stride[...,i] = 1
441
442 # all that's left is SCALAR INTEGER #
443 else:
444 if e >= 0:
445 start[...,i] = e
446 elif e < 0 and (-e <= shape[i]) :
447 start[...,i] = e+shape[i]
448 else:
449 raise IndexError("Index out of range")
450
451 count[...,i] = 1
452 stride[...,i] = 1
453 indices[...,i] = -1 # Use -1 instead of 0 to indicate that
454 # this dimension shall be squeezed.
455
456 return start, count, stride, indices#, out_shape
457
458 def _out_array_shape(count):
459 """Return the output array shape given the count array created by getStartCountStride"""
460
461 s = list(count.shape[:-1])
462 out = []
463
464 for i, n in enumerate(s):
465 if n == 1:
466 c = count[..., i].ravel()[0] # All elements should be identical.
467 out.append(c)
468 else:
469 out.append(n)
470 return out
471
472 def _is_container(a):
473 # is object container-like? (can test for
474 # membership with "is in", but not a string)
475 try: 1 in a
476 except: return False
477 if type(a) == type(basestring): return False
478 return True
479
480 def _is_int(a):
481 try:
482 return int(a) == a
483 except:
484 return False
485
486 def _tostr(s):
487 try:
488 ss = str(s)
489 except:
490 ss = s
491 return ss
492
493
494 def _getgrp(g,p):
495 import posixpath
496 grps = p.split("/")
497 for gname in grps:
498 if gname == "": continue
499 g = g.groups[gname]
500 return g
501
502 def ncinfo():
503
504 from netCDF4 import Dataset
505
506
507 usage = """
508 Print summary information about a netCDF file.
509
510 usage: %s [-h/--help] [-g grp or --group=grp] [-v var or --variable=var] [-d dim or --dimension=dim] filename
511
512 -h/--help -- Print usage message.
513 -g <group name> or --group=<group name> -- Print info for this group
514 (default is root group). Nested groups specified
515 using posix paths ("group1/group2/group3").
516 -v <variable name> or --variable=<variable name> -- Print info for this variable.
517 -d <dimension name> or --dimension=<dimension name> -- Print info for this dimension.
518
519 netcdf filename must be last argument.
520 \n""" % os.path.basename(sys.argv[0])
521
522 try:
523 opts, pargs = getopt.getopt(sys.argv[1:],'hv:g:d:',
524 ['group=',
525 'variable=',
526 'dimension='])
527 except:
528 (type, value, traceback) = sys.exc_info()
529 sys.stdout.write("Error parsing the options. The error was: %s\n" % value)
530 sys.stderr.write(usage)
531 sys.exit(0)
532
533 # Get the options
534 group = None; var = None; dim=None
535 for option in opts:
536 if option[0] == '-h' or option[0] == '--help':
537 sys.stderr.write(usage)
538 sys.exit(0)
539 elif option[0] == '--group' or option[0] == '-g':
540 group = option[1]
541 elif option[0] == '--variable' or option[0] == '-v':
542 var = option[1]
543 elif option[0] == '--dimension' or option[0] == '-d':
544 dim = option[1]
545 else:
546 sys.stdout.write("%s: Unrecognized option\n" % option[0])
547 sys.stderr.write(usage)
548 sys.exit(0)
549
550 # filename passed as last argumenbt
551 try:
552 filename = pargs[-1]
553 except IndexError:
554 sys.stdout.write("You need to pass netcdf filename!\n.")
555 sys.stderr.write(usage)
556 sys.exit(0)
557
558 f = Dataset(filename)
559 if group is None:
560 if var is None and dim is None:
561 print(f)
562 else:
563 if var is not None:
564 print(f.variables[var])
565 if dim is not None:
566 print(f.dimensions[dim])
567 else:
568 if var is None and dim is None:
569 print(_getgrp(f,group))
570 else:
571 g = _getgrp(f,group)
572 if var is not None:
573 print(g.variables[var])
574 if dim is not None:
575 print(g.dimensions[var])
576 f.close()
577
578 def _nc4tonc3(filename4,filename3,clobber=False,nchunk=10,quiet=False,format='NETCDF3_64BIT'):
579 """convert a netcdf 4 file (filename4) in NETCDF4_CLASSIC format
580 to a netcdf 3 file (filename3) in NETCDF3_64BIT format."""
581
582 from netCDF4 import Dataset
583
584 ncfile4 = Dataset(filename4,'r')
585 if ncfile4.file_format != 'NETCDF4_CLASSIC':
586 raise IOError('input file must be in NETCDF4_CLASSIC format')
587 ncfile3 = Dataset(filename3,'w',clobber=clobber,format=format)
588 # create dimensions. Check for unlimited dim.
589 unlimdimname = False
590 unlimdim = None
591 # create global attributes.
592 if not quiet: sys.stdout.write('copying global attributes ..\n')
593 #for attname in ncfile4.ncattrs():
594 # setattr(ncfile3,attname,getattr(ncfile4,attname))
595 ncfile3.setncatts(ncfile4.__dict__)
596 if not quiet: sys.stdout.write('copying dimensions ..\n')
597 for dimname,dim in ncfile4.dimensions.items():
598 if dim.isunlimited():
599 unlimdimname = dimname
600 unlimdim = dim
601 ncfile3.createDimension(dimname,None)
602 else:
603 ncfile3.createDimension(dimname,len(dim))
604 # create variables.
605 for varname,ncvar in ncfile4.variables.items():
606 if not quiet:
607 sys.stdout.write('copying variable %s\n' % varname)
608 # is there an unlimited dimension?
609 if unlimdimname and unlimdimname in ncvar.dimensions:
610 hasunlimdim = True
611 else:
612 hasunlimdim = False
613 if hasattr(ncvar, '_FillValue'):
614 FillValue = ncvar._FillValue
615 else:
616 FillValue = None
617 var = ncfile3.createVariable(varname,ncvar.dtype,ncvar.dimensions,fill_value=FillValue)
618 # fill variable attributes.
619 attdict = ncvar.__dict__
620 if '_FillValue' in attdict:
621 del attdict['_FillValue']
622 var.setncatts(attdict)
623 #for attname in ncvar.ncattrs():
624 # if attname == '_FillValue': continue
625 # setattr(var,attname,getattr(ncvar,attname))
626 # fill variables with data.
627 if hasunlimdim: # has an unlim dim, loop over unlim dim index.
628 # range to copy
629 if nchunk:
630 start = 0; stop = len(unlimdim); step = nchunk
631 if step < 1:
632 step = 1
633 for n in range(start, stop, step):
634 nmax = n+nchunk
635 if nmax > len(unlimdim):
636 nmax=len(unlimdim)
637 var[n:nmax] = ncvar[n:nmax]
638 else:
639 var[0:len(unlimdim)] = ncvar[:]
640 else: # no unlim dim or 1-d variable, just copy all data at once.
641 var[:] = ncvar[:]
642 ncfile3.sync() # flush data to disk
643 # close files.
644 ncfile3.close()
645 ncfile4.close()
646
647 def nc4tonc3():
648 usage = """
649 Convert a netCDF 4 file (in NETCDF4_CLASSIC format) to netCDF 3 format.
650
651 usage: %s [-h/--help] [-o] [--chunk] netcdf4filename netcdf3filename
652 -h/--help -- Print usage message.
653 -o -- Overwrite destination file (default is to raise an error if output file already exists).
654 --quiet=(0|1) -- if 1, don't print diagnostic information.
655 --format -- netcdf3 format to use (NETCDF3_64BIT by default, can be set to NETCDF3_CLASSIC)
656 --chunk=(integer) -- number of records along unlimited dimension to
657 write at once. Default 10. Ignored if there is no unlimited
658 dimension. chunk=0 means write all the data at once.
659 \n""" % os.path.basename(sys.argv[0])
660
661 try:
662 opts, pargs = getopt.getopt(sys.argv[1:], 'ho',
663 ['format=','chunk=','quiet='])
664 except:
665 (type, value, traceback) = sys.exc_info()
666 sys.stdout.write("Error parsing the options. The error was: %s\n" % value)
667 sys.stderr.write(usage)
668 sys.exit(0)
669
670 # default options
671 quiet = 0
672 chunk = 1000
673 format = 'NETCDF3_64BIT'
674 overwritefile = 0
675
676 # Get the options
677 for option in opts:
678 if option[0] == '-h' or option[0] == '--help':
679 sys.stderr.write(usage)
680 sys.exit(0)
681 elif option[0] == '-o':
682 overwritefile = 1
683 elif option[0] == '--quiet':
684 quiet = int(option[1])
685 elif option[0] == '--format':
686 format = option[1]
687 elif option[0] == '--chunk':
688 chunk = int(option[1])
689 else:
690 sys.stdout.write("%s : Unrecognized option\n" % options[0])
691 sys.stderr.write(usage)
692 sys.exit(0)
693
694 # if we pass a number of files different from 2, abort
695 if len(pargs) < 2 or len(pargs) > 2:
696 sys.stdout.write("You need to pass both source and destination!\n.")
697 sys.stderr.write(usage)
698 sys.exit(0)
699
700 # Catch the files passed as the last arguments
701 filename4 = pargs[0]
702 filename3 = pargs[1]
703
704 # copy the data from filename4 to filename3.
705 _nc4tonc3(filename4,filename3,clobber=overwritefile,quiet=quiet,format=format)
706
707
708 def _nc3tonc4(filename3,filename4,unpackshort=True,
709 zlib=True,complevel=6,shuffle=True,fletcher32=False,
710 clobber=False,lsd_dict=None,nchunk=10,quiet=False,classic=0,
711 vars=None,istart=0,istop=-1):
712 """convert a netcdf 3 file (filename3) to a netcdf 4 file
713 The default format is 'NETCDF4', but can be set
714 to NETCDF4_CLASSIC if classic=1.
715 If unpackshort=True, variables stored as short
716 integers with a scale and offset are unpacked to floats.
717 in the netcdf 4 file. If the lsd_dict is not None, variable names
718 corresponding to the keys of the dict will be truncated to the decimal place
719 specified by the values of the dict. This improves compression by
720 making it 'lossy'..
721 If vars is not None, only variable names in the list
722 will be copied (plus all the dimension variables).
723 The zlib, complevel and shuffle keywords control
724 how the compression is done."""
725
726 from netCDF4 import Dataset
727
728 ncfile3 = Dataset(filename3,'r')
729 if classic:
730 ncfile4 = Dataset(filename4,'w',clobber=clobber,format='NETCDF4_CLASSIC')
731 else:
732 ncfile4 = Dataset(filename4,'w',clobber=clobber,format='NETCDF4')
733 mval = 1.e30 # missing value if unpackshort=True
734 # create dimensions. Check for unlimited dim.
735 unlimdimname = False
736 unlimdim = None
737 # create global attributes.
738 if not quiet: sys.stdout.write('copying global attributes ..\n')
739 #for attname in ncfile3.ncattrs():
740 # setattr(ncfile4,attname,getattr(ncfile3,attname))
741 ncfile4.setncatts(ncfile3.__dict__)
742 if not quiet: sys.stdout.write('copying dimensions ..\n')
743 for dimname,dim in ncfile3.dimensions.items():
744 if dim.isunlimited():
745 unlimdimname = dimname
746 unlimdim = dim
747 ncfile4.createDimension(dimname,None)
748 if istop == -1: istop=len(unlimdim)
749 else:
750 ncfile4.createDimension(dimname,len(dim))
751 # create variables.
752 if vars is None:
753 varnames = ncfile3.variables.keys()
754 else:
755 # variables to copy specified
756 varnames = vars
757 # add dimension variables
758 for dimname in ncfile3.dimensions.keys():
759 if dimname in ncfile3.variables.keys() and\
760 dimname not in varnames:
761 varnames.append(dimname)
762 for varname in varnames:
763 ncvar = ncfile3.variables[varname]
764 if not quiet: sys.stdout.write('copying variable %s\n' % varname)
765 # quantize data?
766 if lsd_dict is not None and varname in lsd_dict:
767 lsd = lsd_dict[varname]
768 if not quiet: sys.stdout.write('truncating to least_significant_digit = %d\n'%lsd)
769 else:
770 lsd = None # no quantization.
771 # unpack short integers to floats?
772 if unpackshort and hasattr(ncvar,'scale_factor') and hasattr(ncvar,'add_offset'):
773 dounpackshort = True
774 datatype = 'f4'
775 else:
776 dounpackshort = False
777 datatype = ncvar.dtype
778 # is there an unlimited dimension?
779 if unlimdimname and unlimdimname in ncvar.dimensions:
780 hasunlimdim = True
781 else:
782 hasunlimdim = False
783 if dounpackshort:
784 if not quiet: sys.stdout.write('unpacking short integers to floats ...\n')
785 sys.stdout.write('')
786 # is there missing value?
787 if hasattr(ncvar, '_FillValue'):
788 fillvalue3 = ncvar._FillValue
789 elif hasattr(ncvar, 'missing_value'):
790 fillvalue3 = ncvar.missing_value
791 else:
792 fillvalue3 = None
793 if fillvalue3 is not None:
794 fillvalue4 = fillvalue3 if not dounpackshort else mval
795 else:
796 fillvalue4 = None
797 var = ncfile4.createVariable(varname,datatype,ncvar.dimensions, fill_value=fillvalue4, least_significant_digit=lsd,zlib=zlib,complevel=complevel,shuffle=shuffle,fletcher32=fletcher32)
798 # fill variable attributes.
799 attdict = ncvar.__dict__
800 if '_FillValue' in attdict: del attdict['_FillValue']
801 if dounpackshort and 'add_offset' in attdict:
802 del attdict['add_offset']
803 if dounpackshort and 'scale_factor' in attdict:
804 del attdict['scale_factor']
805 if dounpackshort and 'missing_value' in attdict:
806 attdict['missing_value'] = fillvalue4
807 var.setncatts(attdict)
808 # fill variables with data.
809 if hasunlimdim: # has an unlim dim, loop over unlim dim index.
810 # range to copy
811 if nchunk:
812 start = istart; stop = istop; step = nchunk
813 if step < 1: step = 1
814 for n in range(start, stop, step):
815 nmax = n+nchunk
816 if nmax > istop: nmax=istop
817 var[n-istart:nmax-istart] = ncvar[n:nmax]
818 else:
819 var[0:len(unlimdim)] = ncvar[:]
820 else: # no unlim dim or 1-d variable, just copy all data at once.
821 var[:] = ncvar[:]
822 ncfile4.sync() # flush data to disk
823 # close files.
824 ncfile3.close()
825 ncfile4.close()
826
827
828 def nc3tonc4():
829 usage = """
830 Convert a netCDF 3 file to netCDF 4 format, optionally
831 unpacking variables packed as short integers (with scale_factor and add_offset)
832 to floats, and adding zlib compression (with the HDF5 shuffle filter and fletcher32 checksum).
833 Data may also be quantized (truncated) to a specified precision to improve compression.
834
835 usage: %s [-h/--help] [-o] [--vars=var1,var2,..] [--zlib=(0|1)] [--complevel=(1-9)] [--shuffle=(0|1)] [--fletcher32=(0|1)] [--unpackshort=(0|1)] [--quantize=var1=n1,var2=n2,..] netcdf3filename netcdf4filename
836 -h/--help -- Print usage message.
837 -o -- Overwrite destination file (default is to raise an error if output file already exists).
838 --vars -- comma separated list of variable names to copy (default is to copy
839 all variables)
840 --classic=(0|1) -- use NETCDF4_CLASSIC format instead of NETCDF4 (default 1)
841 --zlib=(0|1) -- Activate (or disable) zlib compression (default is activate).
842 --complevel=(1-9) -- Set zlib compression level (6 is default).
843 --shuffle=(0|1) -- Activate (or disable) the shuffle filter (active by default).
844 --fletcher32=(0|1) -- Activate (or disable) the fletcher32 checksum (not
845 active by default).
846 --unpackshort=(0|1) -- Unpack short integer variables to float variables
847 using scale_factor and add_offset netCDF variable attributes (active by default).
848 --quantize=(comma separated list of "variable name=integer" pairs) --
849 Truncate the data in the specified variables to a given decimal precision.
850 For example, 'speed=2, height=-2, temp=0' will cause the variable
851 'speed' to be truncated to a precision of 0.01, 'height' to a precision of 100
852 and 'temp' to 1. This can significantly improve compression. The default
853 is not to quantize any of the variables.
854 --quiet=(0|1) -- if 1, don't print diagnostic information.
855 --chunk=(integer) -- number of records along unlimited dimension to
856 write at once. Default 10. Ignored if there is no unlimited
857 dimension. chunk=0 means write all the data at once.
858 --istart=(integer) -- number of record to start at along unlimited dimension.
859 Default 0. Ignored if there is no unlimited dimension.
860 --istop=(integer) -- number of record to stop at along unlimited dimension.
861 Default -1. Ignored if there is no unlimited dimension.
862 \n""" % os.path.basename(sys.argv[0])
863
864 try:
865 opts, pargs = getopt.getopt(sys.argv[1:], 'ho',
866 ['classic=',
867 'vars=',
868 'zlib=',
869 'quiet=',
870 'complevel=',
871 'shuffle=',
872 'fletcher32=',
873 'unpackshort=',
874 'quantize=',
875 'chunk=',
876 'istart=',
877 'istop='])
878 except:
879 (type, value, traceback) = sys.exc_info()
880 sys.stdout.write("Error parsing the options. The error was: %s\n" % value)
881 sys.stderr.write(usage)
882 sys.exit(0)
883
884 # default options
885 overwritefile = 0
886 complevel = 6
887 classic = 1
888 zlib = 1
889 shuffle = 1
890 fletcher32 = 0
891 unpackshort = 1
892 vars = None
893 quantize = None
894 quiet = 0
895 chunk = 1000
896 istart = 0
897 istop = -1
898
899 # Get the options
900 for option in opts:
901 if option[0] == '-h' or option[0] == '--help':
902 sys.stderr.write(usage)
903 sys.exit(0)
904 elif option[0] == '-o':
905 overwritefile = 1
906 elif option[0] == '--classic':
907 classic = int(option[1])
908 elif option[0] == '--zlib':
909 zlib = int(option[1])
910 elif option[0] == '--quiet':
911 quiet = int(option[1])
912 elif option[0] == '--complevel':
913 complevel = int(option[1])
914 elif option[0] == '--shuffle':
915 shuffle = int(option[1])
916 elif option[0] == '--fletcher32':
917 fletcher32 = int(option[1])
918 elif option[0] == '--unpackshort':
919 unpackshort = int(option[1])
920 elif option[0] == '--chunk':
921 chunk = int(option[1])
922 elif option[0] == '--vars':
923 vars = option[1]
924 elif option[0] == '--quantize':
925 quantize = option[1]
926 elif option[0] == '--istart':
927 istart = int(option[1])
928 elif option[0] == '--istop':
929 istop = int(option[1])
930 else:
931 sys.stdout.write("%s: Unrecognized option\n" % option[0])
932 sys.stderr.write(usage)
933 sys.exit(0)
934
935 # if we pass a number of files different from 2, abort
936 if len(pargs) < 2 or len(pargs) > 2:
937 sys.stdout.write("You need to pass both source and destination!.\n")
938 sys.stderr.write(usage)
939 sys.exit(0)
940
941 # Catch the files passed as the last arguments
942 filename3 = pargs[0]
943 filename4 = pargs[1]
944
945 # Parse the quantize option, create a dictionary from key/value pairs.
946 if quantize is not None:
947 lsd_dict = {}
948 for p in quantize.split(','):
949 kv = p.split('=')
950 lsd_dict[kv[0]] = int(kv[1])
951 else:
952 lsd_dict=None
953
954 # Parse the vars option, create a list of variable names.
955 if vars is not None:
956 vars = vars.split(',')
957
958 # copy the data from filename3 to filename4.
959 _nc3tonc4(filename3,filename4,unpackshort=unpackshort,
960 zlib=zlib,complevel=complevel,shuffle=shuffle,
961 fletcher32=fletcher32,clobber=overwritefile,lsd_dict=lsd_dict,
962 nchunk=chunk,quiet=quiet,vars=vars,classic=classic,
963 istart=istart,istop=istop)
964
965 def broadcasted_shape(shp1, shp2):
966 # determine shape of array of shp1 and shp2 broadcast against one another.
967 x = np.array([1])
968 # trick to define array with certain shape that doesn't allocate all the
969 # memory.
970 a = as_strided(x, shape=shp1, strides=[0] * len(shp1))
971 b = as_strided(x, shape=shp2, strides=[0] * len(shp2))
972 return np.broadcast(a, b).shape
4747 #curl_dir = /usr/local
4848 # location of mpi.h (needed for parallel support)
4949 #mpi_incdir=/opt/local/include/mpich-mp
50 [check-manifest]
51 ignore =
52 .gitignore
53 README.gh-pages
54 README.release
55 examples/data/*nc
56 examples/*ipynb
164164 pass # We skip invalid entries, because that's what the C compiler does
165165
166166 return None
167
168 def extract_version(CYTHON_FNAME):
169 version = None
170 with open(CYTHON_FNAME) as fi:
171 for line in fi:
172 if (line.startswith('__version__')):
173 _, version = line.split('=')
174 version = version.strip()[1:-1] # Remove quotation characters.
175 break
176 return version
167177
168178
169179 HDF5_dir = os.environ.get('HDF5_DIR')
372382 libs.extend(['hdf5_hl', 'hdf5'])
373383
374384
375 dirstosearch = [os.path.expanduser('~'), '/usr/local', '/sw', '/opt',
385 dirstosearch = []
386 if os.environ.get("CONDA_PREFIX"):
387 dirstosearch.append(os.environ["CONDA_PREFIX"]) # linux,macosx
388 dirstosearch.append(os.path.join(os.environ["CONDA_PREFIX"],'Library')) # windows
389 dirstosearch += [os.path.expanduser('~'), '/usr/local', '/sw', '/opt',
376390 '/opt/local', '/usr']
377391
378392 # try nc-config first
505519 sys.stdout.write('using netcdf library version %s\n' % netcdf_lib_version)
506520
507521 cmdclass = {}
508 netcdf4_src_root = osp.join('netCDF4', '_netCDF4')
522 DEFINE_MACROS = [("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")]
523 netcdf4_src_root = osp.join(osp.join('src','netCDF4'), '_netCDF4')
509524 netcdf4_src_c = netcdf4_src_root + '.c'
510 if 'sdist' not in sys.argv[1:] and 'clean' not in sys.argv[1:]:
525 netcdf4_src_pyx = netcdf4_src_root + '.pyx'
526 if 'sdist' not in sys.argv[1:] and 'clean' not in sys.argv[1:] and '--version' not in sys.argv[1:]:
511527 sys.stdout.write('using Cython to compile netCDF4.pyx...\n')
512528 # remove _netCDF4.c file if it exists, so cython will recompile _netCDF4.pyx.
513529 # run for build *and* install (issue #263). Otherwise 'pip install' will
599615 if mpi_incdir is not None: inc_dirs.append(mpi_incdir)
600616
601617 ext_modules = [Extension("netCDF4._netCDF4",
602 [netcdf4_src_root + '.pyx'],
618 [netcdf4_src_pyx],
619 define_macros=DEFINE_MACROS,
603620 libraries=libs,
604621 library_dirs=lib_dirs,
605622 include_dirs=inc_dirs + ['include'],
609626
610627 setup(name="netCDF4",
611628 cmdclass=cmdclass,
612 version="1.5.5.1",
629 version=extract_version(netcdf4_src_pyx),
613630 long_description="netCDF version 4 has many features not found in earlier versions of the library, such as hierarchical groups, zlib compression, multiple unlimited dimensions, and new data types. It is implemented on top of HDF5. This module implements most of the new features, and can read and write netCDF files compatible with older versions of the library. The API is modelled after Scientific.IO.NetCDF, and should be familiar to users of that module.\n\nThis project is hosted on a `GitHub repository <https://github.com/Unidata/netcdf4-python>`_ where you may access the most up-to-date source.",
614631 author="Jeff Whitaker",
615632 author_email="jeffrey.s.whitaker@noaa.gov",
631648 "Topic :: System :: Archiving :: Compression",
632649 "Operating System :: OS Independent"],
633650 packages=['netCDF4'],
651 package_dir={'':'src'},
634652 ext_modules=ext_modules,
635653 **setuptools_extra_kwargs)
0 # init for netCDF4. package
1 # Docstring comes from extension module _netCDF4.
2 from ._netCDF4 import *
3 # Need explicit imports for names beginning with underscores
4 from ._netCDF4 import __doc__
5 from ._netCDF4 import (__version__, __netcdf4libversion__, __hdf5libversion__,
6 __has_rename_grp__, __has_nc_inq_path__,
7 __has_nc_inq_format_extended__, __has_nc_open_mem__,
8 __has_nc_create_mem__, __has_cdf5_format__,
9 __has_parallel4_support__, __has_pnetcdf_support__)
10 __all__ =\
11 ['Dataset','Variable','Dimension','Group','MFDataset','MFTime','CompoundType','VLType','date2num','num2date','date2index','stringtochar','chartostring','stringtoarr','getlibversion','EnumType','get_chunk_cache','set_chunk_cache']
0 """
1 Version 1.5.6
2 -------------
3
4 # Introduction
5
6 netcdf4-python is a Python interface to the netCDF C library.
7
8 [netCDF](http://www.unidata.ucar.edu/software/netcdf/) version 4 has many features
9 not found in earlier versions of the library and is implemented on top of
10 [HDF5](http://www.hdfgroup.org/HDF5). This module can read and write
11 files in both the new netCDF 4 and the old netCDF 3 format, and can create
12 files that are readable by HDF5 clients. The API modelled after
13 [Scientific.IO.NetCDF](http://dirac.cnrs-orleans.fr/ScientificPython/),
14 and should be familiar to users of that module.
15
16 Most new features of netCDF 4 are implemented, such as multiple
17 unlimited dimensions, groups and zlib data compression. All the new
18 numeric data types (such as 64 bit and unsigned integer types) are
19 implemented. Compound (struct), variable length (vlen) and
20 enumerated (enum) data types are supported, but not the opaque data type.
21 Mixtures of compound, vlen and enum data types (such as
22 compound types containing enums, or vlens containing compound
23 types) are not supported.
24
25 ## Download
26
27 - Latest bleeding-edge code from the
28 [github repository](http://github.com/Unidata/netcdf4-python).
29 - Latest [releases](https://pypi.python.org/pypi/netCDF4)
30 (source code and binary installers).
31
32 ## Requires
33
34 - Python 3.6 or later.
35 - [numpy array module](http://numpy.scipy.org), version 1.10.0 or later.
36 - [Cython](http://cython.org), version 0.21 or later.
37 - [setuptools](https://pypi.python.org/pypi/setuptools), version 18.0 or
38 later.
39 - The HDF5 C library version 1.8.4-patch1 or higher
40 from [](ftp://ftp.hdfgroup.org/HDF5/current/src).
41 ***netCDF version 4.4.1 or higher is recommended if using HDF5 1.10.x -
42 otherwise resulting files may be unreadable by clients using earlier
43 versions of HDF5. For netCDF < 4.4.1, HDF5 version 1.8.x is recommended.***
44 Be sure to build with `--enable-hl --enable-shared`.
45 - [Libcurl](http://curl.haxx.se/libcurl), if you want
46 [OPeNDAP](http://opendap.org) support.
47 - [HDF4](http://www.hdfgroup.org/products/hdf4), if you want
48 to be able to read HDF4 "Scientific Dataset" (SD) files.
49 - The netCDF-4 C library from the [github releases
50 page](https://github.com/Unidata/netcdf-c/releases).
51 Version 4.1.1 or higher is required (4.2 or higher recommended).
52 Be sure to build with `--enable-netcdf-4 --enable-shared`, and set
53 `CPPFLAGS="-I $HDF5_DIR/include"` and `LDFLAGS="-L $HDF5_DIR/lib"`,
54 where `$HDF5_DIR` is the directory where HDF5 was installed.
55 If you want [OPeNDAP](http://opendap.org) support, add `--enable-dap`.
56 If you want HDF4 SD support, add `--enable-hdf4` and add
57 the location of the HDF4 headers and library to `$CPPFLAGS` and `$LDFLAGS`.
58 - for MPI parallel IO support, an MPI-enabled versions of the netcdf library
59 is required, as is the [mpi4py](http://mpi4py.scipy.org) python module.
60 Parallel IO further depends on the existence of MPI-enabled HDF5 or the
61 [PnetCDF](https://parallel-netcdf.github.io/) library.
62 - [cftime](https://github.com/Unidata/cftime) for
63 time and date handling utility functions.
64
65
66 ## Install
67
68 - install the requisite python modules and C libraries (see above). It's
69 easiest if all the C libs are built as shared libraries.
70 - By default, the utility `nc-config`, installed with netcdf 4.1.2 or higher,
71 will be run used to determine where all the dependencies live.
72 - If `nc-config` is not in your default `PATH`, you can set the `NETCDF4_DIR`
73 environment variable and `setup.py` will look in `$NETCDF4_DIR/bin`.
74 You can also use the file `setup.cfg` to set the path to `nc-config`, or
75 enter the paths to the libraries and include files manually. Just edit the `setup.cfg` file
76 in a text editor and follow the instructions in the comments.
77 To disable the use of `nc-config`, set the env var `USE_NCCONFIG` to 0.
78 To disable the use of `setup.cfg`, set `USE_SETUPCFG` to 0.
79 As a last resort, the library and include paths can be set via environment variables.
80 If you go this route, set `USE_NCCONFIG` and `USE_SETUPCFG` to 0, and specify
81 `NETCDF4_LIBDIR`, `NETCDF4_INCDIR`, `HDF5_LIBDIR` and `HDF5_INCDIR`.
82 Similarly, environment variables
83 (all capitalized) can be used to set the include and library paths for
84 `hdf4`, `szip`, `jpeg`, `curl` and `zlib`. If the dependencies are not found
85 in any of the paths specified by environment variables, then standard locations
86 (such as `/usr` and `/usr/local`) are searched.
87 - run `python setup.py build`, then `python setup.py install` (as root if
88 necessary). `pip install` can be used to install pre-compiled binary wheels from
89 [pypi](https://pypi.org/project/netCDF4).
90 - run the tests in the 'test' directory by running `python run_all.py`.
91
92 # Tutorial
93
94 - [Creating/Opening/Closing a netCDF file](#creatingopeningclosing-a-netcdf-file)
95 - [Groups in a netCDF file](#groups-in-a-netcdf-file)
96 - [Dimensions in a netCDF file](#dimensions-in-a-netcdf-file)
97 - [Variables in a netCDF file](#variables-in-a-netcdf-file)
98 - [Attributes in a netCDF file](#attributes-in-a-netcdf-file)
99 - [Dealing with time coordinates](#dealing-with-time-coordinates)
100 - [Writing data to and retrieving data from a netCDF variable](#writing-data-to-and-retrieving-data-from-a-netcdf-variable)
101 - [Reading data from a multi-file netCDF dataset](#reading-data-from-a-multi-file-netcdf-dataset)
102 - [Efficient compression of netCDF variables](#efficient-compression-of-netcdf-variables)
103 - [Beyond homogeneous arrays of a fixed type - compound data types](#beyond-homogeneous-arrays-of-a-fixed-type-compound-data-types)
104 - [Variable-length (vlen) data types](#variable-length-vlen-data-types)
105 - [Enum data type](#enum-data-type)
106 - [Parallel IO](#parallel-io)
107 - [Dealing with strings](#dealing-with-strings)
108 - [In-memory (diskless) Datasets](#in-memory-diskless-datasets)
109
110 ## Creating/Opening/Closing a netCDF file
111
112 To create a netCDF file from python, you simply call the [Dataset](#Dataset)
113 constructor. This is also the method used to open an existing netCDF
114 file. If the file is open for write access (`mode='w', 'r+'` or `'a'`), you may
115 write any type of data including new dimensions, groups, variables and
116 attributes. netCDF files come in five flavors (`NETCDF3_CLASSIC,
117 NETCDF3_64BIT_OFFSET, NETCDF3_64BIT_DATA, NETCDF4_CLASSIC`, and `NETCDF4`).
118 `NETCDF3_CLASSIC` was the original netcdf binary format, and was limited
119 to file sizes less than 2 Gb. `NETCDF3_64BIT_OFFSET` was introduced
120 in version 3.6.0 of the library, and extended the original binary format
121 to allow for file sizes greater than 2 Gb.
122 `NETCDF3_64BIT_DATA` is a new format that requires version 4.4.0 of
123 the C library - it extends the `NETCDF3_64BIT_OFFSET` binary format to
124 allow for unsigned/64 bit integer data types and 64-bit dimension sizes.
125 `NETCDF3_64BIT` is an alias for `NETCDF3_64BIT_OFFSET`.
126 `NETCDF4_CLASSIC` files use the version 4 disk format (HDF5), but omits features
127 not found in the version 3 API. They can be read by netCDF 3 clients
128 only if they have been relinked against the netCDF 4 library. They can
129 also be read by HDF5 clients. `NETCDF4` files use the version 4 disk
130 format (HDF5) and use the new features of the version 4 API. The
131 netCDF4 module can read and write files in any of these formats. When
132 creating a new file, the format may be specified using the `format`
133 keyword in the `Dataset` constructor. The default format is
134 `NETCDF4`. To see how a given file is formatted, you can examine the
135 `data_model` attribute. Closing the netCDF file is
136 accomplished via the [Dataset.close](#Dataset.close) method of the [Dataset](#Dataset)
137 instance.
138
139 Here's an example:
140
141 ```python
142 >>> from netCDF4 import Dataset
143 >>> rootgrp = Dataset("test.nc", "w", format="NETCDF4")
144 >>> print(rootgrp.data_model)
145 NETCDF4
146 >>> rootgrp.close()
147 ```
148
149 Remote [OPeNDAP](http://opendap.org)-hosted datasets can be accessed for
150 reading over http if a URL is provided to the [Dataset](#Dataset) constructor instead of a
151 filename. However, this requires that the netCDF library be built with
152 OPenDAP support, via the `--enable-dap` configure option (added in
153 version 4.0.1).
154
155
156 ## Groups in a netCDF file
157
158 netCDF version 4 added support for organizing data in hierarchical
159 groups, which are analogous to directories in a filesystem. Groups serve
160 as containers for variables, dimensions and attributes, as well as other
161 groups. A [Dataset](#Dataset) creates a special group, called
162 the 'root group', which is similar to the root directory in a unix
163 filesystem. To create [Group](#Group) instances, use the
164 [Dataset.createGroup](#Dataset.createGroup) method of a [Dataset](#Dataset) or [Group](#Group)
165 instance. [Dataset.createGroup](#Dataset.createGroup) takes a single argument, a
166 python string containing the name of the new group. The new [Group](#Group)
167 instances contained within the root group can be accessed by name using
168 the `groups` dictionary attribute of the [Dataset](#Dataset) instance. Only
169 `NETCDF4` formatted files support Groups, if you try to create a Group
170 in a netCDF 3 file you will get an error message.
171
172 ```python
173 >>> rootgrp = Dataset("test.nc", "a")
174 >>> fcstgrp = rootgrp.createGroup("forecasts")
175 >>> analgrp = rootgrp.createGroup("analyses")
176 >>> print(rootgrp.groups)
177 {'forecasts': <class 'netCDF4._netCDF4.Group'>
178 group /forecasts:
179 dimensions(sizes):
180 variables(dimensions):
181 groups: , 'analyses': <class 'netCDF4._netCDF4.Group'>
182 group /analyses:
183 dimensions(sizes):
184 variables(dimensions):
185 groups: }
186 >>>
187 ```
188
189 Groups can exist within groups in a [Dataset](#Dataset), just as directories
190 exist within directories in a unix filesystem. Each [Group](#Group) instance
191 has a `groups` attribute dictionary containing all of the group
192 instances contained within that group. Each [Group](#Group) instance also has a
193 `path` attribute that contains a simulated unix directory path to
194 that group. To simplify the creation of nested groups, you can
195 use a unix-like path as an argument to [Dataset.createGroup](#Dataset.createGroup).
196
197 ```python
198 >>> fcstgrp1 = rootgrp.createGroup("/forecasts/model1")
199 >>> fcstgrp2 = rootgrp.createGroup("/forecasts/model2")
200 ```
201
202 If any of the intermediate elements of the path do not exist, they are created,
203 just as with the unix command `'mkdir -p'`. If you try to create a group
204 that already exists, no error will be raised, and the existing group will be
205 returned.
206
207 Here's an example that shows how to navigate all the groups in a
208 [Dataset](#Dataset). The function `walktree` is a Python generator that is used
209 to walk the directory tree. Note that printing the [Dataset](#Dataset) or [Group](#Group)
210 object yields summary information about it's contents.
211
212 ```python
213 >>> def walktree(top):
214 ... values = top.groups.values()
215 ... yield values
216 ... for value in top.groups.values():
217 ... for children in walktree(value):
218 ... yield children
219 >>> print(rootgrp)
220 <class 'netCDF4._netCDF4.Dataset'>
221 root group (NETCDF4 data model, file format HDF5):
222 dimensions(sizes):
223 variables(dimensions):
224 groups: forecasts, analyses
225 >>> for children in walktree(rootgrp):
226 ... for child in children:
227 ... print(child)
228 <class 'netCDF4._netCDF4.Group'>
229 group /forecasts:
230 dimensions(sizes):
231 variables(dimensions):
232 groups: model1, model2
233 <class 'netCDF4._netCDF4.Group'>
234 group /analyses:
235 dimensions(sizes):
236 variables(dimensions):
237 groups:
238 <class 'netCDF4._netCDF4.Group'>
239 group /forecasts/model1:
240 dimensions(sizes):
241 variables(dimensions):
242 groups:
243 <class 'netCDF4._netCDF4.Group'>
244 group /forecasts/model2:
245 dimensions(sizes):
246 variables(dimensions):
247 groups:
248 ```
249
250 ## Dimensions in a netCDF file
251
252 netCDF defines the sizes of all variables in terms of dimensions, so
253 before any variables can be created the dimensions they use must be
254 created first. A special case, not often used in practice, is that of a
255 scalar variable, which has no dimensions. A dimension is created using
256 the [Dataset.createDimension](#Dataset.createDimension) method of a [Dataset](#Dataset)
257 or [Group](#Group) instance. A Python string is used to set the name of the
258 dimension, and an integer value is used to set the size. To create an
259 unlimited dimension (a dimension that can be appended to), the size
260 value is set to `None` or 0. In this example, there both the `time` and
261 `level` dimensions are unlimited. Having more than one unlimited
262 dimension is a new netCDF 4 feature, in netCDF 3 files there may be only
263 one, and it must be the first (leftmost) dimension of the variable.
264
265 ```python
266 >>> level = rootgrp.createDimension("level", None)
267 >>> time = rootgrp.createDimension("time", None)
268 >>> lat = rootgrp.createDimension("lat", 73)
269 >>> lon = rootgrp.createDimension("lon", 144)
270 ```
271
272
273 All of the [Dimension](#Dimension) instances are stored in a python dictionary.
274
275 ```python
276 >>> print(rootgrp.dimensions)
277 {'level': <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'level', size = 0, 'time': <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'time', size = 0, 'lat': <class 'netCDF4._netCDF4.Dimension'>: name = 'lat', size = 73, 'lon': <class 'netCDF4._netCDF4.Dimension'>: name = 'lon', size = 144}
278 ```
279
280 Using the python `len` function with a [Dimension](#Dimension) instance returns
281 current size of that dimension.
282 [Dimension.isunlimited](#Dimension.isunlimited) method of a [Dimension](#Dimension) instance
283 be used to determine if the dimensions is unlimited, or appendable.
284
285 ```python
286 >>> print(len(lon))
287 144
288 >>> print(lon.isunlimited())
289 False
290 >>> print(time.isunlimited())
291 True
292 ```
293
294 Printing the [Dimension](#Dimension) object
295 provides useful summary info, including the name and length of the dimension,
296 and whether it is unlimited.
297
298 ```python
299 >>> for dimobj in rootgrp.dimensions.values():
300 ... print(dimobj)
301 <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'level', size = 0
302 <class 'netCDF4._netCDF4.Dimension'> (unlimited): name = 'time', size = 0
303 <class 'netCDF4._netCDF4.Dimension'>: name = 'lat', size = 73
304 <class 'netCDF4._netCDF4.Dimension'>: name = 'lon', size = 144
305 ```
306
307 [Dimension](#Dimension) names can be changed using the
308 [Datatset.renameDimension](#Datatset.renameDimension) method of a [Dataset](#Dataset) or
309 [Group](#Group) instance.
310
311 ## Variables in a netCDF file
312
313 netCDF variables behave much like python multidimensional array objects
314 supplied by the [numpy module](http://numpy.scipy.org). However,
315 unlike numpy arrays, netCDF4 variables can be appended to along one or
316 more 'unlimited' dimensions. To create a netCDF variable, use the
317 [Dataset.createVariable](#Dataset.createVariable) method of a [Dataset](#Dataset) or
318 [Group](#Group) instance. The [Dataset.createVariable](#Dataset.createVariable) method
319 has two mandatory arguments, the variable name (a Python string), and
320 the variable datatype. The variable's dimensions are given by a tuple
321 containing the dimension names (defined previously with
322 [Dataset.createDimension](#Dataset.createDimension)). To create a scalar
323 variable, simply leave out the dimensions keyword. The variable
324 primitive datatypes correspond to the dtype attribute of a numpy array.
325 You can specify the datatype as a numpy dtype object, or anything that
326 can be converted to a numpy dtype object. Valid datatype specifiers
327 include: `'f4'` (32-bit floating point), `'f8'` (64-bit floating
328 point), `'i4'` (32-bit signed integer), `'i2'` (16-bit signed
329 integer), `'i8'` (64-bit signed integer), `'i1'` (8-bit signed
330 integer), `'u1'` (8-bit unsigned integer), `'u2'` (16-bit unsigned
331 integer), `'u4'` (32-bit unsigned integer), `'u8'` (64-bit unsigned
332 integer), or `'S1'` (single-character string). The old Numeric
333 single-character typecodes (`'f'`,`'d'`,`'h'`,
334 `'s'`,`'b'`,`'B'`,`'c'`,`'i'`,`'l'`), corresponding to
335 (`'f4'`,`'f8'`,`'i2'`,`'i2'`,`'i1'`,`'i1'`,`'S1'`,`'i4'`,`'i4'`),
336 will also work. The unsigned integer types and the 64-bit integer type
337 can only be used if the file format is `NETCDF4`.
338
339 The dimensions themselves are usually also defined as variables, called
340 coordinate variables. The [Dataset.createVariable](#Dataset.createVariable)
341 method returns an instance of the [Variable](#Variable) class whose methods can be
342 used later to access and set variable data and attributes.
343
344 ```python
345 >>> times = rootgrp.createVariable("time","f8",("time",))
346 >>> levels = rootgrp.createVariable("level","i4",("level",))
347 >>> latitudes = rootgrp.createVariable("lat","f4",("lat",))
348 >>> longitudes = rootgrp.createVariable("lon","f4",("lon",))
349 >>> # two dimensions unlimited
350 >>> temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",))
351 >>> temp.units = "K"
352 ```
353
354 To get summary info on a [Variable](#Variable) instance in an interactive session,
355 just print it.
356
357 ```python
358 >>> print(temp)
359 <class 'netCDF4._netCDF4.Variable'>
360 float32 temp(time, level, lat, lon)
361 units: K
362 unlimited dimensions: time, level
363 current shape = (0, 0, 73, 144)
364 filling on, default _FillValue of 9.969209968386869e+36 used
365 ```
366
367 You can use a path to create a Variable inside a hierarchy of groups.
368
369 ```python
370 >>> ftemp = rootgrp.createVariable("/forecasts/model1/temp","f4",("time","level","lat","lon",))
371 ```
372
373 If the intermediate groups do not yet exist, they will be created.
374
375 You can also query a [Dataset](#Dataset) or [Group](#Group) instance directly to obtain [Group](#Group) or
376 [Variable](#Variable) instances using paths.
377
378 ```python
379 >>> print(rootgrp["/forecasts/model1"]) # a Group instance
380 <class 'netCDF4._netCDF4.Group'>
381 group /forecasts/model1:
382 dimensions(sizes):
383 variables(dimensions): float32 temp(time,level,lat,lon)
384 groups:
385 >>> print(rootgrp["/forecasts/model1/temp"]) # a Variable instance
386 <class 'netCDF4._netCDF4.Variable'>
387 float32 temp(time, level, lat, lon)
388 path = /forecasts/model1
389 unlimited dimensions: time, level
390 current shape = (0, 0, 73, 144)
391 filling on, default _FillValue of 9.969209968386869e+36 used
392 ```
393
394
395 All of the variables in the [Dataset](#Dataset) or [Group](#Group) are stored in a
396 Python dictionary, in the same way as the dimensions:
397
398 ```python
399 >>> print(rootgrp.variables)
400 {'time': <class 'netCDF4._netCDF4.Variable'>
401 float64 time(time)
402 unlimited dimensions: time
403 current shape = (0,)
404 filling on, default _FillValue of 9.969209968386869e+36 used, 'level': <class 'netCDF4._netCDF4.Variable'>
405 int32 level(level)
406 unlimited dimensions: level
407 current shape = (0,)
408 filling on, default _FillValue of -2147483647 used, 'lat': <class 'netCDF4._netCDF4.Variable'>
409 float32 lat(lat)
410 unlimited dimensions:
411 current shape = (73,)
412 filling on, default _FillValue of 9.969209968386869e+36 used, 'lon': <class 'netCDF4._netCDF4.Variable'>
413 float32 lon(lon)
414 unlimited dimensions:
415 current shape = (144,)
416 filling on, default _FillValue of 9.969209968386869e+36 used, 'temp': <class 'netCDF4._netCDF4.Variable'>
417 float32 temp(time, level, lat, lon)
418 units: K
419 unlimited dimensions: time, level
420 current shape = (0, 0, 73, 144)
421 filling on, default _FillValue of 9.969209968386869e+36 used}
422 ```
423
424 [Variable](#Variable) names can be changed using the
425 [Dataset.renameVariable](#Dataset.renameVariable) method of a [Dataset](#Dataset)
426 instance.
427
428 Variables can be sliced similar to numpy arrays, but there are some differences. See
429 [Writing data to and retrieving data from a netCDF variable](#writing-data-to-and-retrieving-data-from-a-netcdf-variable) for more details.
430
431
432 ## Attributes in a netCDF file
433
434 There are two types of attributes in a netCDF file, global and variable.
435 Global attributes provide information about a group, or the entire
436 dataset, as a whole. [Variable](#Variable) attributes provide information about
437 one of the variables in a group. Global attributes are set by assigning
438 values to [Dataset](#Dataset) or [Group](#Group) instance variables. [Variable](#Variable)
439 attributes are set by assigning values to [Variable](#Variable) instances
440 variables. Attributes can be strings, numbers or sequences. Returning to
441 our example,
442
443 ```python
444 >>> import time
445 >>> rootgrp.description = "bogus example script"
446 >>> rootgrp.history = "Created " + time.ctime(time.time())
447 >>> rootgrp.source = "netCDF4 python module tutorial"
448 >>> latitudes.units = "degrees north"
449 >>> longitudes.units = "degrees east"
450 >>> levels.units = "hPa"
451 >>> temp.units = "K"
452 >>> times.units = "hours since 0001-01-01 00:00:00.0"
453 >>> times.calendar = "gregorian"
454 ```
455
456 The [Dataset.ncattrs](#Dataset.ncattrs) method of a [Dataset](#Dataset), [Group](#Group) or
457 [Variable](#Variable) instance can be used to retrieve the names of all the netCDF
458 attributes. This method is provided as a convenience, since using the
459 built-in `dir` Python function will return a bunch of private methods
460 and attributes that cannot (or should not) be modified by the user.
461
462 ```python
463 >>> for name in rootgrp.ncattrs():
464 ... print("Global attr {} = {}".format(name, getattr(rootgrp, name)))
465 Global attr description = bogus example script
466 Global attr history = Created Mon Jul 8 14:19:41 2019
467 Global attr source = netCDF4 python module tutorial
468 ```
469
470 The `__dict__` attribute of a [Dataset](#Dataset), [Group](#Group) or [Variable](#Variable)
471 instance provides all the netCDF attribute name/value pairs in a python
472 dictionary:
473
474 ```python
475 >>> print(rootgrp.__dict__)
476 {'description': 'bogus example script', 'history': 'Created Mon Jul 8 14:19:41 2019', 'source': 'netCDF4 python module tutorial'}
477 ```
478
479 Attributes can be deleted from a netCDF [Dataset](#Dataset), [Group](#Group) or
480 [Variable](#Variable) using the python `del` statement (i.e. `del grp.foo`
481 removes the attribute `foo` the the group `grp`).
482
483 ## Writing data to and retrieving data from a netCDF variable
484
485 Now that you have a netCDF [Variable](#Variable) instance, how do you put data
486 into it? You can just treat it like an array and assign data to a slice.
487
488 ```python
489 >>> import numpy
490 >>> lats = numpy.arange(-90,91,2.5)
491 >>> lons = numpy.arange(-180,180,2.5)
492 >>> latitudes[:] = lats
493 >>> longitudes[:] = lons
494 >>> print("latitudes =\\n{}".format(latitudes[:]))
495 latitudes =
496 [-90. -87.5 -85. -82.5 -80. -77.5 -75. -72.5 -70. -67.5 -65. -62.5
497 -60. -57.5 -55. -52.5 -50. -47.5 -45. -42.5 -40. -37.5 -35. -32.5
498 -30. -27.5 -25. -22.5 -20. -17.5 -15. -12.5 -10. -7.5 -5. -2.5
499 0. 2.5 5. 7.5 10. 12.5 15. 17.5 20. 22.5 25. 27.5
500 30. 32.5 35. 37.5 40. 42.5 45. 47.5 50. 52.5 55. 57.5
501 60. 62.5 65. 67.5 70. 72.5 75. 77.5 80. 82.5 85. 87.5
502 90. ]
503 ```
504
505 Unlike NumPy's array objects, netCDF [Variable](#Variable)
506 objects with unlimited dimensions will grow along those dimensions if you
507 assign data outside the currently defined range of indices.
508
509 ```python
510 >>> # append along two unlimited dimensions by assigning to slice.
511 >>> nlats = len(rootgrp.dimensions["lat"])
512 >>> nlons = len(rootgrp.dimensions["lon"])
513 >>> print("temp shape before adding data = {}".format(temp.shape))
514 temp shape before adding data = (0, 0, 73, 144)
515 >>>
516 >>> from numpy.random import uniform
517 >>> temp[0:5, 0:10, :, :] = uniform(size=(5, 10, nlats, nlons))
518 >>> print("temp shape after adding data = {}".format(temp.shape))
519 temp shape after adding data = (5, 10, 73, 144)
520 >>>
521 >>> # levels have grown, but no values yet assigned.
522 >>> print("levels shape after adding pressure data = {}".format(levels.shape))
523 levels shape after adding pressure data = (10,)
524 ```
525
526 Note that the size of the levels variable grows when data is appended
527 along the `level` dimension of the variable `temp`, even though no
528 data has yet been assigned to levels.
529
530 ```python
531 >>> # now, assign data to levels dimension variable.
532 >>> levels[:] = [1000.,850.,700.,500.,300.,250.,200.,150.,100.,50.]
533 ```
534
535 However, that there are some differences between NumPy and netCDF
536 variable slicing rules. Slices behave as usual, being specified as a
537 `start:stop:step` triplet. Using a scalar integer index `i` takes the ith
538 element and reduces the rank of the output array by one. Boolean array and
539 integer sequence indexing behaves differently for netCDF variables
540 than for numpy arrays. Only 1-d boolean arrays and integer sequences are
541 allowed, and these indices work independently along each dimension (similar
542 to the way vector subscripts work in fortran). This means that
543
544 ```python
545 >>> temp[0, 0, [0,1,2,3], [0,1,2,3]].shape
546 (4, 4)
547 ```
548
549 returns an array of shape (4,4) when slicing a netCDF variable, but for a
550 numpy array it returns an array of shape (4,).
551 Similarly, a netCDF variable of shape `(2,3,4,5)` indexed
552 with `[0, array([True, False, True]), array([False, True, True, True]), :]`
553 would return a `(2, 3, 5)` array. In NumPy, this would raise an error since
554 it would be equivalent to `[0, [0,1], [1,2,3], :]`. When slicing with integer
555 sequences, the indices ***need not be sorted*** and ***may contain
556 duplicates*** (both of these are new features in version 1.2.1).
557 While this behaviour may cause some confusion for those used to NumPy's 'fancy indexing' rules,
558 it provides a very powerful way to extract data from multidimensional netCDF
559 variables by using logical operations on the dimension arrays to create slices.
560
561 For example,
562
563 ```python
564 >>> tempdat = temp[::2, [1,3,6], lats>0, lons>0]
565 ```
566
567 will extract time indices 0,2 and 4, pressure levels
568 850, 500 and 200 hPa, all Northern Hemisphere latitudes and Eastern
569 Hemisphere longitudes, resulting in a numpy array of shape (3, 3, 36, 71).
570
571 ```python
572 >>> print("shape of fancy temp slice = {}".format(tempdat.shape))
573 shape of fancy temp slice = (3, 3, 36, 71)
574 ```
575
576 ***Special note for scalar variables***: To extract data from a scalar variable
577 `v` with no associated dimensions, use `numpy.asarray(v)` or `v[...]`.
578 The result will be a numpy scalar array.
579
580 By default, netcdf4-python returns numpy masked arrays with values equal to the
581 `missing_value` or `_FillValue` variable attributes masked. The
582 [Dataset.set_auto_mask](#Dataset.set_auto_mask) [Dataset](#Dataset) and [Variable](#Variable) methods
583 can be used to disable this feature so that
584 numpy arrays are always returned, with the missing values included. Prior to
585 version 1.4.0 the default behavior was to only return masked arrays when the
586 requested slice contained missing values. This behavior can be recovered
587 using the [Dataset.set_always_mask](#Dataset.set_always_mask) method. If a masked array is
588 written to a netCDF variable, the masked elements are filled with the
589 value specified by the `missing_value` attribute. If the variable has
590 no `missing_value`, the `_FillValue` is used instead.
591
592 ## Dealing with time coordinates
593
594 Time coordinate values pose a special challenge to netCDF users. Most
595 metadata standards (such as CF) specify that time should be
596 measure relative to a fixed date using a certain calendar, with units
597 specified like `hours since YY-MM-DD hh:mm:ss`. These units can be
598 awkward to deal with, without a utility to convert the values to and
599 from calendar dates. The functions [num2date](https://unidata.github.io/cftime/api.html)
600 and [date2num](https://unidata.github.io/cftime/api.html) are
601 provided by [cftime](https://unidata.github.io/cftime) to do just that.
602 Here's an example of how they can be used:
603
604 ```python
605 >>> # fill in times.
606 >>> from datetime import datetime, timedelta
607 >>> from cftime import num2date, date2num
608 >>> dates = [datetime(2001,3,1)+n*timedelta(hours=12) for n in range(temp.shape[0])]
609 >>> times[:] = date2num(dates,units=times.units,calendar=times.calendar)
610 >>> print("time values (in units {}):\\n{}".format(times.units, times[:]))
611 time values (in units hours since 0001-01-01 00:00:00.0):
612 [17533104. 17533116. 17533128. 17533140. 17533152.]
613 >>> dates = num2date(times[:],units=times.units,calendar=times.calendar)
614 >>> print("dates corresponding to time values:\\n{}".format(dates))
615 dates corresponding to time values:
616 [real_datetime(2001, 3, 1, 0, 0) real_datetime(2001, 3, 1, 12, 0)
617 real_datetime(2001, 3, 2, 0, 0) real_datetime(2001, 3, 2, 12, 0)
618 real_datetime(2001, 3, 3, 0, 0)]
619 ```
620
621 `num2date` converts numeric values of time in the specified `units`
622 and `calendar` to datetime objects, and `date2num` does the reverse.
623 All the calendars currently defined in the
624 [CF metadata convention](http://cfconventions.org) are supported.
625 A function called `date2index` is also provided which returns the indices
626 of a netCDF time variable corresponding to a sequence of datetime instances.
627
628
629 ## Reading data from a multi-file netCDF dataset
630
631 If you want to read data from a variable that spans multiple netCDF files,
632 you can use the [MFDataset](#MFDataset) class to read the data as if it were
633 contained in a single file. Instead of using a single filename to create
634 a [Dataset](#Dataset) instance, create a [MFDataset](#MFDataset) instance with either a list
635 of filenames, or a string with a wildcard (which is then converted to
636 a sorted list of files using the python glob module).
637 Variables in the list of files that share the same unlimited
638 dimension are aggregated together, and can be sliced across multiple
639 files. To illustrate this, let's first create a bunch of netCDF files with
640 the same variable (with the same unlimited dimension). The files
641 must in be in `NETCDF3_64BIT_OFFSET`, `NETCDF3_64BIT_DATA`, `NETCDF3_CLASSIC` or
642 `NETCDF4_CLASSIC` format (`NETCDF4` formatted multi-file
643 datasets are not supported).
644
645 ```python
646 >>> for nf in range(10):
647 ... with Dataset("mftest%s.nc" % nf, "w", format="NETCDF4_CLASSIC") as f:
648 ... _ = f.createDimension("x",None)
649 ... x = f.createVariable("x","i",("x",))
650 ... x[0:10] = numpy.arange(nf*10,10*(nf+1))
651 ```
652
653 Now read all the files back in at once with [MFDataset](#MFDataset)
654
655 ```python
656 >>> from netCDF4 import MFDataset
657 >>> f = MFDataset("mftest*nc")
658 >>> print(f.variables["x"][:])
659 [ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
660 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
661 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
662 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
663 96 97 98 99]
664 ```
665
666 Note that [MFDataset](#MFDataset) can only be used to read, not write, multi-file
667 datasets.
668
669 ## Efficient compression of netCDF variables
670
671 Data stored in netCDF 4 [Variable](#Variable) objects can be compressed and
672 decompressed on the fly. The parameters for the compression are
673 determined by the `zlib`, `complevel` and `shuffle` keyword arguments
674 to the [Dataset.createVariable](#Dataset.createVariable) method. To turn on
675 compression, set `zlib=True`. The `complevel` keyword regulates the
676 speed and efficiency of the compression (1 being fastest, but lowest
677 compression ratio, 9 being slowest but best compression ratio). The
678 default value of `complevel` is 4. Setting `shuffle=False` will turn
679 off the HDF5 shuffle filter, which de-interlaces a block of data before
680 compression by reordering the bytes. The shuffle filter can
681 significantly improve compression ratios, and is on by default. Setting
682 `fletcher32` keyword argument to
683 [Dataset.createVariable](#Dataset.createVariable) to `True` (it's `False` by
684 default) enables the Fletcher32 checksum algorithm for error detection.
685 It's also possible to set the HDF5 chunking parameters and endian-ness
686 of the binary data stored in the HDF5 file with the `chunksizes`
687 and `endian` keyword arguments to
688 [Dataset.createVariable](#Dataset.createVariable). These keyword arguments only
689 are relevant for `NETCDF4` and `NETCDF4_CLASSIC` files (where the
690 underlying file format is HDF5) and are silently ignored if the file
691 format is `NETCDF3_CLASSIC`, `NETCDF3_64BIT_OFFSET` or `NETCDF3_64BIT_DATA`.
692
693 If your data only has a certain number of digits of precision (say for
694 example, it is temperature data that was measured with a precision of
695 0.1 degrees), you can dramatically improve zlib compression by
696 quantizing (or truncating) the data using the `least_significant_digit`
697 keyword argument to [Dataset.createVariable](#Dataset.createVariable). The least
698 significant digit is the power of ten of the smallest decimal place in
699 the data that is a reliable value. For example if the data has a
700 precision of 0.1, then setting `least_significant_digit=1` will cause
701 data the data to be quantized using `numpy.around(scale*data)/scale`, where
702 scale = 2**bits, and bits is determined so that a precision of 0.1 is
703 retained (in this case bits=4). Effectively, this makes the compression
704 'lossy' instead of 'lossless', that is some precision in the data is
705 sacrificed for the sake of disk space.
706
707 In our example, try replacing the line
708
709 ```python
710 >>> temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",))
711
712 with
713
714 ```python
715 >>> temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",),zlib=True)
716 ```
717
718 and then
719
720 ```python
721 >>> temp = rootgrp.createVariable("temp","f4",("time","level","lat","lon",),zlib=True,least_significant_digit=3)
722 ```
723
724 and see how much smaller the resulting files are.
725
726 ## Beyond homogeneous arrays of a fixed type - compound data types
727
728 Compound data types map directly to numpy structured (a.k.a 'record')
729 arrays. Structured arrays are akin to C structs, or derived types
730 in Fortran. They allow for the construction of table-like structures
731 composed of combinations of other data types, including other
732 compound types. Compound types might be useful for representing multiple
733 parameter values at each point on a grid, or at each time and space
734 location for scattered (point) data. You can then access all the
735 information for a point by reading one variable, instead of reading
736 different parameters from different variables. Compound data types
737 are created from the corresponding numpy data type using the
738 [Dataset.createCompoundType](#Dataset.createCompoundType) method of a [Dataset](#Dataset) or [Group](#Group) instance.
739 Since there is no native complex data type in netcdf, compound types are handy
740 for storing numpy complex arrays. Here's an example:
741
742 ```python
743 >>> f = Dataset("complex.nc","w")
744 >>> size = 3 # length of 1-d complex array
745 >>> # create sample complex data.
746 >>> datac = numpy.exp(1j*(1.+numpy.linspace(0, numpy.pi, size)))
747 >>> # create complex128 compound data type.
748 >>> complex128 = numpy.dtype([("real",numpy.float_64),("imag",numpy.float_64)])
749 >>> complex128_t = f.createCompoundType(complex128,"complex128")
750 >>> # create a variable with this data type, write some data to it.
751 >>> x_dim = f.createDimension("x_dim",None)
752 >>> v = f.createVariable("cmplx_var",complex128_t,"x_dim")
753 >>> data = numpy.empty(size,complex128) # numpy structured array
754 >>> data["real"] = datac.real; data["imag"] = datac.imag
755 >>> v[:] = data # write numpy structured array to netcdf compound var
756 >>> # close and reopen the file, check the contents.
757 >>> f.close(); f = Dataset("complex.nc")
758 >>> v = f.variables["cmplx_var"]
759 >>> datain = v[:] # read in all the data into a numpy structured array
760 >>> # create an empty numpy complex array
761 >>> datac2 = numpy.empty(datain.shape,numpy.complex128)
762 >>> # .. fill it with contents of structured array.
763 >>> datac2.real = datain["real"]; datac2.imag = datain["imag"]
764 >>> print('{}: {}'.format(datac.dtype, datac)) # original data
765 complex128: [ 0.54030231+0.84147098j -0.84147098+0.54030231j -0.54030231-0.84147098j]
766 >>>
767 >>> print('{}: {}'.format(datac2.dtype, datac2)) # data from file
768 complex128: [ 0.54030231+0.84147098j -0.84147098+0.54030231j -0.54030231-0.84147098j]
769 ```
770
771 Compound types can be nested, but you must create the 'inner'
772 ones first. All possible numpy structured arrays cannot be
773 represented as Compound variables - an error message will be
774 raise if you try to create one that is not supported.
775 All of the compound types defined for a [Dataset](#Dataset) or [Group](#Group) are stored
776 in a Python dictionary, just like variables and dimensions. As always, printing
777 objects gives useful summary information in an interactive session:
778
779 ```python
780 >>> print(f)
781 <class 'netCDF4._netCDF4.Dataset'>
782 root group (NETCDF4 data model, file format HDF5):
783 dimensions(sizes): x_dim(3)
784 variables(dimensions): {'names':['real','imag'], 'formats':['<f8','<f8'], 'offsets':[0,8], 'itemsize':16, 'aligned':True} cmplx_var(x_dim)
785 groups:
786 >>> print(f.variables["cmplx_var"])
787 <class 'netCDF4._netCDF4.Variable'>
788 compound cmplx_var(x_dim)
789 compound data type: {'names':['real','imag'], 'formats':['<f8','<f8'], 'offsets':[0,8], 'itemsize':16, 'aligned':True}
790 unlimited dimensions: x_dim
791 current shape = (3,)
792 >>> print(f.cmptypes)
793 {'complex128': <class 'netCDF4._netCDF4.CompoundType'>: name = 'complex128', numpy dtype = {'names':['real','imag'], 'formats':['<f8','<f8'], 'offsets':[0,8], 'itemsize':16, 'aligned':True}}
794 >>> print(f.cmptypes["complex128"])
795 <class 'netCDF4._netCDF4.CompoundType'>: name = 'complex128', numpy dtype = {'names':['real','imag'], 'formats':['<f8','<f8'], 'offsets':[0,8], 'itemsize':16, 'aligned':True}
796 ```
797
798 ## Variable-length (vlen) data types
799
800 NetCDF 4 has support for variable-length or "ragged" arrays. These are arrays
801 of variable length sequences having the same type. To create a variable-length
802 data type, use the [Dataset.createVLType](#Dataset.createVLType) method
803 method of a [Dataset](#Dataset) or [Group](#Group) instance.
804
805 ```python
806 >>> f = Dataset("tst_vlen.nc","w")
807 >>> vlen_t = f.createVLType(numpy.int32, "phony_vlen")
808 ```
809
810 The numpy datatype of the variable-length sequences and the name of the
811 new datatype must be specified. Any of the primitive datatypes can be
812 used (signed and unsigned integers, 32 and 64 bit floats, and characters),
813 but compound data types cannot.
814 A new variable can then be created using this datatype.
815
816 ```python
817 >>> x = f.createDimension("x",3)
818 >>> y = f.createDimension("y",4)
819 >>> vlvar = f.createVariable("phony_vlen_var", vlen_t, ("y","x"))
820 ```
821
822 Since there is no native vlen datatype in numpy, vlen arrays are represented
823 in python as object arrays (arrays of dtype `object`). These are arrays whose
824 elements are Python object pointers, and can contain any type of python object.
825 For this application, they must contain 1-D numpy arrays all of the same type
826 but of varying length.
827 In this case, they contain 1-D numpy `int32` arrays of random length between
828 1 and 10.
829
830 ```python
831 >>> import random
832 >>> random.seed(54321)
833 >>> data = numpy.empty(len(y)*len(x),object)
834 >>> for n in range(len(y)*len(x)):
835 ... data[n] = numpy.arange(random.randint(1,10),dtype="int32")+1
836 >>> data = numpy.reshape(data,(len(y),len(x)))
837 >>> vlvar[:] = data
838 >>> print("vlen variable =\\n{}".format(vlvar[:]))
839 vlen variable =
840 [[array([1, 2, 3, 4, 5, 6, 7, 8], dtype=int32) array([1, 2], dtype=int32)
841 array([1, 2, 3, 4], dtype=int32)]
842 [array([1, 2, 3], dtype=int32)
843 array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=int32)
844 array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=int32)]
845 [array([1, 2, 3, 4, 5, 6, 7], dtype=int32) array([1, 2, 3], dtype=int32)
846 array([1, 2, 3, 4, 5, 6], dtype=int32)]
847 [array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=int32)
848 array([1, 2, 3, 4, 5], dtype=int32) array([1, 2], dtype=int32)]]
849 >>> print(f)
850 <class 'netCDF4._netCDF4.Dataset'>
851 root group (NETCDF4 data model, file format HDF5):
852 dimensions(sizes): x(3), y(4)
853 variables(dimensions): int32 phony_vlen_var(y,x)
854 groups:
855 >>> print(f.variables["phony_vlen_var"])
856 <class 'netCDF4._netCDF4.Variable'>
857 vlen phony_vlen_var(y, x)
858 vlen data type: int32
859 unlimited dimensions:
860 current shape = (4, 3)
861 >>> print(f.vltypes["phony_vlen"])
862 <class 'netCDF4._netCDF4.VLType'>: name = 'phony_vlen', numpy dtype = int32
863 ```
864
865 Numpy object arrays containing python strings can also be written as vlen
866 variables, For vlen strings, you don't need to create a vlen data type.
867 Instead, simply use the python `str` builtin (or a numpy string datatype
868 with fixed length greater than 1) when calling the
869 [Dataset.createVariable](#Dataset.createVariable) method.
870
871 ```python
872 >>> z = f.createDimension("z",10)
873 >>> strvar = f.createVariable("strvar", str, "z")
874 ```
875
876 In this example, an object array is filled with random python strings with
877 random lengths between 2 and 12 characters, and the data in the object
878 array is assigned to the vlen string variable.
879
880 ```python
881 >>> chars = "1234567890aabcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
882 >>> data = numpy.empty(10,"O")
883 >>> for n in range(10):
884 ... stringlen = random.randint(2,12)
885 ... data[n] = "".join([random.choice(chars) for i in range(stringlen)])
886 >>> strvar[:] = data
887 >>> print("variable-length string variable:\\n{}".format(strvar[:]))
888 variable-length string variable:
889 ['Lh' '25F8wBbMI' '53rmM' 'vvjnb3t63ao' 'qjRBQk6w' 'aJh' 'QF'
890 'jtIJbJACaQk4' '3Z5' 'bftIIq']
891 >>> print(f)
892 <class 'netCDF4._netCDF4.Dataset'>
893 root group (NETCDF4 data model, file format HDF5):
894 dimensions(sizes): x(3), y(4), z(10)
895 variables(dimensions): int32 phony_vlen_var(y,x), <class 'str'> strvar(z)
896 groups:
897 >>> print(f.variables["strvar"])
898 <class 'netCDF4._netCDF4.Variable'>
899 vlen strvar(z)
900 vlen data type: <class 'str'>
901 unlimited dimensions:
902 current shape = (10,)
903 ```
904
905 It is also possible to set contents of vlen string variables with numpy arrays
906 of any string or unicode data type. Note, however, that accessing the contents
907 of such variables will always return numpy arrays with dtype `object`.
908
909 ## Enum data type
910
911 netCDF4 has an enumerated data type, which is an integer datatype that is
912 restricted to certain named values. Since Enums don't map directly to
913 a numpy data type, they are read and written as integer arrays.
914
915 Here's an example of using an Enum type to hold cloud type data.
916 The base integer data type and a python dictionary describing the allowed
917 values and their names are used to define an Enum data type using
918 [Dataset.createEnumType](#Dataset.createEnumType).
919
920 ```python
921 >>> nc = Dataset('clouds.nc','w')
922 >>> # python dict with allowed values and their names.
923 >>> enum_dict = {'Altocumulus': 7, 'Missing': 255,
924 ... 'Stratus': 2, 'Clear': 0,
925 ... 'Nimbostratus': 6, 'Cumulus': 4, 'Altostratus': 5,
926 ... 'Cumulonimbus': 1, 'Stratocumulus': 3}
927 >>> # create the Enum type called 'cloud_t'.
928 >>> cloud_type = nc.createEnumType(numpy.uint8,'cloud_t',enum_dict)
929 >>> print(cloud_type)
930 <class 'netCDF4._netCDF4.EnumType'>: name = 'cloud_t', numpy dtype = uint8, fields/values ={'Altocumulus': 7, 'Missing': 255, 'Stratus': 2, 'Clear': 0, 'Nimbostratus': 6, 'Cumulus': 4, 'Altostratus': 5, 'Cumulonimbus': 1, 'Stratocumulus': 3}
931 ```
932
933 A new variable can be created in the usual way using this data type.
934 Integer data is written to the variable that represents the named
935 cloud types in enum_dict. A `ValueError` will be raised if an attempt
936 is made to write an integer value not associated with one of the
937 specified names.
938
939 ```python
940 >>> time = nc.createDimension('time',None)
941 >>> # create a 1d variable of type 'cloud_type'.
942 >>> # The fill_value is set to the 'Missing' named value.
943 >>> cloud_var = nc.createVariable('primary_cloud',cloud_type,'time',
944 ... fill_value=enum_dict['Missing'])
945 >>> # write some data to the variable.
946 >>> cloud_var[:] = [enum_dict[k] for k in ['Clear', 'Stratus', 'Cumulus',
947 ... 'Missing', 'Cumulonimbus']]
948 >>> nc.close()
949 >>> # reopen the file, read the data.
950 >>> nc = Dataset('clouds.nc')
951 >>> cloud_var = nc.variables['primary_cloud']
952 >>> print(cloud_var)
953 <class 'netCDF4._netCDF4.Variable'>
954 enum primary_cloud(time)
955 _FillValue: 255
956 enum data type: uint8
957 unlimited dimensions: time
958 current shape = (5,)
959 >>> print(cloud_var.datatype.enum_dict)
960 {'Altocumulus': 7, 'Missing': 255, 'Stratus': 2, 'Clear': 0, 'Nimbostratus': 6, 'Cumulus': 4, 'Altostratus': 5, 'Cumulonimbus': 1, 'Stratocumulus': 3}
961 >>> print(cloud_var[:])
962 [0 2 4 -- 1]
963 >>> nc.close()
964 ```
965
966 ## Parallel IO
967
968 If MPI parallel enabled versions of netcdf and hdf5 or pnetcdf are detected,
969 and [mpi4py](https://mpi4py.scipy.org) is installed, netcdf4-python will
970 be built with parallel IO capabilities enabled. Parallel IO of NETCDF4 or
971 NETCDF4_CLASSIC formatted files is only available if the MPI parallel HDF5
972 library is available. Parallel IO of classic netcdf-3 file formats is only
973 available if the [PnetCDF](https://parallel-netcdf.github.io/) library is
974 available. To use parallel IO, your program must be running in an MPI
975 environment using [mpi4py](https://mpi4py.scipy.org).
976
977 ```python
978 >>> from mpi4py import MPI
979 >>> import numpy as np
980 >>> from netCDF4 import Dataset
981 >>> rank = MPI.COMM_WORLD.rank # The process ID (integer 0-3 for 4-process run)
982 ```
983
984 To run an MPI-based parallel program like this, you must use `mpiexec` to launch several
985 parallel instances of Python (for example, using `mpiexec -np 4 python mpi_example.py`).
986 The parallel features of netcdf4-python are mostly transparent -
987 when a new dataset is created or an existing dataset is opened,
988 use the `parallel` keyword to enable parallel access.
989
990 ```python
991 >>> nc = Dataset('parallel_test.nc','w',parallel=True)
992 ```
993
994 The optional `comm` keyword may be used to specify a particular
995 MPI communicator (`MPI_COMM_WORLD` is used by default). Each process (or rank)
996 can now write to the file indepedently. In this example the process rank is
997 written to a different variable index on each task
998
999 ```python
1000 >>> d = nc.createDimension('dim',4)
1001 >>> v = nc.createVariable('var', np.int, 'dim')
1002 >>> v[rank] = rank
1003 >>> nc.close()
1004
1005 % ncdump parallel_test.nc
1006 netcdf parallel_test {
1007 dimensions:
1008 dim = 4 ;
1009 variables:
1010 int64 var(dim) ;
1011 data:
1012
1013 var = 0, 1, 2, 3 ;
1014 }
1015 ```
1016
1017 There are two types of parallel IO, independent (the default) and collective.
1018 Independent IO means that each process can do IO independently. It should not
1019 depend on or be affected by other processes. Collective IO is a way of doing
1020 IO defined in the MPI-IO standard; unlike independent IO, all processes must
1021 participate in doing IO. To toggle back and forth between
1022 the two types of IO, use the [Variable.set_collective](#Variable.set_collective)
1023 [Variable](#Variable) method. All metadata
1024 operations (such as creation of groups, types, variables, dimensions, or attributes)
1025 are collective. There are a couple of important limitations of parallel IO:
1026
1027 - parallel IO for NETCDF4 or NETCDF4_CLASSIC formatted files is only available
1028 if the netcdf library was compiled with MPI enabled HDF5.
1029 - parallel IO for all classic netcdf-3 file formats is only available if the
1030 netcdf library was compiled with [PnetCDF](https://parallel-netcdf.github.io).
1031 - If a variable has an unlimited dimension, appending data must be done in collective mode.
1032 If the write is done in independent mode, the operation will fail with a
1033 a generic "HDF Error".
1034 - You can write compressed data in parallel only with netcdf-c >= 4.7.4
1035 and hdf5 >= 1.10.3 (although you can read in parallel with earlier versions).
1036 - You cannot use variable-length (VLEN) data types.
1037
1038 ## Dealing with strings
1039
1040 The most flexible way to store arrays of strings is with the
1041 [Variable-length (vlen) string data type](#variable-length-vlen-data-type). However, this requires
1042 the use of the NETCDF4 data model, and the vlen type does not map very well
1043 numpy arrays (you have to use numpy arrays of dtype=`object`, which are arrays of
1044 arbitrary python objects). numpy does have a fixed-width string array
1045 data type, but unfortunately the netCDF data model does not.
1046 Instead fixed-width byte strings are typically stored as [arrays of 8-bit
1047 characters](https://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.html#bp_Strings-and-Variables-of-type-char).
1048 To perform the conversion to and from character arrays to fixed-width numpy string arrays, the
1049 following convention is followed by the python interface.
1050 If the `_Encoding` special attribute is set for a character array
1051 (dtype `S1`) variable, the [chartostring](#chartostring) utility function is used to convert the array of
1052 characters to an array of strings with one less dimension (the last dimension is
1053 interpreted as the length of each string) when reading the data. The character
1054 set (usually ascii) is specified by the `_Encoding` attribute. If `_Encoding`
1055 is 'none' or 'bytes', then the character array is converted to a numpy
1056 fixed-width byte string array (dtype `S#`), otherwise a numpy unicode (dtype
1057 `U#`) array is created. When writing the data,
1058 [stringtochar](#stringtochar) is used to convert the numpy string array to an array of
1059 characters with one more dimension. For example,
1060
1061 ```python
1062 >>> from netCDF4 import stringtochar
1063 >>> nc = Dataset('stringtest.nc','w',format='NETCDF4_CLASSIC')
1064 >>> _ = nc.createDimension('nchars',3)
1065 >>> _ = nc.createDimension('nstrings',None)
1066 >>> v = nc.createVariable('strings','S1',('nstrings','nchars'))
1067 >>> datain = numpy.array(['foo','bar'],dtype='S3')
1068 >>> v[:] = stringtochar(datain) # manual conversion to char array
1069 >>> print(v[:]) # data returned as char array
1070 [[b'f' b'o' b'o']
1071 [b'b' b'a' b'r']]
1072 >>> v._Encoding = 'ascii' # this enables automatic conversion
1073 >>> v[:] = datain # conversion to char array done internally
1074 >>> print(v[:]) # data returned in numpy string array
1075 ['foo' 'bar']
1076 >>> nc.close()
1077 ```
1078
1079 Even if the `_Encoding` attribute is set, the automatic conversion of char
1080 arrays to/from string arrays can be disabled with
1081 [Variable.set_auto_chartostring](#Variable.set_auto_chartostring).
1082
1083 A similar situation is often encountered with numpy structured arrays with subdtypes
1084 containing fixed-wdith byte strings (dtype=`S#`). Since there is no native fixed-length string
1085 netCDF datatype, these numpy structure arrays are mapped onto netCDF compound
1086 types with character array elements. In this case the string <-> char array
1087 conversion is handled automatically (without the need to set the `_Encoding`
1088 attribute) using [numpy
1089 views](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.view.html).
1090 The structured array dtype (including the string elements) can even be used to
1091 define the compound data type - the string dtype will be converted to
1092 character array dtype under the hood when creating the netcdf compound type.
1093 Here's an example:
1094
1095 ```python
1096 >>> nc = Dataset('compoundstring_example.nc','w')
1097 >>> dtype = numpy.dtype([('observation', 'f4'),
1098 ... ('station_name','S10')])
1099 >>> station_data_t = nc.createCompoundType(dtype,'station_data')
1100 >>> _ = nc.createDimension('station',None)
1101 >>> statdat = nc.createVariable('station_obs', station_data_t, ('station',))
1102 >>> data = numpy.empty(2,dtype)
1103 >>> data['observation'][:] = (123.,3.14)
1104 >>> data['station_name'][:] = ('Boulder','New York')
1105 >>> print(statdat.dtype) # strings actually stored as character arrays
1106 {'names':['observation','station_name'], 'formats':['<f4',('S1', (10,))], 'offsets':[0,4], 'itemsize':16, 'aligned':True}
1107 >>> statdat[:] = data # strings converted to character arrays internally
1108 >>> print(statdat[:]) # character arrays converted back to strings
1109 [(123. , b'Boulder') ( 3.14, b'New York')]
1110 >>> print(statdat[:].dtype)
1111 {'names':['observation','station_name'], 'formats':['<f4','S10'], 'offsets':[0,4], 'itemsize':16, 'aligned':True}
1112 >>> statdat.set_auto_chartostring(False) # turn off auto-conversion
1113 >>> statdat[:] = data.view(dtype=[('observation', 'f4'),('station_name','S1',10)])
1114 >>> print(statdat[:]) # now structured array with char array subtype is returned
1115 [(123. , [b'B', b'o', b'u', b'l', b'd', b'e', b'r', b'', b'', b''])
1116 ( 3.14, [b'N', b'e', b'w', b' ', b'Y', b'o', b'r', b'k', b'', b''])]
1117 >>> nc.close()
1118 ```
1119
1120 Note that there is currently no support for mapping numpy structured arrays with
1121 unicode elements (dtype `U#`) onto netCDF compound types, nor is there support
1122 for netCDF compound types with vlen string components.
1123
1124 ## In-memory (diskless) Datasets
1125
1126 You can create netCDF Datasets whose content is held in memory
1127 instead of in a disk file. There are two ways to do this. If you
1128 don't need access to the memory buffer containing the Dataset from
1129 within python, the best way is to use the `diskless=True` keyword
1130 argument when creating the Dataset. If you want to save the Dataset
1131 to disk when you close it, also set `persist=True`. If you want to
1132 create a new read-only Dataset from an existing python memory buffer, use the
1133 `memory` keyword argument to pass the memory buffer when creating the Dataset.
1134 If you want to create a new in-memory Dataset, and then access the memory buffer
1135 directly from Python, use the `memory` keyword argument to specify the
1136 estimated size of the Dataset in bytes when creating the Dataset with
1137 `mode='w'`. Then, the `Dataset.close` method will return a python memoryview
1138 object representing the Dataset. Below are examples illustrating both
1139 approaches.
1140
1141 ```python
1142 >>> # create a diskless (in-memory) Dataset,
1143 >>> # and persist the file to disk when it is closed.
1144 >>> nc = Dataset('diskless_example.nc','w',diskless=True,persist=True)
1145 >>> d = nc.createDimension('x',None)
1146 >>> v = nc.createVariable('v',numpy.int32,'x')
1147 >>> v[0:5] = numpy.arange(5)
1148 >>> print(nc)
1149 <class 'netCDF4._netCDF4.Dataset'>
1150 root group (NETCDF4 data model, file format HDF5):
1151 dimensions(sizes): x(5)
1152 variables(dimensions): int32 v(x)
1153 groups:
1154 >>> print(nc['v'][:])
1155 [0 1 2 3 4]
1156 >>> nc.close() # file saved to disk
1157 >>> # create an in-memory dataset from an existing python
1158 >>> # python memory buffer.
1159 >>> # read the newly created netcdf file into a python
1160 >>> # bytes object.
1161 >>> with open('diskless_example.nc', 'rb') as f:
1162 ... nc_bytes = f.read()
1163 >>> # create a netCDF in-memory dataset from the bytes object.
1164 >>> nc = Dataset('inmemory.nc', memory=nc_bytes)
1165 >>> print(nc)
1166 <class 'netCDF4._netCDF4.Dataset'>
1167 root group (NETCDF4 data model, file format HDF5):
1168 dimensions(sizes): x(5)
1169 variables(dimensions): int32 v(x)
1170 groups:
1171 >>> print(nc['v'][:])
1172 [0 1 2 3 4]
1173 >>> nc.close()
1174 >>> # create an in-memory Dataset and retrieve memory buffer
1175 >>> # estimated size is 1028 bytes - this is actually only
1176 >>> # used if format is NETCDF3
1177 >>> # (ignored for NETCDF4/HDF5 files).
1178 >>> nc = Dataset('inmemory.nc', mode='w',memory=1028)
1179 >>> d = nc.createDimension('x',None)
1180 >>> v = nc.createVariable('v',numpy.int32,'x')
1181 >>> v[0:5] = numpy.arange(5)
1182 >>> nc_buf = nc.close() # close returns memoryview
1183 >>> print(type(nc_buf))
1184 <class 'memoryview'>
1185 >>> # save nc_buf to disk, read it back in and check.
1186 >>> with open('inmemory.nc', 'wb') as f:
1187 ... f.write(nc_buf)
1188 >>> nc = Dataset('inmemory.nc')
1189 >>> print(nc)
1190 <class 'netCDF4._netCDF4.Dataset'>
1191 root group (NETCDF4 data model, file format HDF5):
1192 dimensions(sizes): x(5)
1193 variables(dimensions): int32 v(x)
1194 groups:
1195 >>> print(nc['v'][:])
1196 [0 1 2 3 4]
1197 >>> nc.close()
1198 ```
1199
1200
1201 All of the code in this tutorial is available in `examples/tutorial.py`, except
1202 the parallel IO example, which is in `examples/mpi_example.py`.
1203 Unit tests are in the `test` directory.
1204
1205 **contact**: Jeffrey Whitaker <jeffrey.s.whitaker@noaa.gov>
1206
1207 **copyright**: 2008 by Jeffrey Whitaker.
1208
1209 **license**: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
1210
1211 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
1212
1213 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1214 """
1215
1216 # Make changes to this file, not the c-wrappers that Cython generates.
1217 from cpython.mem cimport PyMem_Malloc, PyMem_Free
1218 from cpython.buffer cimport PyObject_GetBuffer, PyBuffer_Release, PyBUF_SIMPLE, PyBUF_ANY_CONTIGUOUS
1219 from cpython.bytes cimport PyBytes_FromStringAndSize
1220
1221 # pure python utilities
1222 from .utils import (_StartCountStride, _quantize, _find_dim, _walk_grps,
1223 _out_array_shape, _sortbylist, _tostr, _safecast, _is_int)
1224 import sys
1225 if sys.version_info[0:2] < (3, 7):
1226 # Python 3.7+ guarantees order; older versions need OrderedDict
1227 from collections import OrderedDict
1228
1229 __version__ = "1.5.6"
1230
1231 # Initialize numpy
1232 import posixpath
1233 from cftime import date2num, num2date, date2index
1234 import numpy
1235 import weakref
1236 import warnings
1237 import subprocess
1238 import pathlib
1239 from glob import glob
1240 from numpy import ma
1241 from libc.string cimport memcpy, memset
1242 from libc.stdlib cimport malloc, free
1243 import_array()
1244 include "constants.pyx"
1245 include "membuf.pyx"
1246 include "netCDF4.pxi"
1247 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
1248 cimport mpi4py.MPI as MPI
1249 from mpi4py.libmpi cimport MPI_Comm, MPI_Info, MPI_Comm_dup, MPI_Info_dup, \
1250 MPI_Comm_free, MPI_Info_free, MPI_INFO_NULL,\
1251 MPI_COMM_WORLD
1252 ctypedef MPI.Comm Comm
1253 ctypedef MPI.Info Info
1254 ELSE:
1255 ctypedef object Comm
1256 ctypedef object Info
1257
1258 # check for required version of netcdf-4 and hdf5.
1259
1260 def _gethdf5libversion():
1261 cdef unsigned int majorvers, minorvers, releasevers
1262 cdef herr_t ierr
1263 ierr = H5get_libversion( &majorvers, &minorvers, &releasevers)
1264 if ierr < 0:
1265 raise RuntimeError('error getting HDF5 library version info')
1266 return '%d.%d.%d' % (majorvers,minorvers,releasevers)
1267
1268 def getlibversion():
1269 """
1270 **`getlibversion()`**
1271
1272 returns a string describing the version of the netcdf library
1273 used to build the module, and when it was built.
1274 """
1275 return (<char *>nc_inq_libvers()).decode('ascii')
1276
1277 def get_chunk_cache():
1278 """
1279 **`get_chunk_cache()`**
1280
1281 return current netCDF chunk cache information in a tuple (size,nelems,preemption).
1282 See netcdf C library documentation for `nc_get_chunk_cache` for
1283 details. Values can be reset with [set_chunk_cache](#set_chunk_cache)."""
1284 cdef int ierr
1285 cdef size_t sizep, nelemsp
1286 cdef float preemptionp
1287 ierr = nc_get_chunk_cache(&sizep, &nelemsp, &preemptionp)
1288 _ensure_nc_success(ierr)
1289 size = sizep; nelems = nelemsp; preemption = preemptionp
1290 return (size,nelems,preemption)
1291
1292 def set_chunk_cache(size=None,nelems=None,preemption=None):
1293 """
1294 **`set_chunk_cache(self,size=None,nelems=None,preemption=None)`**
1295
1296 change netCDF4 chunk cache settings.
1297 See netcdf C library documentation for `nc_set_chunk_cache` for
1298 details."""
1299 cdef int ierr
1300 cdef size_t sizep, nelemsp
1301 cdef float preemptionp
1302 # reset chunk cache size, leave other parameters unchanged.
1303 size_orig, nelems_orig, preemption_orig = get_chunk_cache()
1304 if size is not None:
1305 sizep = size
1306 else:
1307 sizep = size_orig
1308 if nelems is not None:
1309 nelemsp = nelems
1310 else:
1311 nelemsp = nelems_orig
1312 if preemption is not None:
1313 preemptionp = preemption
1314 else:
1315 preemptionp = preemption_orig
1316 ierr = nc_set_chunk_cache(sizep,nelemsp, preemptionp)
1317 _ensure_nc_success(ierr)
1318
1319 __netcdf4libversion__ = getlibversion().split()[0]
1320 __hdf5libversion__ = _gethdf5libversion()
1321 __has_rename_grp__ = HAS_RENAME_GRP
1322 __has_nc_inq_path__ = HAS_NC_INQ_PATH
1323 __has_nc_inq_format_extended__ = HAS_NC_INQ_FORMAT_EXTENDED
1324 __has_cdf5_format__ = HAS_CDF5_FORMAT
1325 __has_nc_open_mem__ = HAS_NC_OPEN_MEM
1326 __has_nc_create_mem__ = HAS_NC_CREATE_MEM
1327 __has_parallel4_support__ = HAS_PARALLEL4_SUPPORT
1328 __has_pnetcdf_support__ = HAS_PNETCDF_SUPPORT
1329 _needsworkaround_issue485 = __netcdf4libversion__ < "4.4.0" or \
1330 (__netcdf4libversion__.startswith("4.4.0") and \
1331 "-development" in __netcdf4libversion__)
1332
1333 # issue warning for hdf5 1.10 (issue #549)
1334 if __netcdf4libversion__[0:5] < "4.4.1" and\
1335 __hdf5libversion__.startswith("1.10"):
1336 msg = """
1337 WARNING: Backwards incompatible files will be created with HDF5 1.10.x
1338 and netCDF < 4.4.1. Upgrading to netCDF4 >= 4.4.1 or downgrading to
1339 to HDF5 version 1.8.x is highly recommended
1340 (see https://github.com/Unidata/netcdf-c/issues/250)."""
1341 warnings.warn(msg)
1342
1343 # numpy data type <--> netCDF 4 data type mapping.
1344 _nptonctype = {'S1' : NC_CHAR,
1345 'i1' : NC_BYTE,
1346 'u1' : NC_UBYTE,
1347 'i2' : NC_SHORT,
1348 'u2' : NC_USHORT,
1349 'i4' : NC_INT,
1350 'u4' : NC_UINT,
1351 'i8' : NC_INT64,
1352 'u8' : NC_UINT64,
1353 'f4' : NC_FLOAT,
1354 'f8' : NC_DOUBLE}
1355
1356 # just integer types.
1357 _intnptonctype = {'i1' : NC_BYTE,
1358 'u1' : NC_UBYTE,
1359 'i2' : NC_SHORT,
1360 'u2' : NC_USHORT,
1361 'i4' : NC_INT,
1362 'u4' : NC_UINT,
1363 'i8' : NC_INT64,
1364 'u8' : NC_UINT64}
1365
1366 # create dictionary mapping string identifiers to netcdf format codes
1367 _format_dict = {'NETCDF3_CLASSIC' : NC_FORMAT_CLASSIC,
1368 'NETCDF4_CLASSIC' : NC_FORMAT_NETCDF4_CLASSIC,
1369 'NETCDF4' : NC_FORMAT_NETCDF4}
1370 # create dictionary mapping string identifiers to netcdf create format codes
1371 _cmode_dict = {'NETCDF3_CLASSIC' : NC_CLASSIC_MODEL,
1372 'NETCDF4_CLASSIC' : NC_CLASSIC_MODEL | NC_NETCDF4,
1373 'NETCDF4' : NC_NETCDF4}
1374 IF HAS_CDF5_FORMAT:
1375 # NETCDF3_64BIT deprecated, saved for compatibility.
1376 # use NETCDF3_64BIT_OFFSET instead.
1377 _format_dict['NETCDF3_64BIT_OFFSET'] = NC_FORMAT_64BIT_OFFSET
1378 _format_dict['NETCDF3_64BIT_DATA'] = NC_FORMAT_64BIT_DATA
1379 _cmode_dict['NETCDF3_64BIT_OFFSET'] = NC_64BIT_OFFSET
1380 _cmode_dict['NETCDF3_64BIT_DATA'] = NC_64BIT_DATA
1381 ELSE:
1382 _format_dict['NETCDF3_64BIT'] = NC_FORMAT_64BIT
1383 _cmode_dict['NETCDF3_64BIT'] = NC_64BIT_OFFSET
1384 # invert dictionary mapping
1385 _reverse_format_dict = dict((v, k) for k, v in _format_dict.iteritems())
1386 # add duplicate entry (NETCDF3_64BIT == NETCDF3_64BIT_OFFSET)
1387 IF HAS_CDF5_FORMAT:
1388 _format_dict['NETCDF3_64BIT'] = NC_FORMAT_64BIT_OFFSET
1389 _cmode_dict['NETCDF3_64BIT'] = NC_64BIT_OFFSET
1390 ELSE:
1391 _format_dict['NETCDF3_64BIT_OFFSET'] = NC_FORMAT_64BIT
1392 _cmode_dict['NETCDF3_64BIT_OFFSET'] = NC_64BIT_OFFSET
1393
1394 # default fill_value to numpy datatype mapping.
1395 default_fillvals = {#'S1':NC_FILL_CHAR,
1396 'S1':'\0',
1397 'i1':NC_FILL_BYTE,
1398 'u1':NC_FILL_UBYTE,
1399 'i2':NC_FILL_SHORT,
1400 'u2':NC_FILL_USHORT,
1401 'i4':NC_FILL_INT,
1402 'u4':NC_FILL_UINT,
1403 'i8':NC_FILL_INT64,
1404 'u8':NC_FILL_UINT64,
1405 'f4':NC_FILL_FLOAT,
1406 'f8':NC_FILL_DOUBLE}
1407
1408 # logical for native endian type.
1409 is_native_little = numpy.dtype('<f4').byteorder == '='
1410 is_native_big = numpy.dtype('>f4').byteorder == '='
1411
1412 # hard code these here, instead of importing from netcdf.h
1413 # so it will compile with versions <= 4.2.
1414 NC_DISKLESS = 0x0008
1415 # introduced in 4.6.2
1416 if __netcdf4libversion__[0:5] >= "4.6.2":
1417 NC_PERSIST = 0x4000
1418 else: # prior to 4.6.2 this flag doesn't work, so make the same as NC_DISKLESS
1419 NC_PERSIST = NC_DISKLESS
1420
1421 # next two lines do nothing, preserved for backwards compatibility.
1422 default_encoding = 'utf-8'
1423 unicode_error = 'replace'
1424
1425 _nctonptype = {}
1426 for _key,_value in _nptonctype.items():
1427 _nctonptype[_value] = _key
1428 _supportedtypes = _nptonctype.keys()
1429 # make sure NC_CHAR points to S1
1430 _nctonptype[NC_CHAR]='S1'
1431
1432 # internal C functions.
1433
1434 cdef _get_att_names(int grpid, int varid):
1435 # Private function to get all the attribute names in a group
1436 cdef int ierr, numatts, n
1437 cdef char namstring[NC_MAX_NAME+1]
1438 if varid == NC_GLOBAL:
1439 with nogil:
1440 ierr = nc_inq_natts(grpid, &numatts)
1441 else:
1442 with nogil:
1443 ierr = nc_inq_varnatts(grpid, varid, &numatts)
1444 _ensure_nc_success(ierr, err_cls=AttributeError)
1445 attslist = []
1446 for n from 0 <= n < numatts:
1447 with nogil:
1448 ierr = nc_inq_attname(grpid, varid, n, namstring)
1449 _ensure_nc_success(ierr, err_cls=AttributeError)
1450 # attribute names are assumed to be utf-8
1451 attslist.append(namstring.decode('utf-8'))
1452 return attslist
1453
1454 cdef _get_att(grp, int varid, name, encoding='utf-8'):
1455 # Private function to get an attribute value given its name
1456 cdef int ierr, n, _grpid
1457 cdef size_t att_len
1458 cdef char *attname
1459 cdef nc_type att_type
1460 cdef ndarray value_arr
1461 # attribute names are assumed to be utf-8
1462 bytestr = _strencode(name,encoding='utf-8')
1463 attname = bytestr
1464 _grpid = grp._grpid
1465 with nogil:
1466 ierr = nc_inq_att(_grpid, varid, attname, &att_type, &att_len)
1467 _ensure_nc_success(ierr, err_cls=AttributeError)
1468 # attribute is a character or string ...
1469 if att_type == NC_CHAR:
1470 value_arr = numpy.empty(att_len,'S1')
1471 with nogil:
1472 ierr = nc_get_att_text(_grpid, varid, attname,
1473 PyArray_BYTES(value_arr))
1474 _ensure_nc_success(ierr, err_cls=AttributeError)
1475 if name == '_FillValue':
1476 # make sure _FillValue for character arrays is a byte on python 3
1477 # (issue 271).
1478 pstring = value_arr.tobytes()
1479 else:
1480 pstring =\
1481 value_arr.tobytes().decode(encoding,errors='replace').replace('\x00','')
1482 return pstring
1483 elif att_type == NC_STRING:
1484 values = <char**>PyMem_Malloc(sizeof(char*) * att_len)
1485 if not values:
1486 raise MemoryError()
1487 try:
1488 with nogil:
1489 ierr = nc_get_att_string(_grpid, varid, attname, values)
1490 _ensure_nc_success(ierr, err_cls=AttributeError)
1491 try:
1492 result = [values[j].decode(encoding,errors='replace').replace('\x00','')
1493 if values[j] else "" for j in range(att_len)]
1494 finally:
1495 ierr = nc_free_string(att_len, values) # free memory in netcdf C lib
1496 finally:
1497 PyMem_Free(values)
1498
1499 if len(result) == 1:
1500 return result[0]
1501 else:
1502 return result
1503 else:
1504 # a regular numeric or compound type.
1505 if att_type == NC_LONG:
1506 att_type = NC_INT
1507 try:
1508 type_att = _nctonptype[att_type] # see if it is a primitive type
1509 value_arr = numpy.empty(att_len,type_att)
1510 except KeyError:
1511 # check if it's a compound
1512 try:
1513 type_att = _read_compound(grp, att_type)
1514 value_arr = numpy.empty(att_len,type_att.dtype_view)
1515 except:
1516 # check if it's an enum
1517 try:
1518 type_att = _read_enum(grp, att_type)
1519 value_arr = numpy.empty(att_len,type_att.dtype)
1520 except:
1521 raise KeyError('attribute %s has unsupported datatype' % attname)
1522 with nogil:
1523 ierr = nc_get_att(_grpid, varid, attname, PyArray_BYTES(value_arr))
1524 _ensure_nc_success(ierr, err_cls=AttributeError)
1525 if value_arr.shape == ():
1526 # return a scalar for a scalar array
1527 return value_arr.item()
1528 elif att_len == 1:
1529 # return a scalar for a single element array
1530 return value_arr[0]
1531 else:
1532 return value_arr
1533
1534 def _set_default_format(object format='NETCDF4'):
1535 # Private function to set the netCDF file format
1536 if format not in _format_dict:
1537 raise ValueError("unrecognized format requested")
1538 nc_set_default_format(_format_dict[format], NULL)
1539
1540 cdef _get_format(int grpid):
1541 # Private function to get the netCDF file format
1542 cdef int ierr, formatp
1543 with nogil:
1544 ierr = nc_inq_format(grpid, &formatp)
1545 _ensure_nc_success(ierr)
1546 if formatp not in _reverse_format_dict:
1547 raise ValueError('format not supported by python interface')
1548 return _reverse_format_dict[formatp]
1549
1550 cdef _get_full_format(int grpid):
1551 # Private function to get the underlying disk format
1552 cdef int ierr, formatp, modep
1553 IF HAS_NC_INQ_FORMAT_EXTENDED:
1554 with nogil:
1555 ierr = nc_inq_format_extended(grpid, &formatp, &modep)
1556 _ensure_nc_success(ierr)
1557 if formatp == NC_FORMAT_NC3:
1558 return 'NETCDF3'
1559 elif formatp == NC_FORMAT_NC_HDF5:
1560 return 'HDF5'
1561 elif formatp == NC_FORMAT_NC_HDF4:
1562 return 'HDF4'
1563 elif formatp == NC_FORMAT_PNETCDF:
1564 return 'PNETCDF'
1565 elif formatp == NC_FORMAT_DAP2:
1566 return 'DAP2'
1567 elif formatp == NC_FORMAT_DAP4:
1568 return 'DAP4'
1569 elif formatp == NC_FORMAT_UNDEFINED:
1570 return 'UNDEFINED'
1571 ELSE:
1572 return 'UNDEFINED'
1573
1574 cdef issue485_workaround(int grpid, int varid, char* attname):
1575 # check to see if attribute already exists
1576 # and is NC_CHAR, if so delete it and re-create it
1577 # (workaround for issue #485). Fixed in C library
1578 # with commit 473259b7728120bb281c52359b1af50cca2fcb72,
1579 # which was included in 4.4.0-RC5.
1580 cdef nc_type att_type
1581 cdef size_t att_len
1582
1583 if not _needsworkaround_issue485:
1584 return
1585 ierr = nc_inq_att(grpid, varid, attname, &att_type, &att_len)
1586 if ierr == NC_NOERR and att_type == NC_CHAR:
1587 ierr = nc_del_att(grpid, varid, attname)
1588 _ensure_nc_success(ierr)
1589
1590
1591 cdef _set_att(grp, int varid, name, value,\
1592 nc_type xtype=-99, force_ncstring=False):
1593 # Private function to set an attribute name/value pair
1594 cdef int ierr, lenarr
1595 cdef char *attname
1596 cdef char *datstring
1597 cdef char **string_ptrs
1598 cdef ndarray value_arr
1599 bytestr = _strencode(name)
1600 attname = bytestr
1601 # put attribute value into a numpy array.
1602 value_arr = numpy.array(value)
1603 if value_arr.ndim > 1: # issue #841
1604 if __version__ > "1.4.2":
1605 raise ValueError('multi-dimensional array attributes not supported')
1606 else:
1607 msg = """
1608 Multi-dimensional array attributes are now deprecated.
1609 Instead of silently flattening the array, an error will
1610 be raised in the next release."""
1611 warnings.warn(msg,FutureWarning)
1612 # if array is 64 bit integers or
1613 # if 64-bit datatype not supported, cast to 32 bit integers.
1614 fmt = _get_format(grp._grpid)
1615 is_netcdf3 = fmt.startswith('NETCDF3') or fmt == 'NETCDF4_CLASSIC'
1616 if value_arr.dtype.str[1:] == 'i8' and ('i8' not in _supportedtypes or\
1617 (is_netcdf3 and fmt != 'NETCDF3_64BIT_DATA')):
1618 value_arr = value_arr.astype('i4')
1619 # if array contains ascii strings, write a text attribute (stored as bytes).
1620 # if array contains unicode strings, and data model is NETCDF4,
1621 # write as a string.
1622 if value_arr.dtype.char in ['S','U']:
1623 # force array of strings if array has multiple elements (issue #770)
1624 N = value_arr.size
1625 if N > 1: force_ncstring=True
1626 if not is_netcdf3 and force_ncstring and N > 1:
1627 string_ptrs = <char**>PyMem_Malloc(N * sizeof(char*))
1628 if not string_ptrs:
1629 raise MemoryError()
1630 try:
1631 strings = [_strencode(s) for s in value_arr.flat]
1632 for j in range(N):
1633 if len(strings[j]) == 0:
1634 strings[j] = _strencode('\x00')
1635 string_ptrs[j] = strings[j]
1636 issue485_workaround(grp._grpid, varid, attname)
1637 ierr = nc_put_att_string(grp._grpid, varid, attname, N, string_ptrs)
1638 finally:
1639 PyMem_Free(string_ptrs)
1640 else:
1641 # don't allow string array attributes in NETCDF3 files.
1642 if is_netcdf3 and N > 1:
1643 msg='array string attributes can only be written with NETCDF4'
1644 raise IOError(msg)
1645 if not value_arr.shape:
1646 dats = _strencode(value_arr.item())
1647 else:
1648 value_arr1 = value_arr.ravel()
1649 dats = _strencode(''.join(value_arr1.tolist()))
1650 lenarr = len(dats)
1651 datstring = dats
1652 if lenarr == 0:
1653 # write null byte
1654 lenarr=1; datstring = '\x00'
1655 if (force_ncstring or value_arr.dtype.char == 'U') and not is_netcdf3:
1656 # try to convert to ascii string, write as NC_CHAR
1657 # else it's a unicode string, write as NC_STRING (if NETCDF4)
1658 try:
1659 if force_ncstring: raise UnicodeError
1660 dats_ascii = _to_ascii(dats) # try to encode bytes as ascii string
1661 ierr = nc_put_att_text(grp._grpid, varid, attname, lenarr, datstring)
1662 except UnicodeError:
1663 issue485_workaround(grp._grpid, varid, attname)
1664 ierr = nc_put_att_string(grp._grpid, varid, attname, 1, &datstring)
1665 else:
1666 ierr = nc_put_att_text(grp._grpid, varid, attname, lenarr, datstring)
1667 _ensure_nc_success(ierr, err_cls=AttributeError)
1668 # a 'regular' array type ('f4','i4','f8' etc)
1669 else:
1670 if value_arr.dtype.kind == 'V': # compound attribute.
1671 xtype = _find_cmptype(grp,value_arr.dtype)
1672 elif value_arr.dtype.str[1:] not in _supportedtypes:
1673 raise TypeError, 'illegal data type for attribute %r, must be one of %s, got %s' % (attname, _supportedtypes, value_arr.dtype.str[1:])
1674 elif xtype == -99: # if xtype is not passed in as kwarg.
1675 xtype = _nptonctype[value_arr.dtype.str[1:]]
1676 lenarr = PyArray_SIZE(value_arr)
1677 ierr = nc_put_att(grp._grpid, varid, attname, xtype, lenarr,
1678 PyArray_DATA(value_arr))
1679 _ensure_nc_success(ierr, err_cls=AttributeError)
1680
1681 cdef _get_types(group):
1682 # Private function to create [CompoundType](#CompoundType),
1683 # [VLType](#VLType) or [EnumType](#EnumType) instances for all the
1684 # compound, VLEN or Enum types in a [Group](#Group) or [Dataset](#Dataset).
1685 cdef int ierr, ntypes, classp, n, _grpid
1686 cdef nc_type xtype
1687 cdef nc_type *typeids
1688 cdef char namstring[NC_MAX_NAME+1]
1689 _grpid = group._grpid
1690 # get the number of user defined types in this group.
1691 with nogil:
1692 ierr = nc_inq_typeids(_grpid, &ntypes, NULL)
1693 _ensure_nc_success(ierr)
1694 if ntypes > 0:
1695 typeids = <nc_type *>malloc(sizeof(nc_type) * ntypes)
1696 with nogil:
1697 ierr = nc_inq_typeids(_grpid, &ntypes, typeids)
1698 _ensure_nc_success(ierr)
1699 # create empty dictionary for CompoundType instances.
1700 if sys.version_info[0:2] < (3, 7):
1701 cmptypes = OrderedDict()
1702 vltypes = OrderedDict()
1703 enumtypes = OrderedDict()
1704 else:
1705 cmptypes = dict()
1706 vltypes = dict()
1707 enumtypes = dict()
1708
1709 if ntypes > 0:
1710 for n from 0 <= n < ntypes:
1711 xtype = typeids[n]
1712 with nogil:
1713 ierr = nc_inq_user_type(_grpid, xtype, namstring,
1714 NULL,NULL,NULL,&classp)
1715 _ensure_nc_success(ierr)
1716 if classp == NC_COMPOUND: # a compound
1717 name = namstring.decode('utf-8')
1718 # read the compound type info from the file,
1719 # create a CompoundType instance from it.
1720 try:
1721 cmptype = _read_compound(group, xtype)
1722 except KeyError:
1723 msg='WARNING: unsupported Compound type, skipping...'
1724 warnings.warn(msg)
1725 continue
1726 cmptypes[name] = cmptype
1727 elif classp == NC_VLEN: # a vlen
1728 name = namstring.decode('utf-8')
1729 # read the VLEN type info from the file,
1730 # create a VLType instance from it.
1731 try:
1732 vltype = _read_vlen(group, xtype)
1733 except KeyError:
1734 msg='WARNING: unsupported VLEN type, skipping...'
1735 warnings.warn(msg)
1736 continue
1737 vltypes[name] = vltype
1738 elif classp == NC_ENUM: # an enum type
1739 name = namstring.decode('utf-8')
1740 # read the Enum type info from the file,
1741 # create a EnumType instance from it.
1742 try:
1743 enumtype = _read_enum(group, xtype)
1744 except KeyError:
1745 msg='WARNING: unsupported Enum type, skipping...'
1746 warnings.warn(msg)
1747 continue
1748 enumtypes[name] = enumtype
1749 free(typeids)
1750 return cmptypes, vltypes, enumtypes
1751
1752 cdef _get_dims(group):
1753 # Private function to create [Dimension](#Dimension) instances for all the
1754 # dimensions in a [Group](#Group) or Dataset
1755 cdef int ierr, numdims, n, _grpid
1756 cdef int *dimids
1757 cdef char namstring[NC_MAX_NAME+1]
1758 # get number of dimensions in this Group.
1759 _grpid = group._grpid
1760 with nogil:
1761 ierr = nc_inq_ndims(_grpid, &numdims)
1762 _ensure_nc_success(ierr)
1763 # create empty dictionary for dimensions.
1764 if sys.version_info[0:2] < (3, 7):
1765 dimensions = OrderedDict()
1766 else:
1767 dimensions = dict()
1768 if numdims > 0:
1769 dimids = <int *>malloc(sizeof(int) * numdims)
1770 if group.data_model == 'NETCDF4':
1771 with nogil:
1772 ierr = nc_inq_dimids(_grpid, &numdims, dimids, 0)
1773 _ensure_nc_success(ierr)
1774 else:
1775 for n from 0 <= n < numdims:
1776 dimids[n] = n
1777 for n from 0 <= n < numdims:
1778 with nogil:
1779 ierr = nc_inq_dimname(_grpid, dimids[n], namstring)
1780 _ensure_nc_success(ierr)
1781 name = namstring.decode('utf-8')
1782 dimensions[name] = Dimension(group, name, id=dimids[n])
1783 free(dimids)
1784 return dimensions
1785
1786 cdef _get_grps(group):
1787 # Private function to create [Group](#Group) instances for all the
1788 # groups in a [Group](#Group) or Dataset
1789 cdef int ierr, numgrps, n, _grpid
1790 cdef int *grpids
1791 cdef char namstring[NC_MAX_NAME+1]
1792 # get number of groups in this Group.
1793 _grpid = group._grpid
1794 with nogil:
1795 ierr = nc_inq_grps(_grpid, &numgrps, NULL)
1796 _ensure_nc_success(ierr)
1797 # create dictionary containing [Group](#Group) instances for groups in this group
1798 if sys.version_info[0:2] < (3, 7):
1799 groups = OrderedDict()
1800 else:
1801 groups = dict()
1802 if numgrps > 0:
1803 grpids = <int *>malloc(sizeof(int) * numgrps)
1804 with nogil:
1805 ierr = nc_inq_grps(_grpid, NULL, grpids)
1806 _ensure_nc_success(ierr)
1807 for n from 0 <= n < numgrps:
1808 with nogil:
1809 ierr = nc_inq_grpname(grpids[n], namstring)
1810 _ensure_nc_success(ierr)
1811 name = namstring.decode('utf-8')
1812 groups[name] = Group(group, name, id=grpids[n])
1813 free(grpids)
1814 return groups
1815
1816 cdef _get_vars(group):
1817 # Private function to create [Variable](#Variable) instances for all the
1818 # variables in a [Group](#Group) or Dataset
1819 cdef int ierr, numvars, n, nn, numdims, varid, classp, iendian, _grpid
1820 cdef int *varids
1821 cdef int *dimids
1822 cdef nc_type xtype
1823 cdef char namstring[NC_MAX_NAME+1]
1824 cdef char namstring_cmp[NC_MAX_NAME+1]
1825 # get number of variables in this Group.
1826 _grpid = group._grpid
1827 with nogil:
1828 ierr = nc_inq_nvars(_grpid, &numvars)
1829 _ensure_nc_success(ierr, err_cls=AttributeError)
1830 # create empty dictionary for variables.
1831 if sys.version_info[0:2] < (3, 7):
1832 variables = OrderedDict()
1833 else:
1834 variables = dict()
1835 if numvars > 0:
1836 # get variable ids.
1837 varids = <int *>malloc(sizeof(int) * numvars)
1838 if group.data_model == 'NETCDF4':
1839 with nogil:
1840 ierr = nc_inq_varids(_grpid, &numvars, varids)
1841 _ensure_nc_success(ierr)
1842 else:
1843 for n from 0 <= n < numvars:
1844 varids[n] = n
1845 # loop over variables.
1846 for n from 0 <= n < numvars:
1847 varid = varids[n]
1848 # get variable name.
1849 with nogil:
1850 ierr = nc_inq_varname(_grpid, varid, namstring)
1851 _ensure_nc_success(ierr)
1852 name = namstring.decode('utf-8')
1853 # get variable type.
1854 with nogil:
1855 ierr = nc_inq_vartype(_grpid, varid, &xtype)
1856 _ensure_nc_success(ierr)
1857 # get endian-ness of variable.
1858 endianness = None
1859 with nogil:
1860 ierr = nc_inq_var_endian(_grpid, varid, &iendian)
1861 if ierr == NC_NOERR and iendian == NC_ENDIAN_LITTLE:
1862 endianness = '<'
1863 elif iendian == NC_ENDIAN_BIG:
1864 endianness = '>'
1865 # check to see if it is a supported user-defined type.
1866 try:
1867 datatype = _nctonptype[xtype]
1868 if endianness is not None:
1869 datatype = endianness + datatype
1870 except KeyError:
1871 if xtype == NC_STRING:
1872 datatype = str
1873 else:
1874 with nogil:
1875 ierr = nc_inq_user_type(_grpid, xtype, namstring_cmp,
1876 NULL, NULL, NULL, &classp)
1877 _ensure_nc_success(ierr)
1878 if classp == NC_COMPOUND: # a compound type
1879 # create CompoundType instance describing this compound type.
1880 try:
1881 datatype = _read_compound(group, xtype, endian=endianness)
1882 except KeyError:
1883 msg="WARNING: variable '%s' has unsupported compound datatype, skipping .." % name
1884 warnings.warn(msg)
1885 continue
1886 elif classp == NC_VLEN: # a compound type
1887 # create VLType instance describing this compound type.
1888 try:
1889 datatype = _read_vlen(group, xtype, endian=endianness)
1890 except KeyError:
1891 msg="WARNING: variable '%s' has unsupported VLEN datatype, skipping .." % name
1892 warnings.warn(msg)
1893 continue
1894 elif classp == NC_ENUM:
1895 # create EnumType instance describing this compound type.
1896 try:
1897 datatype = _read_enum(group, xtype, endian=endianness)
1898 except KeyError:
1899 msg="WARNING: variable '%s' has unsupported Enum datatype, skipping .." % name
1900 warnings.warn(msg)
1901 continue
1902 else:
1903 msg="WARNING: variable '%s' has unsupported datatype, skipping .." % name
1904 warnings.warn(msg)
1905 continue
1906 # get number of dimensions.
1907 with nogil:
1908 ierr = nc_inq_varndims(_grpid, varid, &numdims)
1909 _ensure_nc_success(ierr)
1910 dimids = <int *>malloc(sizeof(int) * numdims)
1911 # get dimension ids.
1912 with nogil:
1913 ierr = nc_inq_vardimid(_grpid, varid, dimids)
1914 _ensure_nc_success(ierr)
1915 # loop over dimensions, retrieve names.
1916 # if not found in current group, look in parents.
1917 # QUESTION: what if grp1 has a dimension named 'foo'
1918 # and so does it's parent - can a variable in grp1
1919 # use the 'foo' dimension from the parent?
1920 dimensions = []
1921 for nn from 0 <= nn < numdims:
1922 grp = group
1923 found = False
1924 while not found:
1925 for key, value in grp.dimensions.items():
1926 if value._dimid == dimids[nn]:
1927 dimensions.append(key)
1928 found = True
1929 break
1930 grp = grp.parent
1931 free(dimids)
1932 # create new variable instance.
1933 if endianness == '>':
1934 variables[name] = Variable(group, name, datatype, dimensions, id=varid, endian='big')
1935 elif endianness == '<':
1936 variables[name] = Variable(group, name, datatype, dimensions, id=varid, endian='little')
1937 else:
1938 variables[name] = Variable(group, name, datatype, dimensions, id=varid)
1939 free(varids) # free pointer holding variable ids.
1940 return variables
1941
1942 cdef _ensure_nc_success(ierr, err_cls=RuntimeError, filename=None):
1943 # print netcdf error message, raise error.
1944 if ierr != NC_NOERR:
1945 err_str = (<char *>nc_strerror(ierr)).decode('ascii')
1946 if issubclass(err_cls, EnvironmentError):
1947 raise err_cls(ierr, err_str, filename)
1948 else:
1949 raise err_cls(err_str)
1950
1951 # these are class attributes that
1952 # only exist at the python level (not in the netCDF file).
1953
1954 _private_atts = \
1955 ['_grpid','_grp','_varid','groups','dimensions','variables','dtype','data_model','disk_format',
1956 '_nunlimdim','path','parent','ndim','mask','scale','cmptypes','vltypes','enumtypes','_isprimitive',
1957 'file_format','_isvlen','_isenum','_iscompound','_cmptype','_vltype','_enumtype','name',
1958 '__orthogoral_indexing__','keepweakref','_has_lsd',
1959 '_buffer','chartostring','_use_get_vars','_ncstring_attrs__']
1960
1961 cdef class Dataset:
1962 """
1963 A netCDF [Dataset](#Dataset) is a collection of dimensions, groups, variables and
1964 attributes. Together they describe the meaning of data and relations among
1965 data fields stored in a netCDF file. See [Dataset.__init__](#Dataset.__init__) for more
1966 details.
1967
1968 A list of attribute names corresponding to global netCDF attributes
1969 defined for the [Dataset](#Dataset) can be obtained with the
1970 [Dataset.ncattrs](#Dataset.ncattrs) method.
1971 These attributes can be created by assigning to an attribute of the
1972 [Dataset](#Dataset) instance. A dictionary containing all the netCDF attribute
1973 name/value pairs is provided by the `__dict__` attribute of a
1974 [Dataset](#Dataset) instance.
1975
1976 The following class variables are read-only and should not be
1977 modified by the user.
1978
1979 **`dimensions`**: The `dimensions` dictionary maps the names of
1980 dimensions defined for the [Group](#Group) or [Dataset](#Dataset) to instances of the
1981 [Dimension](#Dimension) class.
1982
1983 **`variables`**: The `variables` dictionary maps the names of variables
1984 defined for this [Dataset](#Dataset) or [Group](#Group) to instances of the
1985 [Variable](#Variable) class.
1986
1987 **`groups`**: The groups dictionary maps the names of groups created for
1988 this [Dataset](#Dataset) or [Group](#Group) to instances of the [Group](#Group) class (the
1989 [Dataset](#Dataset) class is simply a special case of the [Group](#Group) class which
1990 describes the root group in the netCDF4 file).
1991
1992 **`cmptypes`**: The `cmptypes` dictionary maps the names of
1993 compound types defined for the [Group](#Group) or [Dataset](#Dataset) to instances of the
1994 [CompoundType](#CompoundType) class.
1995
1996 **`vltypes`**: The `vltypes` dictionary maps the names of
1997 variable-length types defined for the [Group](#Group) or [Dataset](#Dataset) to instances
1998 of the [VLType](#VLType) class.
1999
2000 **`enumtypes`**: The `enumtypes` dictionary maps the names of
2001 Enum types defined for the [Group](#Group) or [Dataset](#Dataset) to instances
2002 of the [EnumType](#EnumType) class.
2003
2004 **`data_model`**: `data_model` describes the netCDF
2005 data model version, one of `NETCDF3_CLASSIC`, `NETCDF4`,
2006 `NETCDF4_CLASSIC`, `NETCDF3_64BIT_OFFSET` or `NETCDF3_64BIT_DATA`.
2007
2008 **`file_format`**: same as `data_model`, retained for backwards compatibility.
2009
2010 **`disk_format`**: `disk_format` describes the underlying
2011 file format, one of `NETCDF3`, `HDF5`, `HDF4`,
2012 `PNETCDF`, `DAP2`, `DAP4` or `UNDEFINED`. Only available if using
2013 netcdf C library version >= 4.3.1, otherwise will always return
2014 `UNDEFINED`.
2015
2016 **`parent`**: `parent` is a reference to the parent
2017 [Group](#Group) instance. `None` for the root group or [Dataset](#Dataset)
2018 instance.
2019
2020 **`path`**: `path` shows the location of the [Group](#Group) in
2021 the [Dataset](#Dataset) in a unix directory format (the names of groups in the
2022 hierarchy separated by backslashes). A [Dataset](#Dataset) instance is the root
2023 group, so the path is simply `'/'`.
2024
2025 **`keepweakref`**: If `True`, child Dimension and Variables objects only keep weak
2026 references to the parent Dataset or Group.
2027
2028 **`_ncstring_attrs__`**: If `True`, all text attributes will be written as variable-length
2029 strings.
2030 """
2031 cdef object __weakref__, _inmemory
2032 cdef public int _grpid
2033 cdef public int _isopen
2034 cdef Py_buffer _buffer
2035 cdef public groups, dimensions, variables, disk_format, path, parent,\
2036 file_format, data_model, cmptypes, vltypes, enumtypes, __orthogonal_indexing__, \
2037 keepweakref, _ncstring_attrs__
2038
2039 def __init__(self, filename, mode='r', clobber=True, format='NETCDF4',
2040 diskless=False, persist=False, keepweakref=False,
2041 memory=None, encoding=None, parallel=False,
2042 Comm comm=None, Info info=None, **kwargs):
2043 """
2044 **`__init__(self, filename, mode="r", clobber=True, diskless=False,
2045 persist=False, keepweakref=False, memory=None, encoding=None,
2046 parallel=False, comm=None, info=None, format='NETCDF4')`**
2047
2048 [Dataset](#Dataset) constructor.
2049
2050 **`filename`**: Name of netCDF file to hold dataset. Can also
2051 be a python 3 pathlib instance or the URL of an OpenDAP dataset. When memory is
2052 set this is just used to set the `filepath()`.
2053
2054 **`mode`**: access mode. `r` means read-only; no data can be
2055 modified. `w` means write; a new file is created, an existing file with
2056 the same name is deleted. `a` and `r+` mean append (in analogy with
2057 serial files); an existing file is opened for reading and writing.
2058 Appending `s` to modes `r`, `w`, `r+` or `a` will enable unbuffered shared
2059 access to `NETCDF3_CLASSIC`, `NETCDF3_64BIT_OFFSET` or
2060 `NETCDF3_64BIT_DATA` formatted files.
2061 Unbuffered access may be useful even if you don't need shared
2062 access, since it may be faster for programs that don't access data
2063 sequentially. This option is ignored for `NETCDF4` and `NETCDF4_CLASSIC`
2064 formatted files.
2065
2066 **`clobber`**: if `True` (default), opening a file with `mode='w'`
2067 will clobber an existing file with the same name. if `False`, an
2068 exception will be raised if a file with the same name already exists.
2069
2070 **`format`**: underlying file format (one of `'NETCDF4',
2071 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC'`, `'NETCDF3_64BIT_OFFSET'` or
2072 `'NETCDF3_64BIT_DATA'`.
2073 Only relevant if `mode = 'w'` (if `mode = 'r','a'` or `'r+'` the file format
2074 is automatically detected). Default `'NETCDF4'`, which means the data is
2075 stored in an HDF5 file, using netCDF 4 API features. Setting
2076 `format='NETCDF4_CLASSIC'` will create an HDF5 file, using only netCDF 3
2077 compatible API features. netCDF 3 clients must be recompiled and linked
2078 against the netCDF 4 library to read files in `NETCDF4_CLASSIC` format.
2079 `'NETCDF3_CLASSIC'` is the classic netCDF 3 file format that does not
2080 handle 2+ Gb files. `'NETCDF3_64BIT_OFFSET'` is the 64-bit offset
2081 version of the netCDF 3 file format, which fully supports 2+ GB files, but
2082 is only compatible with clients linked against netCDF version 3.6.0 or
2083 later. `'NETCDF3_64BIT_DATA'` is the 64-bit data version of the netCDF 3
2084 file format, which supports 64-bit dimension sizes plus unsigned and
2085 64 bit integer data types, but is only compatible with clients linked against
2086 netCDF version 4.4.0 or later.
2087
2088 **`diskless`**: If `True`, create diskless (in-core) file.
2089 This is a feature added to the C library after the
2090 netcdf-4.2 release. If you need to access the memory buffer directly,
2091 use the in-memory feature instead (see `memory` kwarg).
2092
2093 **`persist`**: if `diskless=True`, persist file to disk when closed
2094 (default `False`).
2095
2096 **`keepweakref`**: if `True`, child Dimension and Variable instances will keep weak
2097 references to the parent Dataset or Group object. Default is `False`, which
2098 means strong references will be kept. Having Dimension and Variable instances
2099 keep a strong reference to the parent Dataset instance, which in turn keeps a
2100 reference to child Dimension and Variable instances, creates circular references.
2101 Circular references complicate garbage collection, which may mean increased
2102 memory usage for programs that create may Dataset instances with lots of
2103 Variables. It also will result in the Dataset object never being deleted, which
2104 means it may keep open files alive as well. Setting `keepweakref=True` allows
2105 Dataset instances to be garbage collected as soon as they go out of scope, potentially
2106 reducing memory usage and open file handles. However, in many cases this is not
2107 desirable, since the associated Variable instances may still be needed, but are
2108 rendered unusable when the parent Dataset instance is garbage collected.
2109
2110 **`memory`**: if not `None`, create or open an in-memory Dataset.
2111 If mode = 'r', the memory kwarg must contain a memory buffer object
2112 (an object that supports the python buffer interface).
2113 The Dataset will then be created with contents taken from this block of memory.
2114 If mode = 'w', the memory kwarg should contain the anticipated size
2115 of the Dataset in bytes (used only for NETCDF3 files). A memory
2116 buffer containing a copy of the Dataset is returned by the
2117 `Dataset.close` method. Requires netcdf-c version 4.4.1 for mode='r,
2118 netcdf-c 4.6.2 for mode='w'. To persist the file to disk, the raw
2119 bytes from the returned buffer can be written into a binary file.
2120 The Dataset can also be re-opened using this memory buffer.
2121
2122 **`encoding`**: encoding used to encode filename string into bytes.
2123 Default is None (`sys.getdefaultfileencoding()` is used).
2124
2125 **`parallel`**: open for parallel access using MPI (requires mpi4py and
2126 parallel-enabled netcdf-c and hdf5 libraries). Default is `False`. If
2127 `True`, `comm` and `info` kwargs may also be specified.
2128
2129 **`comm`**: MPI_Comm object for parallel access. Default `None`, which
2130 means MPI_COMM_WORLD will be used. Ignored if `parallel=False`.
2131
2132 **`info`**: MPI_Info object for parallel access. Default `None`, which
2133 means MPI_INFO_NULL will be used. Ignored if `parallel=False`.
2134 """
2135 cdef int grpid, ierr, numgrps, numdims, numvars
2136 cdef size_t initialsize
2137 cdef char *path
2138 cdef char namstring[NC_MAX_NAME+1]
2139 cdef int cmode
2140 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2141 cdef MPI_Comm mpicomm
2142 cdef MPI_Info mpiinfo
2143
2144 memset(&self._buffer, 0, sizeof(self._buffer))
2145
2146 # flag to indicate that Variables in this Dataset support orthogonal indexing.
2147 self.__orthogonal_indexing__ = True
2148 if diskless and __netcdf4libversion__ < '4.2.1':
2149 #diskless = False # don't raise error, instead silently ignore
2150 raise ValueError('diskless mode requires netcdf lib >= 4.2.1, you have %s' % __netcdf4libversion__)
2151 # convert filename into string (from os.path object for example),
2152 # encode into bytes.
2153 if encoding is None:
2154 encoding = sys.getfilesystemencoding()
2155 bytestr = _strencode(_tostr(filename), encoding=encoding)
2156 path = bytestr
2157
2158 if memory is not None and mode not in ['r','w']:
2159 msg='if memory kwarg specified, mode must be \'r\' or \'w\''
2160 raise ValueError(msg)
2161
2162 if parallel:
2163 IF HAS_PARALLEL4_SUPPORT != 1 and HAS_PNETCDF_SUPPORT != 1:
2164 msg='parallel mode requires MPI enabled netcdf-c'
2165 raise ValueError(msg)
2166 ELSE:
2167 parallel_formats = []
2168 IF HAS_PARALLEL4_SUPPORT:
2169 parallel_formats += ['NETCDF4','NETCDF4_CLASSIC']
2170 IF HAS_PNETCDF_SUPPORT:
2171 parallel_formats += ['NETCDF3_CLASSIC',
2172 'NETCDF3_64BIT_OFFSET',
2173 'NETCDF3_64BIT_DATA',
2174 'NETCDF3_64BIT']
2175 if format not in parallel_formats:
2176 msg='parallel mode only works with the following formats: ' + ' '.join(parallel_formats)
2177 raise ValueError(msg)
2178 if comm is not None:
2179 mpicomm = comm.ob_mpi
2180 else:
2181 mpicomm = MPI_COMM_WORLD
2182 if info is not None:
2183 mpiinfo = info.ob_mpi
2184 else:
2185 mpiinfo = MPI_INFO_NULL
2186 cmode = NC_MPIIO | _cmode_dict[format]
2187
2188 self._inmemory = False
2189 if mode == 'w':
2190 _set_default_format(format=format)
2191 if memory is not None:
2192 # if memory is not None and mode='w', memory
2193 # kwarg is interpreted as advisory size.
2194 IF HAS_NC_CREATE_MEM:
2195 initialsize = <size_t>memory
2196 ierr = nc_create_mem(path, 0, initialsize, &grpid)
2197 self._inmemory = True # checked in close method
2198 ELSE:
2199 msg = """
2200 nc_create_mem functionality not enabled. To enable, install Cython, make sure you have
2201 version 4.6.2 or higher of the netcdf C lib, and rebuild netcdf4-python."""
2202 raise ValueError(msg)
2203 else:
2204 if clobber:
2205 if parallel:
2206 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2207 ierr = nc_create_par(path, NC_CLOBBER | cmode, \
2208 mpicomm, mpiinfo, &grpid)
2209 ELSE:
2210 pass
2211 elif diskless:
2212 if persist:
2213 ierr = nc_create(path, NC_WRITE | NC_CLOBBER |
2214 NC_DISKLESS | NC_PERSIST, &grpid)
2215 else:
2216 ierr = nc_create(path, NC_CLOBBER | NC_DISKLESS , &grpid)
2217 else:
2218 ierr = nc_create(path, NC_CLOBBER, &grpid)
2219 else:
2220 if parallel:
2221 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2222 ierr = nc_create_par(path, NC_NOCLOBBER | cmode, \
2223 mpicomm, mpiinfo, &grpid)
2224 ELSE:
2225 pass
2226 elif diskless:
2227 if persist:
2228 ierr = nc_create(path, NC_WRITE | NC_NOCLOBBER |
2229 NC_DISKLESS | NC_PERSIST , &grpid)
2230 else:
2231 ierr = nc_create(path, NC_NOCLOBBER | NC_DISKLESS , &grpid)
2232 else:
2233 ierr = nc_create(path, NC_NOCLOBBER, &grpid)
2234 # reset default format to netcdf3 - this is a workaround
2235 # for issue 170 (nc_open'ing a DAP dataset after switching
2236 # format to NETCDF4). This bug should be fixed in version
2237 # 4.3.0 of the netcdf library (add a version check here?).
2238 # **this causes parallel mode to fail when both hdf5-parallel and
2239 # pnetcdf are enabled - issue #820 **
2240 #_set_default_format(format='NETCDF3_64BIT_OFFSET')
2241 elif mode in ('r', 'rs'):
2242 if memory is not None:
2243 IF HAS_NC_OPEN_MEM:
2244 # Store reference to memory
2245 result = PyObject_GetBuffer(memory, &self._buffer, PyBUF_SIMPLE | PyBUF_ANY_CONTIGUOUS)
2246 if result != 0:
2247 raise ValueError("Unable to retrieve Buffer from %s" % (memory,))
2248
2249 ierr = nc_open_mem(<char *>path, 0, self._buffer.len, <void *>self._buffer.buf, &grpid)
2250 ELSE:
2251 msg = """
2252 nc_open_mem functionality not enabled. To enable, install Cython, make sure you have
2253 version 4.4.1 or higher of the netcdf C lib, and rebuild netcdf4-python."""
2254 raise ValueError(msg)
2255 elif parallel:
2256 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2257 ierr = nc_open_par(path, NC_NOWRITE | NC_MPIIO, \
2258 mpicomm, mpiinfo, &grpid)
2259 ELSE:
2260 pass
2261 elif diskless:
2262 ierr = nc_open(path, NC_NOWRITE | NC_DISKLESS, &grpid)
2263 else:
2264 if mode == 'rs':
2265 # NC_SHARE is very important for speed reading
2266 # large netcdf3 files with a record dimension
2267 # (pull request #902).
2268 ierr = nc_open(path, NC_NOWRITE | NC_SHARE, &grpid)
2269 else:
2270 ierr = nc_open(path, NC_NOWRITE, &grpid)
2271 elif mode == 'r+' or mode == 'a':
2272 if parallel:
2273 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2274 ierr = nc_open_par(path, NC_WRITE | NC_MPIIO, \
2275 mpicomm, mpiinfo, &grpid)
2276 ELSE:
2277 pass
2278 elif diskless:
2279 ierr = nc_open(path, NC_WRITE | NC_DISKLESS, &grpid)
2280 else:
2281 ierr = nc_open(path, NC_WRITE, &grpid)
2282 elif mode == 'as' or mode == 'r+s':
2283 if parallel:
2284 # NC_SHARE ignored
2285 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2286 ierr = nc_open_par(path, NC_WRITE | NC_MPIIO, \
2287 mpicomm, mpiinfo, &grpid)
2288 ELSE:
2289 pass
2290 elif diskless:
2291 ierr = nc_open(path, NC_SHARE | NC_DISKLESS, &grpid)
2292 else:
2293 ierr = nc_open(path, NC_SHARE, &grpid)
2294 elif mode == 'ws':
2295 _set_default_format(format=format)
2296 if clobber:
2297 if parallel:
2298 # NC_SHARE ignored
2299 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2300 ierr = nc_create_par(path, NC_CLOBBER | cmode, \
2301 mpicomm, mpiinfo, &grpid)
2302 ELSE:
2303 pass
2304 elif diskless:
2305 if persist:
2306 ierr = nc_create(path, NC_WRITE | NC_SHARE | NC_CLOBBER | NC_DISKLESS , &grpid)
2307 else:
2308 ierr = nc_create(path, NC_SHARE | NC_CLOBBER | NC_DISKLESS , &grpid)
2309 else:
2310 ierr = nc_create(path, NC_SHARE | NC_CLOBBER, &grpid)
2311 else:
2312 if parallel:
2313 # NC_SHARE ignored
2314 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
2315 ierr = nc_create_par(path, NC_NOCLOBBER | cmode, \
2316 mpicomm, mpiinfo, &grpid)
2317 ELSE:
2318 pass
2319 elif diskless:
2320 if persist:
2321 ierr = nc_create(path, NC_WRITE | NC_SHARE | NC_NOCLOBBER | NC_DISKLESS , &grpid)
2322 else:
2323 ierr = nc_create(path, NC_SHARE | NC_NOCLOBBER | NC_DISKLESS , &grpid)
2324 else:
2325 ierr = nc_create(path, NC_SHARE | NC_NOCLOBBER, &grpid)
2326 else:
2327 raise ValueError("mode must be 'w', 'r', 'a' or 'r+', got '%s'" % mode)
2328
2329 _ensure_nc_success(ierr, err_cls=IOError, filename=path)
2330
2331 # data model and file format attributes
2332 self.data_model = _get_format(grpid)
2333 # data_model attribute used to be file_format (versions < 1.0.8), retain
2334 # file_format for backwards compatibility.
2335 self.file_format = self.data_model
2336 self.disk_format = _get_full_format(grpid)
2337 # diskless read access only works with NETCDF_CLASSIC (for now)
2338 #ncopen = mode.startswith('a') or mode.startswith('r')
2339 #if diskless and self.data_model != 'NETCDF3_CLASSIC' and ncopen:
2340 # raise ValueError("diskless access only supported for NETCDF3_CLASSIC format")
2341 self._grpid = grpid
2342 self._isopen = 1
2343 self.path = '/'
2344 self.parent = None
2345 self.keepweakref = keepweakref
2346 self._ncstring_attrs__ = False
2347 # get compound, vlen and enum types in the root Group.
2348 self.cmptypes, self.vltypes, self.enumtypes = _get_types(self)
2349 # get dimensions in the root group.
2350 self.dimensions = _get_dims(self)
2351 # get variables in the root Group.
2352 self.variables = _get_vars(self)
2353 # get groups in the root Group.
2354 if self.data_model == 'NETCDF4':
2355 self.groups = _get_grps(self)
2356 else:
2357 if sys.version_info[0:2] < (3, 7):
2358 self.groups = OrderedDict()
2359 else:
2360 self.groups = dict()
2361
2362 # these allow Dataset objects to be used via a "with" statement.
2363 def __enter__(self):
2364 return self
2365 def __exit__(self,atype,value,traceback):
2366 self.close()
2367
2368 def __getitem__(self, elem):
2369 # return variable or group defined in relative path.
2370 # split out group names in unix path.
2371 elem = posixpath.normpath(elem)
2372 # last name in path, could be a variable or group
2373 dirname, lastname = posixpath.split(elem)
2374 nestedgroups = dirname.split('/')
2375 group = self
2376 # iterate over groups in path.
2377 for g in nestedgroups:
2378 if g: group = group.groups[g]
2379 # return last one, either a group or a variable.
2380 if lastname in group.groups:
2381 return group.groups[lastname]
2382 elif lastname in group.variables:
2383 return group.variables[lastname]
2384 else:
2385 raise IndexError('%s not found in %s' % (lastname,group.path))
2386
2387 def filepath(self,encoding=None):
2388 """
2389 **`filepath(self,encoding=None)`**
2390
2391 Get the file system path (or the opendap URL) which was used to
2392 open/create the Dataset. Requires netcdf >= 4.1.2. The path
2393 is decoded into a string using `sys.getfilesystemencoding()` by default, this can be
2394 changed using the `encoding` kwarg."""
2395 cdef int ierr
2396 cdef size_t pathlen
2397 cdef char *c_path
2398 if encoding is None:
2399 encoding = sys.getfilesystemencoding()
2400 IF HAS_NC_INQ_PATH:
2401 with nogil:
2402 ierr = nc_inq_path(self._grpid, &pathlen, NULL)
2403 _ensure_nc_success(ierr)
2404
2405 c_path = <char *>malloc(sizeof(char) * (pathlen + 1))
2406 if not c_path:
2407 raise MemoryError()
2408 try:
2409 with nogil:
2410 ierr = nc_inq_path(self._grpid, &pathlen, c_path)
2411 _ensure_nc_success(ierr)
2412
2413 py_path = c_path[:pathlen] # makes a copy of pathlen bytes from c_string
2414 finally:
2415 free(c_path)
2416 return py_path.decode(encoding)
2417 ELSE:
2418 msg = """
2419 filepath method not enabled. To enable, install Cython, make sure you have
2420 version 4.1.2 or higher of the netcdf C lib, and rebuild netcdf4-python."""
2421 raise ValueError(msg)
2422
2423 def __repr__(self):
2424 return self.__unicode__()
2425
2426 def __unicode__(self):
2427 ncdump = [repr(type(self))]
2428 dimnames = tuple(_tostr(dimname)+'(%s)'%len(self.dimensions[dimname])\
2429 for dimname in self.dimensions.keys())
2430 varnames = tuple(\
2431 [_tostr(self.variables[varname].dtype)+' '+_tostr(varname)+
2432 ((_tostr(self.variables[varname].dimensions)).replace(",)",")")).replace("'","")
2433 for varname in self.variables.keys()])
2434 grpnames = tuple(_tostr(grpname) for grpname in self.groups.keys())
2435 if self.path == '/':
2436 ncdump.append('root group (%s data model, file format %s):' %
2437 (self.data_model, self.disk_format))
2438 else:
2439 ncdump.append('group %s:' % self.path)
2440 for name in self.ncattrs():
2441 ncdump.append(' %s: %s' % (name, self.getncattr(name)))
2442 ncdump.append(' dimensions(sizes): %s' % ', '.join(dimnames))
2443 ncdump.append(' variables(dimensions): %s' % ', '.join(varnames))
2444 ncdump.append(' groups: %s' % ', '.join(grpnames))
2445 return '\n'.join(ncdump)
2446
2447 def _close(self, check_err):
2448 cdef int ierr = nc_close(self._grpid)
2449
2450 if check_err:
2451 _ensure_nc_success(ierr)
2452
2453 self._isopen = 0 # indicates file already closed, checked by __dealloc__
2454
2455 # Only release buffer if close succeeded
2456 # per impl of PyBuffer_Release: https://github.com/python/cpython/blob/master/Objects/abstract.c#L667
2457 # view.obj is checked, ref on obj is decremented and obj will be null'd out
2458 PyBuffer_Release(&self._buffer)
2459
2460 IF HAS_NC_CREATE_MEM:
2461 def _close_mem(self, check_err):
2462 cdef int ierr
2463 cdef NC_memio memio
2464 ierr = nc_close_memio(self._grpid, &memio)
2465
2466 if check_err:
2467 _ensure_nc_success(ierr)
2468
2469 self._isopen = 0
2470 PyBuffer_Release(&self._buffer)
2471
2472 # membuf_fromptr from membuf.pyx - creates a python memoryview
2473 # from a raw pointer without making a copy.
2474 return memview_fromptr(<char *>memio.memory, memio.size)
2475
2476
2477 def close(self):
2478 """
2479 **`close(self)`**
2480
2481 Close the Dataset.
2482 """
2483 IF HAS_NC_CREATE_MEM:
2484 if self._inmemory:
2485 return self._close_mem(True)
2486 else:
2487 self._close(True)
2488 ELSE:
2489 self._close(True)
2490
2491 def isopen(self):
2492 """
2493 **`close(self)`**
2494
2495 is the Dataset open or closed?
2496 """
2497 return bool(self._isopen)
2498
2499 def __dealloc__(self):
2500 # close file when there are no references to object left
2501 if self._isopen:
2502 self._close(False)
2503
2504 def __reduce__(self):
2505 # raise error is user tries to pickle a Dataset object.
2506 raise NotImplementedError('Dataset is not picklable')
2507
2508 def sync(self):
2509 """
2510 **`sync(self)`**
2511
2512 Writes all buffered data in the [Dataset](#Dataset) to the disk file."""
2513 _ensure_nc_success(nc_sync(self._grpid))
2514
2515 def _redef(self):
2516 cdef int ierr
2517 ierr = nc_redef(self._grpid)
2518
2519 def _enddef(self):
2520 cdef int ierr
2521 ierr = nc_enddef(self._grpid)
2522
2523 def set_fill_on(self):
2524 """
2525 **`set_fill_on(self)`**
2526
2527 Sets the fill mode for a [Dataset](#Dataset) open for writing to `on`.
2528
2529 This causes data to be pre-filled with fill values. The fill values can be
2530 controlled by the variable's `_Fill_Value` attribute, but is usually
2531 sufficient to the use the netCDF default `_Fill_Value` (defined
2532 separately for each variable type). The default behavior of the netCDF
2533 library corresponds to `set_fill_on`. Data which are equal to the
2534 `_Fill_Value` indicate that the variable was created, but never written
2535 to."""
2536 cdef int oldmode
2537 _ensure_nc_success(nc_set_fill(self._grpid, NC_FILL, &oldmode))
2538
2539 def set_fill_off(self):
2540 """
2541 **`set_fill_off(self)`**
2542
2543 Sets the fill mode for a [Dataset](#Dataset) open for writing to `off`.
2544
2545 This will prevent the data from being pre-filled with fill values, which
2546 may result in some performance improvements. However, you must then make
2547 sure the data is actually written before being read."""
2548 cdef int oldmode
2549 _ensure_nc_success(nc_set_fill(self._grpid, NC_NOFILL, &oldmode))
2550
2551 def createDimension(self, dimname, size=None):
2552 """
2553 **`createDimension(self, dimname, size=None)`**
2554
2555 Creates a new dimension with the given `dimname` and `size`.
2556
2557 `size` must be a positive integer or `None`, which stands for
2558 "unlimited" (default is `None`). Specifying a size of 0 also
2559 results in an unlimited dimension. The return value is the [Dimension](#Dimension)
2560 class instance describing the new dimension. To determine the current
2561 maximum size of the dimension, use the `len` function on the [Dimension](#Dimension)
2562 instance. To determine if a dimension is 'unlimited', use the
2563 [Dimension.isunlimited](#Dimension.isunlimited) method of the [Dimension](#Dimension) instance."""
2564 self.dimensions[dimname] = Dimension(self, dimname, size=size)
2565 return self.dimensions[dimname]
2566
2567 def renameDimension(self, oldname, newname):
2568 """
2569 **`renameDimension(self, oldname, newname)`**
2570
2571 rename a [Dimension](#Dimension) named `oldname` to `newname`."""
2572 cdef char *namstring
2573 bytestr = _strencode(newname)
2574 namstring = bytestr
2575 if self.data_model != 'NETCDF4': self._redef()
2576 try:
2577 dim = self.dimensions[oldname]
2578 except KeyError:
2579 raise KeyError('%s not a valid dimension name' % oldname)
2580 ierr = nc_rename_dim(self._grpid, dim._dimid, namstring)
2581 if self.data_model != 'NETCDF4': self._enddef()
2582
2583 _ensure_nc_success(ierr)
2584 # remove old key from dimensions dict.
2585 self.dimensions.pop(oldname)
2586 # add new key.
2587 self.dimensions[newname] = dim
2588 # Variable.dimensions is determined by a method that
2589 # looks in the file, so no need to manually update.
2590
2591 def createCompoundType(self, datatype, datatype_name):
2592 """
2593 **`createCompoundType(self, datatype, datatype_name)`**
2594
2595 Creates a new compound data type named `datatype_name` from the numpy
2596 dtype object `datatype`.
2597
2598 ***Note***: If the new compound data type contains other compound data types
2599 (i.e. it is a 'nested' compound type, where not all of the elements
2600 are homogeneous numeric data types), then the 'inner' compound types **must** be
2601 created first.
2602
2603 The return value is the [CompoundType](#CompoundType) class instance describing the new
2604 datatype."""
2605 self.cmptypes[datatype_name] = CompoundType(self, datatype,\
2606 datatype_name)
2607 return self.cmptypes[datatype_name]
2608
2609 def createVLType(self, datatype, datatype_name):
2610 """
2611 **`createVLType(self, datatype, datatype_name)`**
2612
2613 Creates a new VLEN data type named `datatype_name` from a numpy
2614 dtype object `datatype`.
2615
2616 The return value is the [VLType](#VLType) class instance describing the new
2617 datatype."""
2618 self.vltypes[datatype_name] = VLType(self, datatype, datatype_name)
2619 return self.vltypes[datatype_name]
2620
2621 def createEnumType(self, datatype, datatype_name, enum_dict):
2622 """
2623 **`createEnumType(self, datatype, datatype_name, enum_dict)`**
2624
2625 Creates a new Enum data type named `datatype_name` from a numpy
2626 integer dtype object `datatype`, and a python dictionary
2627 defining the enum fields and values.
2628
2629 The return value is the [EnumType](#EnumType) class instance describing the new
2630 datatype."""
2631 self.enumtypes[datatype_name] = EnumType(self, datatype, datatype_name,
2632 enum_dict)
2633 return self.enumtypes[datatype_name]
2634
2635 def createVariable(self, varname, datatype, dimensions=(), zlib=False,
2636 complevel=4, shuffle=True, fletcher32=False, contiguous=False,
2637 chunksizes=None, endian='native', least_significant_digit=None,
2638 fill_value=None, chunk_cache=None):
2639 """
2640 **`createVariable(self, varname, datatype, dimensions=(), zlib=False,
2641 complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None,
2642 endian='native', least_significant_digit=None, fill_value=None, chunk_cache=None)`**
2643
2644 Creates a new variable with the given `varname`, `datatype`, and
2645 `dimensions`. If dimensions are not given, the variable is assumed to be
2646 a scalar.
2647
2648 If `varname` is specified as a path, using forward slashes as in unix to
2649 separate components, then intermediate groups will be created as necessary
2650 For example, `createVariable('/GroupA/GroupB/VarC', float, ('x','y'))` will create groups `GroupA`
2651 and `GroupA/GroupB`, plus the variable `GroupA/GroupB/VarC`, if the preceding
2652 groups don't already exist.
2653
2654 The `datatype` can be a numpy datatype object, or a string that describes
2655 a numpy dtype object (like the `dtype.str` attribute of a numpy array).
2656 Supported specifiers include: `'S1' or 'c' (NC_CHAR), 'i1' or 'b' or 'B'
2657 (NC_BYTE), 'u1' (NC_UBYTE), 'i2' or 'h' or 's' (NC_SHORT), 'u2'
2658 (NC_USHORT), 'i4' or 'i' or 'l' (NC_INT), 'u4' (NC_UINT), 'i8' (NC_INT64),
2659 'u8' (NC_UINT64), 'f4' or 'f' (NC_FLOAT), 'f8' or 'd' (NC_DOUBLE)`.
2660 `datatype` can also be a [CompoundType](#CompoundType) instance
2661 (for a structured, or compound array), a [VLType](#VLType) instance
2662 (for a variable-length array), or the python `str` builtin
2663 (for a variable-length string array). Numpy string and unicode datatypes with
2664 length greater than one are aliases for `str`.
2665
2666 Data from netCDF variables is presented to python as numpy arrays with
2667 the corresponding data type.
2668
2669 `dimensions` must be a tuple containing dimension names (strings) that
2670 have been defined previously using [Dataset.createDimension](#Dataset.createDimension). The default value
2671 is an empty tuple, which means the variable is a scalar.
2672
2673 If the optional keyword `zlib` is `True`, the data will be compressed in
2674 the netCDF file using gzip compression (default `False`).
2675
2676 The optional keyword `complevel` is an integer between 1 and 9 describing
2677 the level of compression desired (default 4). Ignored if `zlib=False`.
2678
2679 If the optional keyword `shuffle` is `True`, the HDF5 shuffle filter
2680 will be applied before compressing the data (default `True`). This
2681 significantly improves compression. Default is `True`. Ignored if
2682 `zlib=False`.
2683
2684 If the optional keyword `fletcher32` is `True`, the Fletcher32 HDF5
2685 checksum algorithm is activated to detect errors. Default `False`.
2686
2687 If the optional keyword `contiguous` is `True`, the variable data is
2688 stored contiguously on disk. Default `False`. Setting to `True` for
2689 a variable with an unlimited dimension will trigger an error.
2690
2691 The optional keyword `chunksizes` can be used to manually specify the
2692 HDF5 chunksizes for each dimension of the variable. A detailed
2693 discussion of HDF chunking and I/O performance is available
2694 [here](http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html).
2695 Basically, you want the chunk size for each dimension to match as
2696 closely as possible the size of the data block that users will read
2697 from the file. `chunksizes` cannot be set if `contiguous=True`.
2698
2699 The optional keyword `endian` can be used to control whether the
2700 data is stored in little or big endian format on disk. Possible
2701 values are `little, big` or `native` (default). The library
2702 will automatically handle endian conversions when the data is read,
2703 but if the data is always going to be read on a computer with the
2704 opposite format as the one used to create the file, there may be
2705 some performance advantage to be gained by setting the endian-ness.
2706
2707 The `zlib, complevel, shuffle, fletcher32, contiguous, chunksizes` and `endian`
2708 keywords are silently ignored for netCDF 3 files that do not use HDF5.
2709
2710 The optional keyword `fill_value` can be used to override the default
2711 netCDF `_FillValue` (the value that the variable gets filled with before
2712 any data is written to it, defaults given in [default_fillvals](#default_fillvals)).
2713 If fill_value is set to `False`, then the variable is not pre-filled.
2714
2715 If the optional keyword parameter `least_significant_digit` is
2716 specified, variable data will be truncated (quantized). In conjunction
2717 with `zlib=True` this produces 'lossy', but significantly more
2718 efficient compression. For example, if `least_significant_digit=1`,
2719 data will be quantized using `numpy.around(scale*data)/scale`, where
2720 scale = 2**bits, and bits is determined so that a precision of 0.1 is
2721 retained (in this case bits=4). From the
2722 [PSL metadata conventions](http://www.esrl.noaa.gov/psl/data/gridded/conventions/cdc_netcdf_standard.shtml):
2723 "least_significant_digit -- power of ten of the smallest decimal place
2724 in unpacked data that is a reliable value." Default is `None`, or no
2725 quantization, or 'lossless' compression.
2726
2727 When creating variables in a `NETCDF4` or `NETCDF4_CLASSIC` formatted file,
2728 HDF5 creates something called a 'chunk cache' for each variable. The
2729 default size of the chunk cache may be large enough to completely fill
2730 available memory when creating thousands of variables. The optional
2731 keyword `chunk_cache` allows you to reduce (or increase) the size of
2732 the default chunk cache when creating a variable. The setting only
2733 persists as long as the Dataset is open - you can use the set_var_chunk_cache
2734 method to change it the next time the Dataset is opened.
2735 Warning - messing with this parameter can seriously degrade performance.
2736
2737 The return value is the [Variable](#Variable) class instance describing the new
2738 variable.
2739
2740 A list of names corresponding to netCDF variable attributes can be
2741 obtained with the [Variable](#Variable) method [Variable.ncattrs](#Variable.ncattrs). A dictionary
2742 containing all the netCDF attribute name/value pairs is provided by
2743 the `__dict__` attribute of a [Variable](#Variable) instance.
2744
2745 [Variable](#Variable) instances behave much like array objects. Data can be
2746 assigned to or retrieved from a variable with indexing and slicing
2747 operations on the [Variable](#Variable) instance. A [Variable](#Variable) instance has six
2748 Dataset standard attributes: `dimensions, dtype, shape, ndim, name` and
2749 `least_significant_digit`. Application programs should never modify
2750 these attributes. The `dimensions` attribute is a tuple containing the
2751 names of the dimensions associated with this variable. The `dtype`
2752 attribute is a string describing the variable's data type (`i4, f8,
2753 S1,` etc). The `shape` attribute is a tuple describing the current
2754 sizes of all the variable's dimensions. The `name` attribute is a
2755 string containing the name of the Variable instance.
2756 The `least_significant_digit`
2757 attributes describes the power of ten of the smallest decimal place in
2758 the data the contains a reliable value. assigned to the [Variable](#Variable)
2759 instance. If `None`, the data is not truncated. The `ndim` attribute
2760 is the number of variable dimensions."""
2761 # if varname specified as a path, split out group names.
2762 varname = posixpath.normpath(varname)
2763 dirname, varname = posixpath.split(varname) # varname is last.
2764 # create parent groups (like mkdir -p).
2765 if not dirname:
2766 group = self
2767 else:
2768 group = self.createGroup(dirname)
2769 # create variable.
2770 group.variables[varname] = Variable(group, varname, datatype,
2771 dimensions=dimensions, zlib=zlib, complevel=complevel, shuffle=shuffle,
2772 fletcher32=fletcher32, contiguous=contiguous, chunksizes=chunksizes,
2773 endian=endian, least_significant_digit=least_significant_digit,
2774 fill_value=fill_value, chunk_cache=chunk_cache)
2775 return group.variables[varname]
2776
2777 def renameVariable(self, oldname, newname):
2778 """
2779 **`renameVariable(self, oldname, newname)`**
2780
2781 rename a [Variable](#Variable) named `oldname` to `newname`"""
2782 cdef char *namstring
2783 try:
2784 var = self.variables[oldname]
2785 except KeyError:
2786 raise KeyError('%s not a valid variable name' % oldname)
2787 bytestr = _strencode(newname)
2788 namstring = bytestr
2789 if self.data_model != 'NETCDF4': self._redef()
2790 ierr = nc_rename_var(self._grpid, var._varid, namstring)
2791 if self.data_model != 'NETCDF4': self._enddef()
2792
2793 _ensure_nc_success(ierr)
2794 # remove old key from dimensions dict.
2795 self.variables.pop(oldname)
2796 # add new key.
2797 self.variables[newname] = var
2798
2799 def createGroup(self, groupname):
2800 """
2801 **`createGroup(self, groupname)`**
2802
2803 Creates a new [Group](#Group) with the given `groupname`.
2804
2805 If `groupname` is specified as a path, using forward slashes as in unix to
2806 separate components, then intermediate groups will be created as necessary
2807 (analogous to `mkdir -p` in unix). For example,
2808 `createGroup('/GroupA/GroupB/GroupC')` will create `GroupA`,
2809 `GroupA/GroupB`, and `GroupA/GroupB/GroupC`, if they don't already exist.
2810 If the specified path describes a group that already exists, no error is
2811 raised.
2812
2813 The return value is a [Group](#Group) class instance."""
2814 # if group specified as a path, split out group names
2815 groupname = posixpath.normpath(groupname)
2816 nestedgroups = groupname.split('/')
2817 group = self
2818 # loop over group names, create parent groups if they do not already
2819 # exist.
2820 for g in nestedgroups:
2821 if not g: continue
2822 if g not in group.groups:
2823 group.groups[g] = Group(group, g)
2824 group = group.groups[g]
2825 # if group already exists, just return the group
2826 # (prior to 1.1.8, this would have raised an error)
2827 return group
2828
2829 def ncattrs(self):
2830 """
2831 **`ncattrs(self)`**
2832
2833 return netCDF global attribute names for this [Dataset](#Dataset) or [Group](#Group) in a list."""
2834 return _get_att_names(self._grpid, NC_GLOBAL)
2835
2836 def setncattr(self,name,value):
2837 """
2838 **`setncattr(self,name,value)`**
2839
2840 set a netCDF dataset or group attribute using name,value pair.
2841 Use if you need to set a netCDF attribute with the
2842 with the same name as one of the reserved python attributes."""
2843 cdef nc_type xtype
2844 xtype=-99
2845 if self.data_model != 'NETCDF4': self._redef()
2846 _set_att(self, NC_GLOBAL, name, value, xtype=xtype, force_ncstring=self._ncstring_attrs__)
2847 if self.data_model != 'NETCDF4': self._enddef()
2848
2849 def setncattr_string(self,name,value):
2850 """
2851 **`setncattr_string(self,name,value)`**
2852
2853 set a netCDF dataset or group string attribute using name,value pair.
2854 Use if you need to ensure that a netCDF attribute is created with type
2855 `NC_STRING` if the file format is `NETCDF4`."""
2856 cdef nc_type xtype
2857 xtype=-99
2858 if self.data_model != 'NETCDF4':
2859 msg='file format does not support NC_STRING attributes'
2860 raise IOError(msg)
2861 _set_att(self, NC_GLOBAL, name, value, xtype=xtype, force_ncstring=True)
2862
2863 def setncatts(self,attdict):
2864 """
2865 **`setncatts(self,attdict)`**
2866
2867 set a bunch of netCDF dataset or group attributes at once using a python dictionary.
2868 This may be faster when setting a lot of attributes for a `NETCDF3`
2869 formatted file, since nc_redef/nc_enddef is not called in between setting
2870 each attribute"""
2871 if self.data_model != 'NETCDF4': self._redef()
2872 for name, value in attdict.items():
2873 _set_att(self, NC_GLOBAL, name, value)
2874 if self.data_model != 'NETCDF4': self._enddef()
2875
2876 def getncattr(self,name,encoding='utf-8'):
2877 """
2878 **`getncattr(self,name)`**
2879
2880 retrieve a netCDF dataset or group attribute.
2881 Use if you need to get a netCDF attribute with the same
2882 name as one of the reserved python attributes.
2883
2884 option kwarg `encoding` can be used to specify the
2885 character encoding of a string attribute (default is `utf-8`)."""
2886 return _get_att(self, NC_GLOBAL, name, encoding=encoding)
2887
2888 def __delattr__(self,name):
2889 # if it's a netCDF attribute, remove it
2890 if name not in _private_atts:
2891 self.delncattr(name)
2892 else:
2893 raise AttributeError(
2894 "'%s' is one of the reserved attributes %s, cannot delete. Use delncattr instead." % (name, tuple(_private_atts)))
2895
2896 def delncattr(self, name):
2897 """
2898 **`delncattr(self,name,value)`**
2899
2900 delete a netCDF dataset or group attribute. Use if you need to delete a
2901 netCDF attribute with the same name as one of the reserved python
2902 attributes."""
2903 cdef char *attname
2904 cdef int ierr
2905 bytestr = _strencode(name)
2906 attname = bytestr
2907 if self.data_model != 'NETCDF4': self._redef()
2908 ierr = nc_del_att(self._grpid, NC_GLOBAL, attname)
2909 if self.data_model != 'NETCDF4': self._enddef()
2910 _ensure_nc_success(ierr)
2911
2912 def __setattr__(self,name,value):
2913 # if name in _private_atts, it is stored at the python
2914 # level and not in the netCDF file.
2915 if name not in _private_atts:
2916 self.setncattr(name, value)
2917 elif not name.endswith('__'):
2918 if hasattr(self,name):
2919 raise AttributeError(
2920 "'%s' is one of the reserved attributes %s, cannot rebind. Use setncattr instead." % (name, tuple(_private_atts)))
2921 else:
2922 self.__dict__[name]=value
2923
2924 def __getattr__(self,name):
2925 # if name in _private_atts, it is stored at the python
2926 # level and not in the netCDF file.
2927 if name.startswith('__') and name.endswith('__'):
2928 # if __dict__ requested, return a dict with netCDF attributes.
2929 if name == '__dict__':
2930 names = self.ncattrs()
2931 values = []
2932 for name in names:
2933 values.append(_get_att(self, NC_GLOBAL, name))
2934 gen = zip(names, values)
2935 if sys.version_info[0:2] < (3, 7):
2936 return OrderedDict(gen)
2937 else:
2938 return dict(gen)
2939 else:
2940 raise AttributeError
2941 elif name in _private_atts:
2942 return self.__dict__[name]
2943 else:
2944 return self.getncattr(name)
2945
2946 def renameAttribute(self, oldname, newname):
2947 """
2948 **`renameAttribute(self, oldname, newname)`**
2949
2950 rename a [Dataset](#Dataset) or [Group](#Group) attribute named `oldname` to `newname`."""
2951 cdef char *oldnamec
2952 cdef char *newnamec
2953 bytestr = _strencode(oldname)
2954 oldnamec = bytestr
2955 bytestr = _strencode(newname)
2956 newnamec = bytestr
2957 _ensure_nc_success(nc_rename_att(self._grpid, NC_GLOBAL, oldnamec, newnamec))
2958
2959 def renameGroup(self, oldname, newname):
2960 """
2961 **`renameGroup(self, oldname, newname)`**
2962
2963 rename a [Group](#Group) named `oldname` to `newname` (requires netcdf >= 4.3.1)."""
2964 cdef char *newnamec
2965 IF HAS_RENAME_GRP:
2966 bytestr = _strencode(newname)
2967 newnamec = bytestr
2968 try:
2969 grp = self.groups[oldname]
2970 except KeyError:
2971 raise KeyError('%s not a valid group name' % oldname)
2972 _ensure_nc_success(nc_rename_grp(grp._grpid, newnamec))
2973 # remove old key from groups dict.
2974 self.groups.pop(oldname)
2975 # add new key.
2976 self.groups[newname] = grp
2977 ELSE:
2978 msg = """
2979 renameGroup method not enabled. To enable, install Cython, make sure you have
2980 version 4.3.1 or higher of the netcdf C lib, and rebuild netcdf4-python."""
2981 raise ValueError(msg)
2982
2983 def set_auto_chartostring(self, value):
2984 """
2985 **`set_auto_chartostring(self, True_or_False)`**
2986
2987 Call [Variable.set_auto_chartostring](#Variable.set_auto_chartostring) for all variables contained in this [Dataset](#Dataset) or
2988 [Group](#Group), as well as for all variables in all its subgroups.
2989
2990 **`True_or_False`**: Boolean determining if automatic conversion of
2991 all character arrays <--> string arrays should be performed for
2992 character variables (variables of type `NC_CHAR` or `S1`) with the
2993 `_Encoding` attribute set.
2994
2995 ***Note***: Calling this function only affects existing variables. Variables created
2996 after calling this function will follow the default behaviour.
2997 """
2998
2999 # this is a hack to make inheritance work in MFDataset
3000 # (which stores variables in _vars)
3001 _vars = self.variables
3002 if _vars is None: _vars = self._vars
3003 for var in _vars.values():
3004 var.set_auto_chartostring(value)
3005
3006 for groups in _walk_grps(self):
3007 for group in groups:
3008 for var in group.variables.values():
3009 var.set_auto_chartostring(value)
3010
3011 def set_auto_maskandscale(self, value):
3012 """
3013 **`set_auto_maskandscale(self, True_or_False)`**
3014
3015 Call [Variable.set_auto_maskandscale](#Variable.set_auto_maskandscale) for all variables contained in this [Dataset](#Dataset) or
3016 [Group](#Group), as well as for all variables in all its subgroups.
3017
3018 **`True_or_False`**: Boolean determining if automatic conversion to masked arrays
3019 and variable scaling shall be applied for all variables.
3020
3021 ***Note***: Calling this function only affects existing variables. Variables created
3022 after calling this function will follow the default behaviour.
3023 """
3024
3025 # this is a hack to make inheritance work in MFDataset
3026 # (which stores variables in _vars)
3027 _vars = self.variables
3028 if _vars is None: _vars = self._vars
3029 for var in _vars.values():
3030 var.set_auto_maskandscale(value)
3031
3032 for groups in _walk_grps(self):
3033 for group in groups:
3034 for var in group.variables.values():
3035 var.set_auto_maskandscale(value)
3036
3037
3038 def set_auto_mask(self, value):
3039 """
3040 **`set_auto_mask(self, True_or_False)`**
3041
3042 Call [Variable.set_auto_mask](#Variable.set_auto_mask) for all variables contained in this [Dataset](#Dataset) or
3043 [Group](#Group), as well as for all variables in all its subgroups.
3044
3045 **`True_or_False`**: Boolean determining if automatic conversion to masked arrays
3046 shall be applied for all variables.
3047
3048 ***Note***: Calling this function only affects existing variables. Variables created
3049 after calling this function will follow the default behaviour.
3050 """
3051
3052 # this is a hack to make inheritance work in MFDataset
3053 # (which stores variables in _vars)
3054 _vars = self.variables
3055 if _vars is None: _vars = self._vars
3056 for var in _vars.values():
3057 var.set_auto_mask(value)
3058
3059 for groups in _walk_grps(self):
3060 for group in groups:
3061 for var in group.variables.values():
3062 var.set_auto_mask(value)
3063
3064 def set_auto_scale(self, value):
3065 """
3066 **`set_auto_scale(self, True_or_False)`**
3067
3068 Call [Variable.set_auto_scale](#Variable.set_auto_scale) for all variables contained in this [Dataset](#Dataset) or
3069 [Group](#Group), as well as for all variables in all its subgroups.
3070
3071 **`True_or_False`**: Boolean determining if automatic variable scaling
3072 shall be applied for all variables.
3073
3074 ***Note***: Calling this function only affects existing variables. Variables created
3075 after calling this function will follow the default behaviour.
3076 """
3077
3078 # this is a hack to make inheritance work in MFDataset
3079 # (which stores variables in _vars)
3080 _vars = self.variables
3081 if _vars is None: _vars = self._vars
3082 for var in _vars.values():
3083 var.set_auto_scale(value)
3084
3085 for groups in _walk_grps(self):
3086 for group in groups:
3087 for var in group.variables.values():
3088 var.set_auto_scale(value)
3089
3090 def set_always_mask(self, value):
3091 """
3092 **`set_always_mask(self, True_or_False)`**
3093
3094 Call [Variable.set_always_mask](#Variable.set_always_mask) for all variables contained in
3095 this [Dataset](#Dataset) or [Group](#Group), as well as for all
3096 variables in all its subgroups.
3097
3098 **`True_or_False`**: Boolean determining if automatic conversion of
3099 masked arrays with no missing values to regular numpy arrays shall be
3100 applied for all variables. Default True. Set to False to restore the default behaviour
3101 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
3102 otherwise masked array returned).
3103
3104 ***Note***: Calling this function only affects existing
3105 variables. Variables created after calling this function will follow
3106 the default behaviour.
3107 """
3108
3109 # this is a hack to make inheritance work in MFDataset
3110 # (which stores variables in _vars)
3111 _vars = self.variables
3112 if _vars is None: _vars = self._vars
3113 for var in _vars.values():
3114 var.set_always_mask(value)
3115
3116 for groups in _walk_grps(self):
3117 for group in groups:
3118 for var in group.variables.values():
3119 var.set_always_mask(value)
3120
3121 def set_ncstring_attrs(self, value):
3122 """
3123 **`set_ncstring_attrs(self, True_or_False)`**
3124
3125 Call [Variable.set_ncstring_attrs](#Variable.set_ncstring_attrs) for all variables contained in
3126 this [Dataset](#Dataset) or [Group](#Group), as well as for all its
3127 subgroups and their variables.
3128
3129 **`True_or_False`**: Boolean determining if all string attributes are
3130 created as variable-length NC_STRINGs, (if True), or if ascii text
3131 attributes are stored as NC_CHARs (if False; default)
3132
3133 ***Note***: Calling this function only affects newly created attributes
3134 of existing (sub-) groups and their variables.
3135 """
3136
3137 self._ncstring_attrs__ = bool(value)
3138
3139 # this is a hack to make inheritance work in MFDataset
3140 # (which stores variables in _vars)
3141 _vars = self.variables
3142 if _vars is None:
3143 _vars = self._vars
3144 for var in _vars.values():
3145 var.set_ncstring_attrs(value)
3146
3147 for groups in _walk_grps(self):
3148 for group in groups:
3149 group.set_ncstring_attrs(value) # recurse into subgroups...
3150
3151 def get_variables_by_attributes(self, **kwargs):
3152 """
3153 **`get_variables_by_attribute(self, **kwargs)`**
3154
3155 Returns a list of variables that match specific conditions.
3156
3157 Can pass in key=value parameters and variables are returned that
3158 contain all of the matches. For example,
3159
3160 ```python
3161 >>> # Get variables with x-axis attribute.
3162 >>> vs = nc.get_variables_by_attributes(axis='X')
3163 >>> # Get variables with matching "standard_name" attribute
3164 >>> vs = nc.get_variables_by_attributes(standard_name='northward_sea_water_velocity')
3165 ```
3166
3167 Can pass in key=callable parameter and variables are returned if the
3168 callable returns True. The callable should accept a single parameter,
3169 the attribute value. None is given as the attribute value when the
3170 attribute does not exist on the variable. For example,
3171
3172 ```python
3173 >>> # Get Axis variables
3174 >>> vs = nc.get_variables_by_attributes(axis=lambda v: v in ['X', 'Y', 'Z', 'T'])
3175 >>> # Get variables that don't have an "axis" attribute
3176 >>> vs = nc.get_variables_by_attributes(axis=lambda v: v is None)
3177 >>> # Get variables that have a "grid_mapping" attribute
3178 >>> vs = nc.get_variables_by_attributes(grid_mapping=lambda v: v is not None)
3179 ```
3180 """
3181 vs = []
3182
3183 has_value_flag = False
3184 # this is a hack to make inheritance work in MFDataset
3185 # (which stores variables in _vars)
3186 _vars = self.variables
3187 if _vars is None: _vars = self._vars
3188 for vname in _vars:
3189 var = _vars[vname]
3190 for k, v in kwargs.items():
3191 if callable(v):
3192 has_value_flag = v(getattr(var, k, None))
3193 if has_value_flag is False:
3194 break
3195 elif hasattr(var, k) and getattr(var, k) == v:
3196 has_value_flag = True
3197 else:
3198 has_value_flag = False
3199 break
3200
3201 if has_value_flag is True:
3202 vs.append(_vars[vname])
3203
3204 return vs
3205
3206 def _getname(self):
3207 # private method to get name associated with instance.
3208 cdef int ierr
3209 cdef char namstring[NC_MAX_NAME+1]
3210 with nogil:
3211 ierr = nc_inq_grpname(self._grpid, namstring)
3212 _ensure_nc_success(ierr)
3213 return namstring.decode('utf-8')
3214
3215 property name:
3216 """string name of Group instance"""
3217 def __get__(self):
3218 return self._getname()
3219 def __set__(self,value):
3220 raise AttributeError("name cannot be altered")
3221
3222 @staticmethod
3223 def fromcdl(cdlfilename,ncfilename=None,mode='a',format='NETCDF4'):
3224 """
3225 **`fromcdl(cdlfilename, ncfilename=None, mode='a',format='NETCDF4')`**
3226
3227 call `ncgen` via subprocess to create Dataset from [CDL](https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_utilities_guide.html#cdl_guide)
3228 text representation. Requires `ncgen` to be installed and in `$PATH`.
3229
3230 **`cdlfilename`**: CDL file.
3231
3232 **`ncfilename`**: netCDF file to create. If not given, CDL filename with
3233 suffix replaced by `.nc` is used..
3234
3235 **`mode`**: Access mode to open Dataset (Default `'a'`).
3236
3237 **`format`**: underlying file format to use (one of `'NETCDF4',
3238 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC'`, `'NETCDF3_64BIT_OFFSET'` or
3239 `'NETCDF3_64BIT_DATA'`. Default `'NETCDF4'`.
3240
3241 Dataset instance for `ncfilename` is returned.
3242 """
3243 if ncfilename is None:
3244 filepath = pathlib.Path(cdlfilename)
3245 ncfilename = filepath.with_suffix('.nc')
3246 formatcodes = {'NETCDF4': 4,
3247 'NETCDF4_CLASSIC': 7,
3248 'NETCDF3_CLASSIC': 3,
3249 'NETCDF3_64BIT': 6, # legacy
3250 'NETCDF3_64BIT_OFFSET': 6,
3251 'NETCDF3_64BIT_DATA': 5}
3252 if format not in formatcodes:
3253 raise ValueError('illegal format requested')
3254 ncgenargs="-knc%s" % formatcodes[format]
3255 subprocess.run(["ncgen", ncgenargs, "-o", ncfilename, cdlfilename], check=True)
3256 return Dataset(ncfilename, mode=mode)
3257
3258 def tocdl(self,coordvars=False,data=False,outfile=None):
3259 """
3260 **`tocdl(self, coordvars=False, data=False, outfile=None)`**
3261
3262 call `ncdump` via subprocess to create [CDL](https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_utilities_guide.html#cdl_guide)
3263 text representation of Dataset. Requires `ncdump` to be installed and in `$PATH`.
3264
3265 **`coordvars`**: include coordinate variable data (via `ncdump -c`). Default False
3266
3267 **`data`**: if True, write out variable data (Default False).
3268
3269 **`outfile`**: If not None, file to output ncdump to. Default is to return a string.
3270 """
3271 self.sync()
3272 if coordvars:
3273 ncdumpargs = "-cs"
3274 else:
3275 ncdumpargs = "-s"
3276 if not data: ncdumpargs += "h"
3277 result=subprocess.run(["ncdump", ncdumpargs, self.filepath()],
3278 check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
3279 encoding='utf-8')
3280 if outfile is None:
3281 return result.stdout
3282 else:
3283 f = open(outfile,'w')
3284 f.write(result.stdout)
3285 f.close()
3286
3287 cdef class Group(Dataset):
3288 """
3289 Groups define a hierarchical namespace within a netCDF file. They are
3290 analogous to directories in a unix filesystem. Each [Group](#Group) behaves like
3291 a [Dataset](#Dataset) within a Dataset, and can contain it's own variables,
3292 dimensions and attributes (and other Groups). See [Group.__init__](#Group.__init__)
3293 for more details.
3294
3295 [Group](#Group) inherits from [Dataset](#Dataset), so all the
3296 [Dataset](#Dataset) class methods and variables are available
3297 to a [Group](#Group) instance (except the `close` method).
3298
3299 Additional read-only class variables:
3300
3301 **`name`**: String describing the group name.
3302 """
3303 def __init__(self, parent, name, **kwargs):
3304 """
3305 **`__init__(self, parent, name)`**
3306 [Group](#Group) constructor.
3307
3308 **`parent`**: [Group](#Group) instance for the parent group. If being created
3309 in the root group, use a [Dataset](#Dataset) instance.
3310
3311 **`name`**: - Name of the group.
3312
3313 ***Note***: [Group](#Group) instances should be created using the
3314 [Dataset.createGroup](#Dataset.createGroup) method of a [Dataset](#Dataset) instance, or
3315 another [Group](#Group) instance, not using this class directly.
3316 """
3317 cdef char *groupname
3318 # flag to indicate that Variables in this Group support orthogonal indexing.
3319 self.__orthogonal_indexing__ = True
3320 # set data_model and file_format attributes.
3321 self.data_model = parent.data_model
3322 self.file_format = parent.file_format
3323 # full path to Group.
3324 self.path = posixpath.join(parent.path, name)
3325 # parent group.
3326 self.parent = parent
3327 # propagate weak reference setting from parent.
3328 self.keepweakref = parent.keepweakref
3329 # propagate _ncstring_attrs__ setting from parent.
3330 self._ncstring_attrs__ = parent._ncstring_attrs__
3331 if 'id' in kwargs:
3332 self._grpid = kwargs['id']
3333 # get compound, vlen and enum types in this Group.
3334 self.cmptypes, self.vltypes, self.enumtypes = _get_types(self)
3335 # get dimensions in this Group.
3336 self.dimensions = _get_dims(self)
3337 # get variables in this Group.
3338 self.variables = _get_vars(self)
3339 # get groups in this Group.
3340 self.groups = _get_grps(self)
3341 else:
3342 bytestr = _strencode(name)
3343 groupname = bytestr
3344 _ensure_nc_success(nc_def_grp(parent._grpid, groupname, &self._grpid))
3345 if sys.version_info[0:2] < (3, 7):
3346 self.cmptypes = OrderedDict()
3347 self.vltypes = OrderedDict()
3348 self.enumtypes = OrderedDict()
3349 self.dimensions = OrderedDict()
3350 self.variables = OrderedDict()
3351 self.groups = OrderedDict()
3352 else:
3353 self.cmptypes = dict()
3354 self.vltypes = dict()
3355 self.enumtypes = dict()
3356 self.dimensions = dict()
3357 self.variables = dict()
3358 self.groups = dict()
3359
3360
3361 def close(self):
3362 """
3363 **`close(self)`**
3364
3365 overrides [Dataset](#Dataset) close method which does not apply to [Group](#Group)
3366 instances, raises IOError."""
3367 raise IOError('cannot close a [Group](#Group) (only applies to Dataset)')
3368
3369
3370 cdef class Dimension:
3371 """
3372 A netCDF [Dimension](#Dimension) is used to describe the coordinates of a [Variable](#Variable).
3373 See [Dimension.__init__](#Dimension.__init__) for more details.
3374
3375 The current maximum size of a [Dimension](#Dimension) instance can be obtained by
3376 calling the python `len` function on the [Dimension](#Dimension) instance. The
3377 [Dimension.isunlimited](#Dimension.isunlimited) method of a [Dimension](#Dimension) instance can be used to
3378 determine if the dimension is unlimited.
3379
3380 Read-only class variables:
3381
3382 **`name`**: String name, used when creating a [Variable](#Variable) with
3383 [Dataset.createVariable](#Dataset.createVariable).
3384
3385 **`size`**: Current [Dimension](#Dimension) size (same as `len(d)`, where `d` is a
3386 [Dimension](#Dimension) instance).
3387 """
3388 cdef public int _dimid, _grpid
3389 cdef public _data_model, _name, _grp
3390
3391 def __init__(self, grp, name, size=None, **kwargs):
3392 """
3393 **`__init__(self, group, name, size=None)`**
3394
3395 [Dimension](#Dimension) constructor.
3396
3397 **`group`**: [Group](#Group) instance to associate with dimension.
3398
3399 **`name`**: Name of the dimension.
3400
3401 **`size`**: Size of the dimension. `None` or 0 means unlimited. (Default `None`).
3402
3403 ***Note***: [Dimension](#Dimension) instances should be created using the
3404 [Dataset.createDimension](#Dataset.createDimension) method of a [Group](#Group) or
3405 [Dataset](#Dataset) instance, not using [Dimension.__init__](#Dimension.__init__) directly.
3406 """
3407 cdef int ierr
3408 cdef char *dimname
3409 cdef size_t lendim
3410 self._grpid = grp._grpid
3411 # make a weakref to group to avoid circular ref (issue 218)
3412 # keep strong reference the default behaviour (issue 251)
3413 if grp.keepweakref:
3414 self._grp = weakref.proxy(grp)
3415 else:
3416 self._grp = grp
3417 self._data_model = grp.data_model
3418 self._name = name
3419 if 'id' in kwargs:
3420 self._dimid = kwargs['id']
3421 else:
3422 bytestr = _strencode(name)
3423 dimname = bytestr
3424 if size is not None:
3425 lendim = size
3426 else:
3427 lendim = NC_UNLIMITED
3428 if grp.data_model != 'NETCDF4': grp._redef()
3429 ierr = nc_def_dim(self._grpid, dimname, lendim, &self._dimid)
3430 if grp.data_model != 'NETCDF4': grp._enddef()
3431 _ensure_nc_success(ierr)
3432
3433 def _getname(self):
3434 # private method to get name associated with instance.
3435 cdef int err, _grpid
3436 cdef char namstring[NC_MAX_NAME+1]
3437 _grpid = self._grp._grpid
3438 with nogil:
3439 ierr = nc_inq_dimname(_grpid, self._dimid, namstring)
3440 _ensure_nc_success(ierr)
3441 return namstring.decode('utf-8')
3442
3443 property name:
3444 """string name of Dimension instance"""
3445 def __get__(self):
3446 return self._getname()
3447 def __set__(self,value):
3448 raise AttributeError("name cannot be altered")
3449
3450 property size:
3451 """current size of Dimension (calls `len` on Dimension instance)"""
3452 def __get__(self):
3453 return len(self)
3454 def __set__(self,value):
3455 raise AttributeError("size cannot be altered")
3456
3457 def __repr__(self):
3458 return self.__unicode__()
3459
3460 def __unicode__(self):
3461 if not dir(self._grp):
3462 return 'Dimension object no longer valid'
3463 if self.isunlimited():
3464 return "%r (unlimited): name = '%s', size = %s" %\
3465 (type(self), self._name, len(self))
3466 else:
3467 return "%r: name = '%s', size = %s" %\
3468 (type(self), self._name, len(self))
3469
3470 def __len__(self):
3471 # len([Dimension](#Dimension) instance) returns current size of dimension
3472 cdef int ierr
3473 cdef size_t lengthp
3474 with nogil:
3475 ierr = nc_inq_dimlen(self._grpid, self._dimid, &lengthp)
3476 _ensure_nc_success(ierr)
3477 return lengthp
3478
3479 def group(self):
3480 """
3481 **`group(self)`**
3482
3483 return the group that this [Dimension](#Dimension) is a member of."""
3484 return self._grp
3485
3486 def isunlimited(self):
3487 """
3488 **`isunlimited(self)`**
3489
3490 returns `True` if the [Dimension](#Dimension) instance is unlimited, `False` otherwise."""
3491 cdef int ierr, n, numunlimdims, ndims, nvars, ngatts, xdimid
3492 cdef int *unlimdimids
3493 if self._data_model == 'NETCDF4':
3494 ierr = nc_inq_unlimdims(self._grpid, &numunlimdims, NULL)
3495 _ensure_nc_success(ierr)
3496 if numunlimdims == 0:
3497 return False
3498 else:
3499 unlimdimids = <int *>malloc(sizeof(int) * numunlimdims)
3500 dimid = self._dimid
3501 with nogil:
3502 ierr = nc_inq_unlimdims(self._grpid, &numunlimdims, unlimdimids)
3503 _ensure_nc_success(ierr)
3504 unlimdim_ids = []
3505 for n from 0 <= n < numunlimdims:
3506 unlimdim_ids.append(unlimdimids[n])
3507 free(unlimdimids)
3508 if dimid in unlimdim_ids:
3509 return True
3510 else:
3511 return False
3512 else: # if not NETCDF4, there is only one unlimited dimension.
3513 # nc_inq_unlimdims only works for NETCDF4.
3514 with nogil:
3515 ierr = nc_inq(self._grpid, &ndims, &nvars, &ngatts, &xdimid)
3516 if self._dimid == xdimid:
3517 return True
3518 else:
3519 return False
3520
3521 cdef class Variable:
3522 """
3523 A netCDF [Variable](#Variable) is used to read and write netCDF data. They are
3524 analogous to numpy array objects. See [Variable.__init__](#Variable.__init__) for more
3525 details.
3526
3527 A list of attribute names corresponding to netCDF attributes defined for
3528 the variable can be obtained with the [Variable.ncattrs](#Variable.ncattrs) method. These
3529 attributes can be created by assigning to an attribute of the
3530 [Variable](#Variable) instance. A dictionary containing all the netCDF attribute
3531 name/value pairs is provided by the `__dict__` attribute of a
3532 [Variable](#Variable) instance.
3533
3534 The following class variables are read-only:
3535
3536 **`dimensions`**: A tuple containing the names of the
3537 dimensions associated with this variable.
3538
3539 **`dtype`**: A numpy dtype object describing the
3540 variable's data type.
3541
3542 **`ndim`**: The number of variable dimensions.
3543
3544 **`shape`**: A tuple with the current shape (length of all dimensions).
3545
3546 **`scale`**: If True, `scale_factor` and `add_offset` are
3547 applied, and signed integer data is automatically converted to
3548 unsigned integer data if the `_Unsigned` attribute is set.
3549 Default is `True`, can be reset using [Variable.set_auto_scale](#Variable.set_auto_scale) and
3550 [Variable.set_auto_maskandscale](#Variable.set_auto_maskandscale) methods.
3551
3552 **`mask`**: If True, data is automatically converted to/from masked
3553 arrays when missing values or fill values are present. Default is `True`, can be
3554 reset using [Variable.set_auto_mask](#Variable.set_auto_mask) and [Variable.set_auto_maskandscale](#Variable.set_auto_maskandscale)
3555 methods.
3556
3557 **`chartostring`**: If True, data is automatically converted to/from character
3558 arrays to string arrays when the `_Encoding` variable attribute is set.
3559 Default is `True`, can be reset using
3560 [Variable.set_auto_chartostring](#Variable.set_auto_chartostring) method.
3561
3562 **`least_significant_digit`**: Describes the power of ten of the
3563 smallest decimal place in the data the contains a reliable value. Data is
3564 truncated to this decimal place when it is assigned to the [Variable](#Variable)
3565 instance. If `None`, the data is not truncated.
3566
3567 **`__orthogonal_indexing__`**: Always `True`. Indicates to client code
3568 that the object supports 'orthogonal indexing', which means that slices
3569 that are 1d arrays or lists slice along each dimension independently. This
3570 behavior is similar to Fortran or Matlab, but different than numpy.
3571
3572 **`datatype`**: numpy data type (for primitive data types) or VLType/CompoundType
3573 instance (for compound or vlen data types).
3574
3575 **`name`**: String name.
3576
3577 **`size`**: The number of stored elements.
3578 """
3579 cdef public int _varid, _grpid, _nunlimdim
3580 cdef public _name, ndim, dtype, mask, scale, always_mask, chartostring, _isprimitive, \
3581 _iscompound, _isvlen, _isenum, _grp, _cmptype, _vltype, _enumtype,\
3582 __orthogonal_indexing__, _has_lsd, _use_get_vars, _ncstring_attrs__
3583
3584 def __init__(self, grp, name, datatype, dimensions=(), zlib=False,
3585 complevel=4, shuffle=True, fletcher32=False, contiguous=False,
3586 chunksizes=None, endian='native', least_significant_digit=None,
3587 fill_value=None, chunk_cache=None, **kwargs):
3588 """
3589 **`__init__(self, group, name, datatype, dimensions=(), zlib=False,
3590 complevel=4, shuffle=True, fletcher32=False, contiguous=False,
3591 chunksizes=None, endian='native',
3592 least_significant_digit=None,fill_value=None,chunk_cache=None)`**
3593
3594 [Variable](#Variable) constructor.
3595
3596 **`group`**: [Group](#Group) or [Dataset](#Dataset) instance to associate with variable.
3597
3598 **`name`**: Name of the variable.
3599
3600 **`datatype`**: [Variable](#Variable) data type. Can be specified by providing a
3601 numpy dtype object, or a string that describes a numpy dtype object.
3602 Supported values, corresponding to `str` attribute of numpy dtype
3603 objects, include `'f4'` (32-bit floating point), `'f8'` (64-bit floating
3604 point), `'i4'` (32-bit signed integer), `'i2'` (16-bit signed integer),
3605 `'i8'` (64-bit signed integer), `'i4'` (8-bit signed integer), `'i1'`
3606 (8-bit signed integer), `'u1'` (8-bit unsigned integer), `'u2'` (16-bit
3607 unsigned integer), `'u4'` (32-bit unsigned integer), `'u8'` (64-bit
3608 unsigned integer), or `'S1'` (single-character string). From
3609 compatibility with Scientific.IO.NetCDF, the old Numeric single character
3610 typecodes can also be used (`'f'` instead of `'f4'`, `'d'` instead of
3611 `'f8'`, `'h'` or `'s'` instead of `'i2'`, `'b'` or `'B'` instead of
3612 `'i1'`, `'c'` instead of `'S1'`, and `'i'` or `'l'` instead of
3613 `'i4'`). `datatype` can also be a [CompoundType](#CompoundType) instance
3614 (for a structured, or compound array), a [VLType](#VLType) instance
3615 (for a variable-length array), or the python `str` builtin
3616 (for a variable-length string array). Numpy string and unicode datatypes with
3617 length greater than one are aliases for `str`.
3618
3619 **`dimensions`**: a tuple containing the variable's dimension names
3620 (defined previously with `createDimension`). Default is an empty tuple
3621 which means the variable is a scalar (and therefore has no dimensions).
3622
3623 **`zlib`**: if `True`, data assigned to the [Variable](#Variable)
3624 instance is compressed on disk. Default `False`.
3625
3626 **`complevel`**: the level of zlib compression to use (1 is the fastest,
3627 but poorest compression, 9 is the slowest but best compression). Default 4.
3628 Ignored if `zlib=False`.
3629
3630 **`shuffle`**: if `True`, the HDF5 shuffle filter is applied
3631 to improve compression. Default `True`. Ignored if `zlib=False`.
3632
3633 **`fletcher32`**: if `True` (default `False`), the Fletcher32 checksum
3634 algorithm is used for error detection.
3635
3636 **`contiguous`**: if `True` (default `False`), the variable data is
3637 stored contiguously on disk. Default `False`. Setting to `True` for
3638 a variable with an unlimited dimension will trigger an error.
3639
3640 **`chunksizes`**: Can be used to specify the HDF5 chunksizes for each
3641 dimension of the variable. A detailed discussion of HDF chunking and I/O
3642 performance is available
3643 [here](http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html).
3644 Basically, you want the chunk size for each dimension to match as
3645 closely as possible the size of the data block that users will read
3646 from the file. `chunksizes` cannot be set if `contiguous=True`.
3647
3648 **`endian`**: Can be used to control whether the
3649 data is stored in little or big endian format on disk. Possible
3650 values are `little, big` or `native` (default). The library
3651 will automatically handle endian conversions when the data is read,
3652 but if the data is always going to be read on a computer with the
3653 opposite format as the one used to create the file, there may be
3654 some performance advantage to be gained by setting the endian-ness.
3655 For netCDF 3 files (that don't use HDF5), only `endian='native'` is allowed.
3656
3657 The `zlib, complevel, shuffle, fletcher32, contiguous` and `chunksizes`
3658 keywords are silently ignored for netCDF 3 files that do not use HDF5.
3659
3660 **`least_significant_digit`**: If specified, variable data will be
3661 truncated (quantized). In conjunction with `zlib=True` this produces
3662 'lossy', but significantly more efficient compression. For example, if
3663 `least_significant_digit=1`, data will be quantized using
3664 around(scale*data)/scale, where scale = 2**bits, and bits is determined
3665 so that a precision of 0.1 is retained (in this case bits=4). Default is
3666 `None`, or no quantization.
3667
3668 **`fill_value`**: If specified, the default netCDF `_FillValue` (the
3669 value that the variable gets filled with before any data is written to it)
3670 is replaced with this value. If fill_value is set to `False`, then
3671 the variable is not pre-filled. The default netCDF fill values can be found
3672 in [default_fillvals](#default_fillvals).
3673
3674 **`chunk_cache`**: If specified, sets the chunk cache size for this variable.
3675 Persists as long as Dataset is open. Use [set_var_chunk_cache](#set_var_chunk_cache) to
3676 change it when Dataset is re-opened.
3677
3678 ***Note***: [Variable](#Variable) instances should be created using the
3679 [Dataset.createVariable](#Dataset.createVariable) method of a [Dataset](#Dataset) or
3680 [Group](#Group) instance, not using this class directly.
3681 """
3682 cdef int ierr, ndims, icontiguous, ideflate_level, numdims, _grpid
3683 cdef char namstring[NC_MAX_NAME+1]
3684 cdef char *varname
3685 cdef nc_type xtype
3686 cdef int *dimids
3687 cdef size_t sizep, nelemsp
3688 cdef size_t *chunksizesp
3689 cdef float preemptionp
3690 # flag to indicate that orthogonal indexing is supported
3691 self.__orthogonal_indexing__ = True
3692 # if complevel is set to zero, set zlib to False.
3693 if not complevel:
3694 zlib = False
3695 # if dimensions is a string, convert to a tuple
3696 # this prevents a common error that occurs when
3697 # dimensions = 'lat' instead of ('lat',)
3698 if type(dimensions) == str or type(dimensions) == bytes or type(dimensions) == unicode:
3699 dimensions = dimensions,
3700 self._grpid = grp._grpid
3701 # make a weakref to group to avoid circular ref (issue 218)
3702 # keep strong reference the default behaviour (issue 251)
3703 if grp.keepweakref:
3704 self._grp = weakref.proxy(grp)
3705 else:
3706 self._grp = grp
3707 user_type = isinstance(datatype, CompoundType) or \
3708 isinstance(datatype, VLType) or \
3709 isinstance(datatype, EnumType) or \
3710 datatype == str
3711 # convert to a real numpy datatype object if necessary.
3712 if not user_type and type(datatype) != numpy.dtype:
3713 datatype = numpy.dtype(datatype)
3714 # convert numpy string dtype with length > 1
3715 # or any numpy unicode dtype into str
3716 if (isinstance(datatype, numpy.dtype) and
3717 ((datatype.kind == 'S' and datatype.itemsize > 1) or
3718 datatype.kind == 'U')):
3719 datatype = str
3720 user_type = True
3721 # check if endian keyword consistent with datatype specification.
3722 dtype_endian = getattr(datatype,'byteorder',None)
3723 if dtype_endian == '=': dtype_endian='native'
3724 if dtype_endian == '>': dtype_endian='big'
3725 if dtype_endian == '<': dtype_endian='little'
3726 if dtype_endian == '|': dtype_endian=None
3727 if dtype_endian is not None and dtype_endian != endian:
3728 if dtype_endian == 'native' and endian == sys.byteorder:
3729 pass
3730 else:
3731 # endian keyword prevails, issue warning
3732 msg = 'endian-ness of dtype and endian kwarg do not match, using endian kwarg'
3733 #msg = 'endian-ness of dtype and endian kwarg do not match, dtype over-riding endian kwarg'
3734 warnings.warn(msg)
3735 #endian = dtype_endian # dtype prevails
3736 # check validity of datatype.
3737 self._isprimitive = False
3738 self._iscompound = False
3739 self._isvlen = False
3740 self._isenum = False
3741 if user_type:
3742 if isinstance(datatype, CompoundType):
3743 self._iscompound = True
3744 self._cmptype = datatype
3745 if isinstance(datatype, VLType) or datatype==str:
3746 self._isvlen = True
3747 self._vltype = datatype
3748 if isinstance(datatype, EnumType):
3749 self._isenum = True
3750 self._enumtype = datatype
3751 if datatype==str:
3752 if grp.data_model != 'NETCDF4':
3753 raise ValueError(
3754 'Variable length strings are only supported for the '
3755 'NETCDF4 format. For other formats, consider using '
3756 'netCDF4.stringtochar to convert string arrays into '
3757 'character arrays with an additional dimension.')
3758 datatype = VLType(self._grp, str, None)
3759 self._vltype = datatype
3760 xtype = datatype._nc_type
3761 # make sure this a valid user defined datatype defined in this Group
3762 ierr = nc_inq_type(self._grpid, xtype, namstring, NULL)
3763 _ensure_nc_success(ierr)
3764 # dtype variable attribute is a numpy datatype object.
3765 self.dtype = datatype.dtype
3766 elif datatype.str[1:] in _supportedtypes:
3767 self._isprimitive = True
3768 # find netCDF primitive data type corresponding to
3769 # specified numpy data type.
3770 xtype = _nptonctype[datatype.str[1:]]
3771 # dtype variable attribute is a numpy datatype object.
3772 self.dtype = datatype
3773 else:
3774 raise TypeError('illegal primitive data type, must be one of %s, got %s' % (_supportedtypes,datatype))
3775 if 'id' in kwargs:
3776 self._varid = kwargs['id']
3777 else:
3778 bytestr = _strencode(name)
3779 varname = bytestr
3780 ndims = len(dimensions)
3781 # find dimension ids.
3782 if ndims:
3783 dims = []
3784 dimids = <int *>malloc(sizeof(int) * ndims)
3785 for n from 0 <= n < ndims:
3786 dimname = dimensions[n]
3787 # look for dimension in this group, and if not
3788 # found there, look in parent (and it's parent, etc, back to root).
3789 dim = _find_dim(grp, dimname)
3790 if dim is None:
3791 raise KeyError("dimension %s not defined in group %s or any group in it's family tree" % (dimname, grp.path))
3792 dimids[n] = dim._dimid
3793 dims.append(dim)
3794 # go into define mode if it's a netCDF 3 compatible
3795 # file format. Be careful to exit define mode before
3796 # any exceptions are raised.
3797 if grp.data_model != 'NETCDF4': grp._redef()
3798 # define variable.
3799 if ndims:
3800 ierr = nc_def_var(self._grpid, varname, xtype, ndims,
3801 dimids, &self._varid)
3802 free(dimids)
3803 else: # a scalar variable.
3804 ierr = nc_def_var(self._grpid, varname, xtype, ndims,
3805 NULL, &self._varid)
3806 # set chunk cache size if desired
3807 # default is 1mb per var, can cause problems when many (1000's)
3808 # of vars are created. This change only lasts as long as file is
3809 # open.
3810 if grp.data_model.startswith('NETCDF4') and chunk_cache is not None:
3811 ierr = nc_get_var_chunk_cache(self._grpid, self._varid, &sizep,
3812 &nelemsp, &preemptionp)
3813 _ensure_nc_success(ierr)
3814 # reset chunk cache size, leave other parameters unchanged.
3815 sizep = chunk_cache
3816 ierr = nc_set_var_chunk_cache(self._grpid, self._varid, sizep,
3817 nelemsp, preemptionp)
3818 _ensure_nc_success(ierr)
3819 if ierr != NC_NOERR:
3820 if grp.data_model != 'NETCDF4': grp._enddef()
3821 _ensure_nc_success(ierr)
3822 # set zlib, shuffle, chunking, fletcher32 and endian
3823 # variable settings.
3824 # don't bother for NETCDF3* formats.
3825 # for NETCDF3* formats, the zlib,shuffle,chunking,
3826 # and fletcher32 are silently ignored. Only
3827 # endian='native' allowed for NETCDF3.
3828 if grp.data_model in ['NETCDF4','NETCDF4_CLASSIC']:
3829 # set zlib and shuffle parameters.
3830 if zlib and ndims: # don't bother for scalar variable
3831 ideflate_level = complevel
3832 if shuffle:
3833 ierr = nc_def_var_deflate(self._grpid, self._varid, 1, 1, ideflate_level)
3834 else:
3835 ierr = nc_def_var_deflate(self._grpid, self._varid, 0, 1, ideflate_level)
3836 if ierr != NC_NOERR:
3837 if grp.data_model != 'NETCDF4': grp._enddef()
3838 _ensure_nc_success(ierr)
3839 # set checksum.
3840 if fletcher32 and ndims: # don't bother for scalar variable
3841 ierr = nc_def_var_fletcher32(self._grpid, self._varid, 1)
3842 if ierr != NC_NOERR:
3843 if grp.data_model != 'NETCDF4': grp._enddef()
3844 _ensure_nc_success(ierr)
3845 # set chunking stuff.
3846 if ndims: # don't bother for scalar variable.
3847 if contiguous:
3848 icontiguous = NC_CONTIGUOUS
3849 if chunksizes is not None:
3850 raise ValueError('cannot specify chunksizes for a contiguous dataset')
3851 else:
3852 icontiguous = NC_CHUNKED
3853 if chunksizes is None:
3854 chunksizesp = NULL
3855 else:
3856 if len(chunksizes) != len(dimensions):
3857 if grp.data_model != 'NETCDF4': grp._enddef()
3858 raise ValueError('chunksizes must be a sequence with the same length as dimensions')
3859 chunksizesp = <size_t *>malloc(sizeof(size_t) * ndims)
3860 for n from 0 <= n < ndims:
3861 if not dims[n].isunlimited() and \
3862 chunksizes[n] > dims[n].size:
3863 msg = 'chunksize cannot exceed dimension size'
3864 raise ValueError(msg)
3865 chunksizesp[n] = chunksizes[n]
3866 if chunksizes is not None or contiguous:
3867 ierr = nc_def_var_chunking(self._grpid, self._varid, icontiguous, chunksizesp)
3868 free(chunksizesp)
3869 if ierr != NC_NOERR:
3870 if grp.data_model != 'NETCDF4': grp._enddef()
3871 _ensure_nc_success(ierr)
3872 # set endian-ness of variable
3873 if endian == 'little':
3874 ierr = nc_def_var_endian(self._grpid, self._varid, NC_ENDIAN_LITTLE)
3875 elif endian == 'big':
3876 ierr = nc_def_var_endian(self._grpid, self._varid, NC_ENDIAN_BIG)
3877 elif endian == 'native':
3878 pass # this is the default format.
3879 else:
3880 raise ValueError("'endian' keyword argument must be 'little','big' or 'native', got '%s'" % endian)
3881 if ierr != NC_NOERR:
3882 if grp.data_model != 'NETCDF4': grp._enddef()
3883 _ensure_nc_success(ierr)
3884 else:
3885 if endian != 'native':
3886 msg="only endian='native' allowed for NETCDF3 files"
3887 raise RuntimeError(msg)
3888 # set a fill value for this variable if fill_value keyword
3889 # given. This avoids the HDF5 overhead of deleting and
3890 # recreating the dataset if it is set later (after the enddef).
3891 if fill_value is not None:
3892 if not fill_value and isinstance(fill_value,bool):
3893 # no filling for this variable if fill_value==False.
3894 if not self._isprimitive:
3895 # no fill values for VLEN and compound variables
3896 # anyway.
3897 ierr = 0
3898 else:
3899 ierr = nc_def_var_fill(self._grpid, self._varid, 1, NULL)
3900 if ierr != NC_NOERR:
3901 if grp.data_model != 'NETCDF4': grp._enddef()
3902 _ensure_nc_success(ierr)
3903 else:
3904 if self._isprimitive or self._isenum or \
3905 (self._isvlen and self.dtype == str):
3906 if self._isvlen and self.dtype == str:
3907 _set_att(self._grp, self._varid, '_FillValue',\
3908 _tostr(fill_value), xtype=xtype, force_ncstring=True)
3909 else:
3910 fillval = numpy.array(fill_value, self.dtype)
3911 if not fillval.dtype.isnative: fillval.byteswap(True)
3912 _set_att(self._grp, self._varid, '_FillValue',\
3913 fillval, xtype=xtype)
3914 else:
3915 raise AttributeError("cannot set _FillValue attribute for VLEN or compound variable")
3916 if least_significant_digit is not None:
3917 self.least_significant_digit = least_significant_digit
3918 # leave define mode if not a NETCDF4 format file.
3919 if grp.data_model != 'NETCDF4': grp._enddef()
3920 # count how many unlimited dimensions there are.
3921 self._nunlimdim = 0
3922 for dimname in dimensions:
3923 # look in current group, and parents for dim.
3924 dim = _find_dim(self._grp, dimname)
3925 if dim.isunlimited(): self._nunlimdim = self._nunlimdim + 1
3926 # set ndim attribute (number of dimensions).
3927 with nogil:
3928 ierr = nc_inq_varndims(self._grpid, self._varid, &numdims)
3929 _ensure_nc_success(ierr)
3930 self.ndim = numdims
3931 self._name = name
3932 # default for automatically applying scale_factor and
3933 # add_offset, and converting to/from masked arrays is True.
3934 self.scale = True
3935 self.mask = True
3936 # issue 809: default for converting arrays with no missing values to
3937 # regular numpy arrays
3938 self.always_mask = True
3939 # default is to automatically convert to/from character
3940 # to string arrays when _Encoding variable attribute is set.
3941 self.chartostring = True
3942 # propagate _ncstring_attrs__ setting from parent group.
3943 self._ncstring_attrs__ = grp._ncstring_attrs__
3944 if 'least_significant_digit' in self.ncattrs():
3945 self._has_lsd = True
3946 # avoid calling nc_get_vars for strided slices by default.
3947 # a fix for strided slice access using HDF5 was added
3948 # in 4.6.2.
3949 # always use nc_get_vars for strided access with OpenDAP (issue #838).
3950 if __netcdf4libversion__ >= "4.6.2" or\
3951 self._grp.filepath().startswith('http'):
3952 self._use_get_vars = True
3953 else:
3954 self._use_get_vars = False
3955
3956 def __array__(self):
3957 # numpy special method that returns a numpy array.
3958 # allows numpy ufuncs to work faster on Variable objects
3959 # (issue 216).
3960 return self[...]
3961
3962 def __repr__(self):
3963 return self.__unicode__()
3964
3965 def __unicode__(self):
3966 cdef int ierr, no_fill
3967 if not dir(self._grp):
3968 return 'Variable object no longer valid'
3969 ncdump = [repr(type(self))]
3970 show_more_dtype = True
3971 if self._iscompound:
3972 kind = 'compound'
3973 elif self._isvlen:
3974 kind = 'vlen'
3975 elif self._isenum:
3976 kind = 'enum'
3977 else:
3978 show_more_dtype = False
3979 kind = str(self.dtype)
3980 dimnames = tuple(_tostr(dimname) for dimname in self.dimensions)
3981 ncdump.append('%s %s(%s)' %\
3982 (kind, self._name, ', '.join(dimnames)))
3983 for name in self.ncattrs():
3984 ncdump.append(' %s: %s' % (name, self.getncattr(name)))
3985 if show_more_dtype:
3986 ncdump.append('%s data type: %s' % (kind, self.dtype))
3987 unlimdims = []
3988 for dimname in self.dimensions:
3989 dim = _find_dim(self._grp, dimname)
3990 if dim.isunlimited():
3991 unlimdims.append(dimname)
3992 if (self._grp.path != '/'): ncdump.append('path = %s' % self._grp.path)
3993 ncdump.append('unlimited dimensions: %s' % ', '.join(unlimdims))
3994 ncdump.append('current shape = %r' % (self.shape,))
3995 if __netcdf4libversion__ < '4.5.1' and\
3996 self._grp.file_format.startswith('NETCDF3'):
3997 # issue #908: no_fill not correct for NETCDF3 files before 4.5.1
3998 # before 4.5.1 there was no way to turn off filling on a
3999 # per-variable basis for classic files.
4000 no_fill=0
4001 else:
4002 with nogil:
4003 ierr = nc_inq_var_fill(self._grpid,self._varid,&no_fill,NULL)
4004 _ensure_nc_success(ierr)
4005 if self._isprimitive:
4006 if no_fill != 1:
4007 try:
4008 fillval = self._FillValue
4009 msg = 'filling on'
4010 except AttributeError:
4011 fillval = default_fillvals[self.dtype.str[1:]]
4012 if self.dtype.str[1:] in ['u1','i1']:
4013 msg = 'filling on, default _FillValue of %s ignored' % fillval
4014 else:
4015 msg = 'filling on, default _FillValue of %s used' % fillval
4016 ncdump.append(msg)
4017 else:
4018 ncdump.append('filling off')
4019
4020
4021 return '\n'.join(ncdump)
4022
4023 def _getdims(self):
4024 # Private method to get variables's dimension names
4025 cdef int ierr, numdims, n, nn
4026 cdef char namstring[NC_MAX_NAME+1]
4027 cdef int *dimids
4028 # get number of dimensions for this variable.
4029 with nogil:
4030 ierr = nc_inq_varndims(self._grpid, self._varid, &numdims)
4031 _ensure_nc_success(ierr)
4032 dimids = <int *>malloc(sizeof(int) * numdims)
4033 # get dimension ids.
4034 with nogil:
4035 ierr = nc_inq_vardimid(self._grpid, self._varid, dimids)
4036 _ensure_nc_success(ierr)
4037 # loop over dimensions, retrieve names.
4038 dimensions = ()
4039 for nn from 0 <= nn < numdims:
4040 with nogil:
4041 ierr = nc_inq_dimname(self._grpid, dimids[nn], namstring)
4042 _ensure_nc_success(ierr)
4043 name = namstring.decode('utf-8')
4044 dimensions = dimensions + (name,)
4045 free(dimids)
4046 return dimensions
4047
4048 def _getname(self):
4049 # Private method to get name associated with instance
4050 cdef int err, _grpid
4051 cdef char namstring[NC_MAX_NAME+1]
4052 _grpid = self._grp._grpid
4053 with nogil:
4054 ierr = nc_inq_varname(_grpid, self._varid, namstring)
4055 _ensure_nc_success(ierr)
4056 return namstring.decode('utf-8')
4057
4058 property name:
4059 """string name of Variable instance"""
4060 def __get__(self):
4061 return self._getname()
4062 def __set__(self,value):
4063 raise AttributeError("name cannot be altered")
4064
4065 property datatype:
4066 """numpy data type (for primitive data types) or
4067 VLType/CompoundType/EnumType instance
4068 (for compound, vlen or enum data types)"""
4069 def __get__(self):
4070 if self._iscompound:
4071 return self._cmptype
4072 elif self._isvlen:
4073 return self._vltype
4074 elif self._isenum:
4075 return self._enumtype
4076 elif self._isprimitive:
4077 return self.dtype
4078
4079 property shape:
4080 """find current sizes of all variable dimensions"""
4081 def __get__(self):
4082 shape = ()
4083 for dimname in self._getdims():
4084 # look in current group, and parents for dim.
4085 dim = _find_dim(self._grp,dimname)
4086 shape = shape + (len(dim),)
4087 return shape
4088 def __set__(self,value):
4089 raise AttributeError("shape cannot be altered")
4090
4091 property size:
4092 """Return the number of stored elements."""
4093 def __get__(self):
4094 # issue #957: add int since prod(())=1.0
4095 return int(numpy.prod(self.shape))
4096
4097 property dimensions:
4098 """get variables's dimension names"""
4099 def __get__(self):
4100 return self._getdims()
4101 def __set__(self,value):
4102 raise AttributeError("dimensions cannot be altered")
4103
4104
4105 def group(self):
4106 """
4107 **`group(self)`**
4108
4109 return the group that this [Variable](#Variable) is a member of."""
4110 return self._grp
4111
4112 def ncattrs(self):
4113 """
4114 **`ncattrs(self)`**
4115
4116 return netCDF attribute names for this [Variable](#Variable) in a list."""
4117 return _get_att_names(self._grpid, self._varid)
4118
4119 def setncattr(self,name,value):
4120 """
4121 **`setncattr(self,name,value)`**
4122
4123 set a netCDF variable attribute using name,value pair. Use if you need to set a
4124 netCDF attribute with the same name as one of the reserved python
4125 attributes."""
4126 cdef nc_type xtype
4127 xtype=-99
4128 # issue #959 - trying to set _FillValue results in mysterious
4129 # error when close method is called so catch it here. It is
4130 # already caught in __setattr__.
4131 if name == '_FillValue':
4132 msg='_FillValue attribute must be set when variable is '+\
4133 'created (using fill_value keyword to createVariable)'
4134 raise AttributeError(msg)
4135 if self._grp.data_model != 'NETCDF4': self._grp._redef()
4136 _set_att(self._grp, self._varid, name, value, xtype=xtype, force_ncstring=self._ncstring_attrs__)
4137 if self._grp.data_model != 'NETCDF4': self._grp._enddef()
4138
4139 def setncattr_string(self,name,value):
4140 """
4141 **`setncattr_string(self,name,value)`**
4142
4143 set a netCDF variable string attribute using name,value pair.
4144 Use if you need to ensure that a netCDF attribute is created with type
4145 `NC_STRING` if the file format is `NETCDF4`.
4146 Use if you need to set an attribute to an array of variable-length strings."""
4147 cdef nc_type xtype
4148 xtype=-99
4149 if self._grp.data_model != 'NETCDF4':
4150 msg='file format does not support NC_STRING attributes'
4151 raise IOError(msg)
4152 _set_att(self._grp, self._varid, name, value, xtype=xtype, force_ncstring=True)
4153
4154 def setncatts(self,attdict):
4155 """
4156 **`setncatts(self,attdict)`**
4157
4158 set a bunch of netCDF variable attributes at once using a python dictionary.
4159 This may be faster when setting a lot of attributes for a `NETCDF3`
4160 formatted file, since nc_redef/nc_enddef is not called in between setting
4161 each attribute"""
4162 if self._grp.data_model != 'NETCDF4': self._grp._redef()
4163 for name, value in attdict.items():
4164 _set_att(self._grp, self._varid, name, value)
4165 if self._grp.data_model != 'NETCDF4': self._grp._enddef()
4166
4167 def getncattr(self,name,encoding='utf-8'):
4168 """
4169 **`getncattr(self,name)`**
4170
4171 retrieve a netCDF variable attribute. Use if you need to set a
4172 netCDF attribute with the same name as one of the reserved python
4173 attributes.
4174
4175 option kwarg `encoding` can be used to specify the
4176 character encoding of a string attribute (default is `utf-8`)."""
4177 return _get_att(self._grp, self._varid, name, encoding=encoding)
4178
4179 def delncattr(self, name):
4180 """
4181 **`delncattr(self,name,value)`**
4182
4183 delete a netCDF variable attribute. Use if you need to delete a
4184 netCDF attribute with the same name as one of the reserved python
4185 attributes."""
4186 cdef char *attname
4187 bytestr = _strencode(name)
4188 attname = bytestr
4189 if self._grp.data_model != 'NETCDF4': self._grp._redef()
4190 ierr = nc_del_att(self._grpid, self._varid, attname)
4191 if self._grp.data_model != 'NETCDF4': self._grp._enddef()
4192 _ensure_nc_success(ierr)
4193
4194 def filters(self):
4195 """
4196 **`filters(self)`**
4197
4198 return dictionary containing HDF5 filter parameters."""
4199 cdef int ierr,ideflate,ishuffle,ideflate_level,ifletcher32
4200 filtdict = {'zlib':False,'shuffle':False,'complevel':0,'fletcher32':False}
4201 if self._grp.data_model not in ['NETCDF4_CLASSIC','NETCDF4']: return
4202 with nogil:
4203 ierr = nc_inq_var_deflate(self._grpid, self._varid, &ishuffle, &ideflate, &ideflate_level)
4204 _ensure_nc_success(ierr)
4205 with nogil:
4206 ierr = nc_inq_var_fletcher32(self._grpid, self._varid, &ifletcher32)
4207 _ensure_nc_success(ierr)
4208 if ideflate:
4209 filtdict['zlib']=True
4210 filtdict['complevel']=ideflate_level
4211 if ishuffle:
4212 filtdict['shuffle']=True
4213 if ifletcher32:
4214 filtdict['fletcher32']=True
4215 return filtdict
4216
4217 def endian(self):
4218 """
4219 **`endian(self)`**
4220
4221 return endian-ness (`little,big,native`) of variable (as stored in HDF5 file)."""
4222 cdef int ierr, iendian
4223 if self._grp.data_model not in ['NETCDF4_CLASSIC','NETCDF4']:
4224 return 'native'
4225 with nogil:
4226 ierr = nc_inq_var_endian(self._grpid, self._varid, &iendian)
4227 _ensure_nc_success(ierr)
4228 if iendian == NC_ENDIAN_LITTLE:
4229 return 'little'
4230 elif iendian == NC_ENDIAN_BIG:
4231 return 'big'
4232 else:
4233 return 'native'
4234
4235 def chunking(self):
4236 """
4237 **`chunking(self)`**
4238
4239 return variable chunking information. If the dataset is
4240 defined to be contiguous (and hence there is no chunking) the word 'contiguous'
4241 is returned. Otherwise, a sequence with the chunksize for
4242 each dimension is returned."""
4243 cdef int ierr, icontiguous, ndims
4244 cdef size_t *chunksizesp
4245 if self._grp.data_model not in ['NETCDF4_CLASSIC','NETCDF4']: return None
4246 ndims = self.ndim
4247 chunksizesp = <size_t *>malloc(sizeof(size_t) * ndims)
4248 with nogil:
4249 ierr = nc_inq_var_chunking(self._grpid, self._varid, &icontiguous, chunksizesp)
4250 _ensure_nc_success(ierr)
4251 chunksizes=[]
4252 for n from 0 <= n < ndims:
4253 chunksizes.append(chunksizesp[n])
4254 free(chunksizesp)
4255 if icontiguous:
4256 return 'contiguous'
4257 else:
4258 return chunksizes
4259
4260 def get_var_chunk_cache(self):
4261 """
4262 **`get_var_chunk_cache(self)`**
4263
4264 return variable chunk cache information in a tuple (size,nelems,preemption).
4265 See netcdf C library documentation for `nc_get_var_chunk_cache` for
4266 details."""
4267 cdef int ierr
4268 cdef size_t sizep, nelemsp
4269 cdef float preemptionp
4270 with nogil:
4271 ierr = nc_get_var_chunk_cache(self._grpid, self._varid, &sizep,
4272 &nelemsp, &preemptionp)
4273 _ensure_nc_success(ierr)
4274 size = sizep; nelems = nelemsp; preemption = preemptionp
4275 return (size,nelems,preemption)
4276
4277 def set_var_chunk_cache(self,size=None,nelems=None,preemption=None):
4278 """
4279 **`set_var_chunk_cache(self,size=None,nelems=None,preemption=None)`**
4280
4281 change variable chunk cache settings.
4282 See netcdf C library documentation for `nc_set_var_chunk_cache` for
4283 details."""
4284 cdef int ierr
4285 cdef size_t sizep, nelemsp
4286 cdef float preemptionp
4287 # reset chunk cache size, leave other parameters unchanged.
4288 size_orig, nelems_orig, preemption_orig = self.get_var_chunk_cache()
4289 if size is not None:
4290 sizep = size
4291 else:
4292 sizep = size_orig
4293 if nelems is not None:
4294 nelemsp = nelems
4295 else:
4296 nelemsp = nelems_orig
4297 if preemption is not None:
4298 preemptionp = preemption
4299 else:
4300 preemptionp = preemption_orig
4301 ierr = nc_set_var_chunk_cache(self._grpid, self._varid, sizep,
4302 nelemsp, preemptionp)
4303 _ensure_nc_success(ierr)
4304
4305 def __delattr__(self,name):
4306 # if it's a netCDF attribute, remove it
4307 if name not in _private_atts:
4308 self.delncattr(name)
4309 else:
4310 raise AttributeError(
4311 "'%s' is one of the reserved attributes %s, cannot delete. Use delncattr instead." % (name, tuple(_private_atts)))
4312
4313 def __setattr__(self,name,value):
4314 # if name in _private_atts, it is stored at the python
4315 # level and not in the netCDF file.
4316 if name not in _private_atts:
4317 # if setting _FillValue or missing_value, make sure value
4318 # has same type and byte order as variable.
4319 if name == '_FillValue':
4320 msg='_FillValue attribute must be set when variable is '+\
4321 'created (using fill_value keyword to createVariable)'
4322 raise AttributeError(msg)
4323 #if self._isprimitive:
4324 # value = numpy.array(value, self.dtype)
4325 #else:
4326 # msg="cannot set _FillValue attribute for "+\
4327 # "VLEN or compound variable"
4328 # raise AttributeError(msg)
4329 elif name in ['valid_min','valid_max','valid_range','missing_value'] and self._isprimitive:
4330 # make sure these attributes written in same data type as variable.
4331 # also make sure it is written in native byte order
4332 # (the same as the data)
4333 valuea = numpy.array(value, self.dtype)
4334 # check to see if array cast is safe
4335 if _safecast(numpy.array(value),valuea):
4336 value = valuea
4337 if not value.dtype.isnative: value.byteswap(True)
4338 else: # otherwise don't do it, but issue a warning
4339 msg="WARNING: %s cannot be safely cast to variable dtype" \
4340 % name
4341 warnings.warn(msg)
4342 self.setncattr(name, value)
4343 elif not name.endswith('__'):
4344 if hasattr(self,name):
4345 raise AttributeError(
4346 "'%s' is one of the reserved attributes %s, cannot rebind. Use setncattr instead." % (name, tuple(_private_atts)))
4347 else:
4348 self.__dict__[name]=value
4349
4350 def __getattr__(self,name):
4351 # if name in _private_atts, it is stored at the python
4352 # level and not in the netCDF file.
4353 if name.startswith('__') and name.endswith('__'):
4354 # if __dict__ requested, return a dict with netCDF attributes.
4355 if name == '__dict__':
4356 names = self.ncattrs()
4357 values = []
4358 for name in names:
4359 values.append(_get_att(self._grp, self._varid, name))
4360 gen = zip(names, values)
4361 if sys.version_info[0:2] < (3, 7):
4362 return OrderedDict(gen)
4363 else:
4364 return dict(gen)
4365
4366 else:
4367 raise AttributeError
4368 elif name in _private_atts:
4369 return self.__dict__[name]
4370 else:
4371 return self.getncattr(name)
4372
4373 def renameAttribute(self, oldname, newname):
4374 """
4375 **`renameAttribute(self, oldname, newname)`**
4376
4377 rename a [Variable](#Variable) attribute named `oldname` to `newname`."""
4378 cdef int ierr
4379 cdef char *oldnamec
4380 cdef char *newnamec
4381 bytestr = _strencode(oldname)
4382 oldnamec = bytestr
4383 bytestr = _strencode(newname)
4384 newnamec = bytestr
4385 ierr = nc_rename_att(self._grpid, self._varid, oldnamec, newnamec)
4386 _ensure_nc_success(ierr)
4387
4388 def __getitem__(self, elem):
4389 # This special method is used to index the netCDF variable
4390 # using the "extended slice syntax". The extended slice syntax
4391 # is a perfect match for the "start", "count" and "stride"
4392 # arguments to the nc_get_var() function, and is much more easy
4393 # to use.
4394 start, count, stride, put_ind =\
4395 _StartCountStride(elem,self.shape,dimensions=self.dimensions,grp=self._grp,use_get_vars=self._use_get_vars)
4396 datashape = _out_array_shape(count)
4397 if self._isvlen:
4398 data = numpy.empty(datashape, dtype='O')
4399 else:
4400 data = numpy.empty(datashape, dtype=self.dtype)
4401
4402 # Determine which dimensions need to be
4403 # squeezed (those for which elem is an integer scalar).
4404 # The convention used is that for those cases,
4405 # put_ind for this dimension is set to -1 by _StartCountStride.
4406 squeeze = data.ndim * [slice(None),]
4407 for i,n in enumerate(put_ind.shape[:-1]):
4408 if n == 1 and put_ind[...,i].ravel()[0] == -1:
4409 squeeze[i] = 0
4410
4411 # Reshape the arrays so we can iterate over them.
4412 start = start.reshape((-1, self.ndim or 1))
4413 count = count.reshape((-1, self.ndim or 1))
4414 stride = stride.reshape((-1, self.ndim or 1))
4415 put_ind = put_ind.reshape((-1, self.ndim or 1))
4416
4417 # Fill output array with data chunks.
4418 for (a,b,c,i) in zip(start, count, stride, put_ind):
4419 datout = self._get(a,b,c)
4420 if not hasattr(datout,'shape') or data.shape == datout.shape:
4421 data = datout
4422 else:
4423 shape = getattr(data[tuple(i)], 'shape', ())
4424 if self._isvlen and not len(self.dimensions):
4425 # special case of scalar VLEN
4426 data[0] = datout
4427 else:
4428 data[tuple(i)] = datout.reshape(shape)
4429
4430 # Remove extra singleton dimensions.
4431 if hasattr(data,'shape'):
4432 data = data[tuple(squeeze)]
4433 if hasattr(data,'ndim') and self.ndim == 0:
4434 # Make sure a numpy scalar array is returned instead of a 1-d array of
4435 # length 1.
4436 if data.ndim != 0: data = numpy.asarray(data[0])
4437
4438 # if auto_scale mode set to True, (through
4439 # a call to set_auto_scale or set_auto_maskandscale),
4440 # perform automatic unpacking using scale_factor/add_offset.
4441 # if auto_mask mode is set to True (through a call to
4442 # set_auto_mask or set_auto_maskandscale), perform
4443 # automatic conversion to masked array using
4444 # missing_value/_Fill_Value.
4445 # applied for primitive and (non-string) vlen,
4446 # ignored for compound and enum datatypes.
4447 try: # check to see if scale_factor and add_offset is valid (issue 176).
4448 if hasattr(self,'scale_factor'): float(self.scale_factor)
4449 if hasattr(self,'add_offset'): float(self.add_offset)
4450 valid_scaleoffset = True
4451 except:
4452 valid_scaleoffset = False
4453 if self.scale:
4454 msg = 'invalid scale_factor or add_offset attribute, no unpacking done...'
4455 warnings.warn(msg)
4456
4457 if self.mask and\
4458 (self._isprimitive or self._isenum or\
4459 (self._isvlen and self.dtype != str)):
4460 data = self._toma(data)
4461 else:
4462 # if attribute _Unsigned is True, and variable has signed integer
4463 # dtype, return view with corresponding unsigned dtype (issue #656)
4464 if self.scale: # only do this if autoscale option is on.
4465 is_unsigned = getattr(self, '_Unsigned', False)
4466 if is_unsigned and data.dtype.kind == 'i':
4467 data=data.view('%su%s'%(data.dtype.byteorder,data.dtype.itemsize))
4468
4469 if self.scale and\
4470 (self._isprimitive or (self._isvlen and self.dtype != str)) and\
4471 valid_scaleoffset:
4472 # if variable has scale_factor and add_offset attributes, apply
4473 # them.
4474 if hasattr(self, 'scale_factor') and hasattr(self, 'add_offset'):
4475 if self.add_offset != 0.0 or self.scale_factor != 1.0:
4476 data = data*self.scale_factor + self.add_offset
4477 else:
4478 data = data.astype(self.scale_factor.dtype) # issue 913
4479 # else if variable has only scale_factor attribute, rescale.
4480 elif hasattr(self, 'scale_factor') and self.scale_factor != 1.0:
4481 data = data*self.scale_factor
4482 # else if variable has only add_offset attribute, add offset.
4483 elif hasattr(self, 'add_offset') and self.add_offset != 0.0:
4484 data = data + self.add_offset
4485
4486 # if _Encoding is specified for a character variable, return
4487 # a numpy array of strings with one less dimension.
4488 if self.chartostring and getattr(self.dtype,'kind',None) == 'S' and\
4489 getattr(self.dtype,'itemsize',None) == 1:
4490 encoding = getattr(self,'_Encoding',None)
4491 # should this only be done if self.scale = True?
4492 # should there be some other way to disable this?
4493 if encoding is not None:
4494 # only try to return a string array if rightmost dimension of
4495 # sliced data matches rightmost dimension of char variable
4496 if len(data.shape) > 0 and data.shape[-1] == self.shape[-1]:
4497 # also make sure slice is along last dimension
4498 matchdim = True
4499 for cnt in count:
4500 if cnt[-1] != self.shape[-1]:
4501 matchdim = False
4502 break
4503 if matchdim:
4504 data = chartostring(data, encoding=encoding)
4505
4506 # if structure array contains char arrays, return view as strings
4507 # if _Encoding att set (issue #773)
4508 if self._iscompound and \
4509 self._cmptype.dtype != self._cmptype.dtype_view and \
4510 self.chartostring:
4511 # self.chartostring and getattr(self,'_Encoding',None) is not None:
4512 data = data.view(self._cmptype.dtype_view)
4513 return data
4514
4515 def _toma(self,data):
4516 cdef int ierr, no_fill
4517 # if attribute _Unsigned is True, and variable has signed integer
4518 # dtype, return view with corresponding unsigned dtype (issues #656,
4519 # #794)
4520 is_unsigned = getattr(self, '_Unsigned', False)
4521 is_unsigned_int = is_unsigned and data.dtype.kind == 'i'
4522 if self.scale and is_unsigned_int: # only do this if autoscale option is on.
4523 dtype_unsigned_int='%su%s' % (data.dtype.byteorder,data.dtype.itemsize)
4524 data = data.view(dtype_unsigned_int)
4525 # private function for creating a masked array, masking missing_values
4526 # and/or _FillValues.
4527 totalmask = numpy.zeros(data.shape, numpy.bool_)
4528 fill_value = None
4529 safe_missval = self._check_safecast('missing_value')
4530 if safe_missval:
4531 mval = numpy.array(self.missing_value, self.dtype)
4532 if self.scale and is_unsigned_int:
4533 mval = mval.view(dtype_unsigned_int)
4534 # create mask from missing values.
4535 mvalmask = numpy.zeros(data.shape, numpy.bool_)
4536 if mval.shape == (): # mval a scalar.
4537 mval = [mval] # make into iterable.
4538 for m in mval:
4539 # is scalar missing value a NaN?
4540 try:
4541 mvalisnan = numpy.isnan(m)
4542 except TypeError: # isnan fails on some dtypes (issue 206)
4543 mvalisnan = False
4544 if mvalisnan:
4545 mvalmask += numpy.isnan(data)
4546 else:
4547 mvalmask += data==m
4548 if mvalmask.any():
4549 # set fill_value for masked array
4550 # to missing_value (or 1st element
4551 # if missing_value is a vector).
4552 fill_value = mval[0]
4553 totalmask += mvalmask
4554 # set mask=True for data == fill value
4555 safe_fillval = self._check_safecast('_FillValue')
4556 if safe_fillval:
4557 fval = numpy.array(self._FillValue, self.dtype)
4558 if self.scale and is_unsigned_int:
4559 fval = fval.view(dtype_unsigned_int)
4560 # is _FillValue a NaN?
4561 try:
4562 fvalisnan = numpy.isnan(fval)
4563 except: # isnan fails on some dtypes (issue 202)
4564 fvalisnan = False
4565 if fvalisnan:
4566 mask = numpy.isnan(data)
4567 elif (data == fval).any():
4568 mask = data==fval
4569 else:
4570 mask = None
4571 if mask is not None:
4572 if fill_value is None:
4573 fill_value = fval
4574 totalmask += mask
4575 # issue 209: don't return masked array if variable filling
4576 # is disabled.
4577 else:
4578 if __netcdf4libversion__ < '4.5.1' and\
4579 self._grp.file_format.startswith('NETCDF3'):
4580 # issue #908: no_fill not correct for NETCDF3 files before 4.5.1
4581 # before 4.5.1 there was no way to turn off filling on a
4582 # per-variable basis for classic files.
4583 no_fill=0
4584 else:
4585 with nogil:
4586 ierr = nc_inq_var_fill(self._grpid,self._varid,&no_fill,NULL)
4587 _ensure_nc_success(ierr)
4588 # if no_fill is not 1, and not a byte variable, then use default fill value.
4589 # from http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-c/Fill-Values.html#Fill-Values
4590 # "If you need a fill value for a byte variable, it is recommended
4591 # that you explicitly define an appropriate _FillValue attribute, as
4592 # generic utilities such as ncdump will not assume a default fill
4593 # value for byte variables."
4594 # Explained here too:
4595 # http://www.unidata.ucar.edu/software/netcdf/docs/known_problems.html#ncdump_ubyte_fill
4596 # "There should be no default fill values when reading any byte
4597 # type, signed or unsigned, because the byte ranges are too
4598 # small to assume one of the values should appear as a missing
4599 # value unless a _FillValue attribute is set explicitly."
4600 if no_fill != 1 or self.dtype.str[1:] not in ['u1','i1']:
4601 fillval = numpy.array(default_fillvals[self.dtype.str[1:]],self.dtype)
4602 has_fillval = data == fillval
4603 # if data is an array scalar, has_fillval will be a boolean.
4604 # in that case convert to an array.
4605 if type(has_fillval) == bool: has_fillval=numpy.asarray(has_fillval)
4606 if has_fillval.any():
4607 if fill_value is None:
4608 fill_value = fillval
4609 mask=data==fillval
4610 totalmask += mask
4611 # set mask=True for data outside valid_min,valid_max.
4612 # (issue #576)
4613 validmin = None; validmax = None
4614 # if valid_range exists use that, otherwise
4615 # look for valid_min, valid_max. No special
4616 # treatment of byte data as described at
4617 # http://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html).
4618 safe_validrange = self._check_safecast('valid_range')
4619 safe_validmin = self._check_safecast('valid_min')
4620 safe_validmax = self._check_safecast('valid_max')
4621 if safe_validrange and self.valid_range.size == 2:
4622 validmin = numpy.array(self.valid_range[0], self.dtype)
4623 validmax = numpy.array(self.valid_range[1], self.dtype)
4624 else:
4625 if safe_validmin:
4626 validmin = numpy.array(self.valid_min, self.dtype)
4627 if safe_validmax:
4628 validmax = numpy.array(self.valid_max, self.dtype)
4629 if validmin is not None and self.scale and is_unsigned_int:
4630 validmin = validmin.view(dtype_unsigned_int)
4631 if validmax is not None and self.scale and is_unsigned_int:
4632 validmax = validmax.view(dtype_unsigned_int)
4633 # http://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html).
4634 # "If the data type is byte and _FillValue
4635 # is not explicitly defined,
4636 # then the valid range should include all possible values.
4637 # Otherwise, the valid range should exclude the _FillValue
4638 # (whether defined explicitly or by default) as follows.
4639 # If the _FillValue is positive then it defines a valid maximum,
4640 # otherwise it defines a valid minimum."
4641 byte_type = self.dtype.str[1:] in ['u1','i1']
4642 if safe_fillval:
4643 fval = numpy.array(self._FillValue, self.dtype)
4644 else:
4645 fval = numpy.array(default_fillvals[self.dtype.str[1:]],self.dtype)
4646 if byte_type: fval = None
4647 if self.dtype.kind != 'S': # don't set mask for character data
4648 # issues #761 and #748: setting valid_min/valid_max to the
4649 # _FillVaue is too surprising for many users (despite the
4650 # netcdf docs attribute best practices suggesting clients
4651 # should do this).
4652 #if validmin is None and (fval is not None and fval <= 0):
4653 # validmin = fval
4654 #if validmax is None and (fval is not None and fval > 0):
4655 # validmax = fval
4656 if validmin is not None:
4657 totalmask += data < validmin
4658 if validmax is not None:
4659 totalmask += data > validmax
4660 if fill_value is None and fval is not None:
4661 fill_value = fval
4662 # if all else fails, use default _FillValue as fill_value
4663 # for masked array.
4664 if fill_value is None:
4665 fill_value = default_fillvals[self.dtype.str[1:]]
4666 # create masked array with computed mask
4667 masked_values = bool(totalmask.any())
4668 if masked_values:
4669 data = ma.masked_array(data,mask=totalmask,fill_value=fill_value)
4670 else:
4671 # issue #785: always return masked array, if no values masked
4672 data = ma.masked_array(data)
4673 # issue 515 scalar array with mask=True should be converted
4674 # to numpy.ma.MaskedConstant to be consistent with slicing
4675 # behavior of masked arrays.
4676 if data.shape == () and data.mask.all():
4677 # return a scalar numpy masked constant not a 0-d masked array,
4678 # so that data == numpy.ma.masked.
4679 data = data[()] # changed from [...] (issue #662)
4680 elif not self.always_mask and not masked_values:
4681 # issue #809: return a regular numpy array if requested
4682 # and there are no missing values
4683 data = numpy.array(data, copy=False)
4684
4685 return data
4686
4687 def _pack(self,data):
4688 # pack non-masked values using scale_factor and add_offset
4689 if hasattr(self, 'scale_factor') and hasattr(self, 'add_offset'):
4690 data = (data - self.add_offset)/self.scale_factor
4691 if self.dtype.kind in 'iu': data = numpy.around(data)
4692 elif hasattr(self, 'scale_factor'):
4693 data = data/self.scale_factor
4694 if self.dtype.kind in 'iu': data = numpy.around(data)
4695 elif hasattr(self, 'add_offset'):
4696 data = data - self.add_offset
4697 if self.dtype.kind in 'iu': data = numpy.around(data)
4698 if ma.isMA(data):
4699 # if underlying data in masked regions of masked array
4700 # corresponds to missing values, don't fill masked array -
4701 # just use underlying data instead
4702 if hasattr(self, 'missing_value') and \
4703 numpy.all(numpy.in1d(data.data[data.mask],self.missing_value)):
4704 data = data.data
4705 else:
4706 if hasattr(self, 'missing_value'):
4707 # if missing value is a scalar, use it as fill_value.
4708 # if missing value is a vector, raise an exception
4709 # since we then don't know how to fill in masked values.
4710 if numpy.array(self.missing_value).shape == ():
4711 fillval = self.missing_value
4712 else:
4713 msg="cannot assign fill_value for masked array when missing_value attribute is not a scalar"
4714 raise RuntimeError(msg)
4715 if numpy.array(fillval).shape != ():
4716 fillval = fillval[0]
4717 elif hasattr(self, '_FillValue'):
4718 fillval = self._FillValue
4719 else:
4720 fillval = default_fillvals[self.dtype.str[1:]]
4721 # some versions of numpy have trouble handling
4722 # MaskedConstants when filling - this is is
4723 # a workaround (issue #850)
4724 if data.shape == (1,) and data.mask.all():
4725 data = numpy.array([fillval],self.dtype)
4726 else:
4727 data = data.filled(fill_value=fillval)
4728 if self.dtype != data.dtype:
4729 data = data.astype(self.dtype) # cast data to var type, if necessary.
4730 return data
4731
4732 def _assign_vlen(self, elem, data):
4733 """private method to assign data to a single item in a VLEN variable"""
4734 cdef size_t *startp
4735 cdef size_t *countp
4736 cdef int ndims, n
4737 cdef nc_vlen_t *vldata
4738 cdef char **strdata
4739 cdef ndarray data2
4740 if not self._isvlen:
4741 raise TypeError('_assign_vlen method only for use with VLEN variables')
4742 ndims = self.ndim
4743 msg="data can only be assigned to VLEN variables using integer indices"
4744 # check to see that elem is a tuple of integers.
4745 # handle negative integers.
4746 if _is_int(elem):
4747 if ndims > 1:
4748 raise IndexError(msg)
4749 if elem < 0:
4750 if self.shape[0]+elem >= 0:
4751 elem = self.shape[0]+elem
4752 else:
4753 raise IndexError("Illegal index")
4754 elif isinstance(elem, tuple):
4755 if len(elem) != ndims:
4756 raise IndexError("Illegal index")
4757 elemnew = []
4758 for n,e in enumerate(elem):
4759 if not _is_int(e):
4760 raise IndexError(msg)
4761 elif e < 0:
4762 enew = self.shape[n]+e
4763 if enew < 0:
4764 raise IndexError("Illegal index")
4765 else:
4766 elemnew.append(self.shape[n]+e)
4767 else:
4768 elemnew.append(e)
4769 elem = tuple(elemnew)
4770 else:
4771 raise IndexError(msg)
4772 # set start, count
4773 if isinstance(elem, tuple):
4774 start = list(elem)
4775 else:
4776 start = [elem]
4777 count = [1]*ndims
4778 startp = <size_t *>malloc(sizeof(size_t) * ndims)
4779 countp = <size_t *>malloc(sizeof(size_t) * ndims)
4780 for n from 0 <= n < ndims:
4781 startp[n] = start[n]
4782 countp[n] = count[n]
4783 if self.dtype == str: # VLEN string
4784 strdata = <char **>malloc(sizeof(char *))
4785 # use _Encoding attribute to specify string encoding - if
4786 # not given, use 'utf-8'.
4787 encoding = getattr(self,'_Encoding','utf-8')
4788 bytestr = _strencode(data,encoding=encoding)
4789 strdata[0] = bytestr
4790 ierr = nc_put_vara(self._grpid, self._varid,
4791 startp, countp, strdata)
4792 _ensure_nc_success(ierr)
4793 free(strdata)
4794 else: # regular VLEN
4795 if data.dtype != self.dtype:
4796 raise TypeError("wrong data type: should be %s, got %s" % (self.dtype,data.dtype))
4797 data2 = data
4798 vldata = <nc_vlen_t *>malloc(sizeof(nc_vlen_t))
4799 vldata[0].len = PyArray_SIZE(data2)
4800 vldata[0].p = PyArray_DATA(data2)
4801 ierr = nc_put_vara(self._grpid, self._varid,
4802 startp, countp, vldata)
4803 _ensure_nc_success(ierr)
4804 free(vldata)
4805 free(startp)
4806 free(countp)
4807
4808 def _check_safecast(self, attname):
4809 # check to see that variable attribute exists
4810 # can can be safely cast to variable data type.
4811 if hasattr(self, attname):
4812 att = numpy.array(self.getncattr(attname))
4813 else:
4814 return False
4815 atta = numpy.array(att, self.dtype)
4816 is_safe = _safecast(att,atta)
4817 if not is_safe:
4818 msg="""WARNING: %s not used since it
4819 cannot be safely cast to variable data type""" % attname
4820 warnings.warn(msg)
4821 return is_safe
4822
4823 def __setitem__(self, elem, data):
4824 # This special method is used to assign to the netCDF variable
4825 # using "extended slice syntax". The extended slice syntax
4826 # is a perfect match for the "start", "count" and "stride"
4827 # arguments to the nc_put_var() function, and is much more easy
4828 # to use.
4829
4830 # if _Encoding is specified for a character variable, convert
4831 # numpy array of strings to a numpy array of characters with one more
4832 # dimension.
4833 if self.chartostring and getattr(self.dtype,'kind',None) == 'S' and\
4834 getattr(self.dtype,'itemsize',None) == 1:
4835 # NC_CHAR variable
4836 encoding = getattr(self,'_Encoding',None)
4837 if encoding is not None:
4838 # _Encoding attribute is set
4839 # if data is a string or a bytes object, convert to a numpy string array
4840 # whose length is equal to the rightmost dimension of the
4841 # variable.
4842 if type(data) in [str,bytes]: data = numpy.asarray(data,dtype='S'+repr(self.shape[-1]))
4843 if data.dtype.kind in ['S','U'] and data.dtype.itemsize > 1:
4844 # if data is a numpy string array, convert it to an array
4845 # of characters with one more dimension.
4846 data = stringtochar(data, encoding=encoding)
4847
4848 # if structured data has strings (and _Encoding att set), create view as char arrays
4849 # (issue #773)
4850 if self._iscompound and \
4851 self._cmptype.dtype != self._cmptype.dtype_view and \
4852 _set_viewdtype(data.dtype) == self._cmptype.dtype_view and \
4853 self.chartostring:
4854 # self.chartostring and getattr(self,'_Encoding',None) is not None:
4855 # may need to cast input data to aligned type
4856 data = data.astype(self._cmptype.dtype_view).view(self._cmptype.dtype)
4857
4858 if self._isvlen: # if vlen, should be object array (don't try casting)
4859 if self.dtype == str:
4860 # for string vars, if data is not an array
4861 # assume it is a python string and raise an error
4862 # if it is an array, but not an object array.
4863 if not isinstance(data, numpy.ndarray):
4864 # issue 458, allow Ellipsis to be used for scalar var
4865 if type(elem) == type(Ellipsis) and not\
4866 len(self.dimensions): elem = 0
4867 self._assign_vlen(elem, data)
4868 return
4869 elif data.dtype.kind in ['S', 'U']:
4870 if ma.isMA(data):
4871 msg='masked arrays cannot be assigned by VLEN str slices'
4872 raise TypeError(msg)
4873 data = data.astype(object)
4874 elif data.dtype.kind != 'O':
4875 msg = ('only numpy string, unicode or object arrays can '
4876 'be assigned to VLEN str var slices')
4877 raise TypeError(msg)
4878 else:
4879 # for non-string vlen arrays, if data is not multi-dim, or
4880 # not an object array, assume it represents a single element
4881 # of the vlen var.
4882 if not isinstance(data, numpy.ndarray) or data.dtype.kind != 'O':
4883 # issue 458, allow Ellipsis to be used for scalar var
4884 if type(elem) == type(Ellipsis) and not\
4885 len(self.dimensions): elem = 0
4886 # pack as integers if desired.
4887 if self.scale:
4888 data = self._pack(data)
4889 self._assign_vlen(elem, data)
4890 return
4891
4892 # A numpy or masked array (or an object supporting the buffer interface) is needed.
4893 # Convert if necessary.
4894 if not ma.isMA(data) and not (hasattr(data,'data') and isinstance(data.data,memoryview)):
4895 # if auto scaling is to be done, don't cast to an integer yet.
4896 if self.scale and self.dtype.kind in 'iu' and \
4897 hasattr(self, 'scale_factor') or hasattr(self, 'add_offset'):
4898 data = numpy.array(data,numpy.float_)
4899 else:
4900 data = numpy.array(data,self.dtype)
4901
4902 # for Enum variable, make sure data is valid.
4903 if self._isenum:
4904 test = numpy.zeros(data.shape,numpy.bool_)
4905 if ma.isMA(data):
4906 # fix for new behaviour in numpy.ma in 1.13 (issue #662)
4907 for val in self.datatype.enum_dict.values():
4908 test += data.filled() == val
4909 else:
4910 for val in self.datatype.enum_dict.values():
4911 test += data == val
4912 if not numpy.all(test):
4913 msg="trying to assign illegal value to Enum variable"
4914 raise ValueError(msg)
4915
4916 start, count, stride, put_ind =\
4917 _StartCountStride(elem,self.shape,self.dimensions,self._grp,datashape=data.shape,put=True)
4918 datashape = _out_array_shape(count)
4919
4920 # if a numpy scalar, create an array of the right size
4921 # and fill with scalar values.
4922 if data.shape == ():
4923 data = numpy.tile(data,datashape)
4924 # reshape data array if needed to conform with start,count,stride.
4925 if data.ndim != len(datashape) or\
4926 (data.shape != datashape and data.ndim > 1): # issue #1083
4927 # create a view so shape in caller is not modified (issue 90)
4928 try: # if extra singleton dims, just reshape
4929 data = data.view()
4930 data.shape = tuple(datashape)
4931 except ValueError: # otherwise broadcast
4932 data = numpy.broadcast_to(data, datashape)
4933
4934 # Reshape these arrays so we can iterate over them.
4935 start = start.reshape((-1, self.ndim or 1))
4936 count = count.reshape((-1, self.ndim or 1))
4937 stride = stride.reshape((-1, self.ndim or 1))
4938 put_ind = put_ind.reshape((-1, self.ndim or 1))
4939
4940 # quantize data if least_significant_digit attribute
4941 # exists (improves compression).
4942 if self._has_lsd:
4943 data = _quantize(data,self.least_significant_digit)
4944
4945 if self.scale and self._isprimitive:
4946 # pack non-masked values using scale_factor and add_offset
4947 data = self._pack(data)
4948
4949 # Fill output array with data chunks.
4950 for (a,b,c,i) in zip(start, count, stride, put_ind):
4951 dataput = data[tuple(i)]
4952 if dataput.size == 0: continue # nothing to write
4953 # convert array scalar to regular array with one element.
4954 if dataput.shape == ():
4955 if self._isvlen:
4956 dataput=numpy.array(dataput,'O')
4957 else:
4958 dataput=numpy.array(dataput,dataput.dtype)
4959 self._put(dataput,a,b,c)
4960
4961
4962 def __len__(self):
4963 if not self.shape:
4964 raise TypeError('len() of unsized object')
4965 else:
4966 return self.shape[0]
4967
4968
4969 def assignValue(self,val):
4970 """
4971 **`assignValue(self, val)`**
4972
4973 assign a value to a scalar variable. Provided for compatibility with
4974 Scientific.IO.NetCDF, can also be done by assigning to an Ellipsis slice ([...])."""
4975 if len(self.dimensions):
4976 raise IndexError('to assign values to a non-scalar variable, use a slice')
4977 self[:]=val
4978
4979 def getValue(self):
4980 """
4981 **`getValue(self)`**
4982
4983 get the value of a scalar variable. Provided for compatibility with
4984 Scientific.IO.NetCDF, can also be done by slicing with an Ellipsis ([...])."""
4985 if len(self.dimensions):
4986 raise IndexError('to retrieve values from a non-scalar variable, use slicing')
4987 return self[slice(None)]
4988
4989 def set_auto_chartostring(self,chartostring):
4990 """
4991 **`set_auto_chartostring(self,chartostring)`**
4992
4993 turn on or off automatic conversion of character variable data to and
4994 from numpy fixed length string arrays when the `_Encoding` variable attribute
4995 is set.
4996
4997 If `chartostring` is set to `True`, when data is read from a character variable
4998 (dtype = `S1`) that has an `_Encoding` attribute, it is converted to a numpy
4999 fixed length unicode string array (dtype = `UN`, where `N` is the length
5000 of the the rightmost dimension of the variable). The value of `_Encoding`
5001 is the unicode encoding that is used to decode the bytes into strings.
5002
5003 When numpy string data is written to a variable it is converted back to
5004 indiviual bytes, with the number of bytes in each string equalling the
5005 rightmost dimension of the variable.
5006
5007 The default value of `chartostring` is `True`
5008 (automatic conversions are performed).
5009 """
5010 self.chartostring = bool(chartostring)
5011
5012 def use_nc_get_vars(self,use_nc_get_vars):
5013 """
5014 **`use_nc_get_vars(self,_use_get_vars)`**
5015
5016 enable the use of netcdf library routine `nc_get_vars`
5017 to retrieve strided variable slices. By default,
5018 `nc_get_vars` may not used by default (depending on the
5019 version of the netcdf-c library being used) since it may be
5020 slower than multiple calls to the unstrided read routine `nc_get_vara`.
5021 """
5022 self._use_get_vars = bool(use_nc_get_vars)
5023
5024 def set_auto_maskandscale(self,maskandscale):
5025 """
5026 **`set_auto_maskandscale(self,maskandscale)`**
5027
5028 turn on or off automatic conversion of variable data to and
5029 from masked arrays, automatic packing/unpacking of variable
5030 data using `scale_factor` and `add_offset` attributes and
5031 automatic conversion of signed integer data to unsigned integer
5032 data if the `_Unsigned` attribute exists.
5033
5034 If `maskandscale` is set to `True`, when data is read from a variable
5035 it is converted to a masked array if any of the values are exactly
5036 equal to the either the netCDF _FillValue or the value specified by the
5037 missing_value variable attribute. The fill_value of the masked array
5038 is set to the missing_value attribute (if it exists), otherwise
5039 the netCDF _FillValue attribute (which has a default value
5040 for each data type). When data is written to a variable, the masked
5041 array is converted back to a regular numpy array by replacing all the
5042 masked values by the missing_value attribute of the variable (if it
5043 exists). If the variable has no missing_value attribute, the _FillValue
5044 is used instead. If the variable has valid_min/valid_max and
5045 missing_value attributes, data outside the specified range will be
5046 set to missing_value.
5047
5048 If `maskandscale` is set to `True`, and the variable has a
5049 `scale_factor` or an `add_offset` attribute, then data read
5050 from that variable is unpacked using::
5051
5052 data = self.scale_factor*data + self.add_offset
5053
5054 When data is written to a variable it is packed using::
5055
5056 data = (data - self.add_offset)/self.scale_factor
5057
5058 If either scale_factor is present, but add_offset is missing, add_offset
5059 is assumed zero. If add_offset is present, but scale_factor is missing,
5060 scale_factor is assumed to be one.
5061 For more information on how `scale_factor` and `add_offset` can be
5062 used to provide simple compression, see the
5063 [PSL metadata conventions](http://www.esrl.noaa.gov/psl/data/gridded/conventions/cdc_netcdf_standard.shtml).
5064
5065 In addition, if `maskandscale` is set to `True`, and if the variable has an
5066 attribute `_Unsigned` set, and the variable has a signed integer data type,
5067 a view to the data is returned with the corresponding unsigned integer data type.
5068 This convention is used by the netcdf-java library to save unsigned integer
5069 data in `NETCDF3` or `NETCDF4_CLASSIC` files (since the `NETCDF3`
5070 data model does not have unsigned integer data types).
5071
5072 The default value of `maskandscale` is `True`
5073 (automatic conversions are performed).
5074 """
5075 self.scale = self.mask = bool(maskandscale)
5076
5077 def set_auto_scale(self,scale):
5078 """
5079 **`set_auto_scale(self,scale)`**
5080
5081 turn on or off automatic packing/unpacking of variable
5082 data using `scale_factor` and `add_offset` attributes.
5083 Also turns on and off automatic conversion of signed integer data
5084 to unsigned integer data if the variable has an `_Unsigned`
5085 attribute.
5086
5087 If `scale` is set to `True`, and the variable has a
5088 `scale_factor` or an `add_offset` attribute, then data read
5089 from that variable is unpacked using::
5090
5091 data = self.scale_factor*data + self.add_offset
5092
5093 When data is written to a variable it is packed using::
5094
5095 data = (data - self.add_offset)/self.scale_factor
5096
5097 If either scale_factor is present, but add_offset is missing, add_offset
5098 is assumed zero. If add_offset is present, but scale_factor is missing,
5099 scale_factor is assumed to be one.
5100 For more information on how `scale_factor` and `add_offset` can be
5101 used to provide simple compression, see the
5102 [PSL metadata conventions](http://www.esrl.noaa.gov/psl/data/gridded/conventions/cdc_netcdf_standard.shtml).
5103
5104 In addition, if `scale` is set to `True`, and if the variable has an
5105 attribute `_Unsigned` set, and the variable has a signed integer data type,
5106 a view to the data is returned with the corresponding unsigned integer datatype.
5107 This convention is used by the netcdf-java library to save unsigned integer
5108 data in `NETCDF3` or `NETCDF4_CLASSIC` files (since the `NETCDF3`
5109 data model does not have unsigned integer data types).
5110
5111 The default value of `scale` is `True`
5112 (automatic conversions are performed).
5113 """
5114 self.scale = bool(scale)
5115
5116 def set_auto_mask(self,mask):
5117 """
5118 **`set_auto_mask(self,mask)`**
5119
5120 turn on or off automatic conversion of variable data to and
5121 from masked arrays .
5122
5123 If `mask` is set to `True`, when data is read from a variable
5124 it is converted to a masked array if any of the values are exactly
5125 equal to the either the netCDF _FillValue or the value specified by the
5126 missing_value variable attribute. The fill_value of the masked array
5127 is set to the missing_value attribute (if it exists), otherwise
5128 the netCDF _FillValue attribute (which has a default value
5129 for each data type). When data is written to a variable, the masked
5130 array is converted back to a regular numpy array by replacing all the
5131 masked values by the missing_value attribute of the variable (if it
5132 exists). If the variable has no missing_value attribute, the _FillValue
5133 is used instead. If the variable has valid_min/valid_max and
5134 missing_value attributes, data outside the specified range will be
5135 set to missing_value.
5136
5137 The default value of `mask` is `True`
5138 (automatic conversions are performed).
5139 """
5140 self.mask = bool(mask)
5141
5142 def set_always_mask(self,always_mask):
5143 """
5144 **`set_always_mask(self,always_mask)`**
5145
5146 turn on or off conversion of data without missing values to regular
5147 numpy arrays.
5148
5149 `always_mask` is a Boolean determining if automatic conversion of
5150 masked arrays with no missing values to regular numpy arrays shall be
5151 applied. Default is True. Set to False to restore the default behaviour
5152 in versions prior to 1.4.1 (numpy array returned unless missing values are present,
5153 otherwise masked array returned).
5154 """
5155 self.always_mask = bool(always_mask)
5156
5157 def set_ncstring_attrs(self,ncstring_attrs):
5158 """
5159 **`set_always_mask(self,ncstring_attrs)`**
5160
5161 turn on or off creating NC_STRING string attributes.
5162
5163 If `ncstring_attrs` is set to `True` then text attributes will be variable-length
5164 NC_STRINGs.
5165
5166 The default value of `ncstring_attrs` is `False` (writing ascii text attributes as
5167 NC_CHAR).
5168
5169 """
5170 self._ncstring_attrs__ = bool(ncstring_attrs)
5171
5172 def _put(self,ndarray data,start,count,stride):
5173 """Private method to put data into a netCDF variable"""
5174 cdef int ierr, ndims
5175 cdef npy_intp totelem
5176 cdef size_t *startp
5177 cdef size_t *countp
5178 cdef ptrdiff_t *stridep
5179 cdef char **strdata
5180 cdef void* elptr
5181 cdef char* databuff
5182 cdef ndarray dataarr
5183 cdef nc_vlen_t *vldata
5184 # rank of variable.
5185 ndims = len(self.dimensions)
5186 # make sure data is contiguous.
5187 # if not, make a local copy.
5188 if not PyArray_ISCONTIGUOUS(data):
5189 data = data.copy()
5190 # fill up startp,countp,stridep.
5191 totelem = 1
5192 negstride = 0
5193 sl = []
5194 startp = <size_t *>malloc(sizeof(size_t) * ndims)
5195 countp = <size_t *>malloc(sizeof(size_t) * ndims)
5196 stridep = <ptrdiff_t *>malloc(sizeof(ptrdiff_t) * ndims)
5197 for n from 0 <= n < ndims:
5198 count[n] = abs(count[n]) # make -1 into +1
5199 countp[n] = count[n]
5200 # for neg strides, reverse order (then flip that axis after data read in)
5201 if stride[n] < 0:
5202 negstride = 1
5203 stridep[n] = -stride[n]
5204 startp[n] = start[n]+stride[n]*(count[n]-1)
5205 stride[n] = -stride[n]
5206 sl.append(slice(None, None, -1)) # this slice will reverse the data
5207 else:
5208 startp[n] = start[n]
5209 stridep[n] = stride[n]
5210 sl.append(slice(None,None, 1))
5211 totelem = totelem*countp[n]
5212 # check to see that size of data array is what is expected
5213 # for slice given.
5214 dataelem = PyArray_SIZE(data)
5215 if totelem != dataelem:
5216 raise IndexError('size of data array does not conform to slice')
5217 if negstride:
5218 # reverse data along axes with negative strides.
5219 data = data[tuple(sl)].copy() # make sure a copy is made.
5220 if self._isprimitive or self._iscompound or self._isenum:
5221 # primitive, enum or compound data type.
5222 # if data type of array doesn't match variable,
5223 # try to cast the data.
5224 if self.dtype != data.dtype:
5225 data = data.astype(self.dtype) # cast data, if necessary.
5226 # byte-swap data in numpy array so that is has native
5227 # endian byte order (this is what netcdf-c expects -
5228 # issue #554, pull request #555)
5229 if not data.dtype.isnative:
5230 data = data.byteswap()
5231 # strides all 1 or scalar variable, use put_vara (faster)
5232 if sum(stride) == ndims or ndims == 0:
5233 ierr = nc_put_vara(self._grpid, self._varid,
5234 startp, countp, PyArray_DATA(data))
5235 else:
5236 ierr = nc_put_vars(self._grpid, self._varid,
5237 startp, countp, stridep, PyArray_DATA(data))
5238 _ensure_nc_success(ierr)
5239 elif self._isvlen:
5240 if data.dtype.char !='O':
5241 raise TypeError('data to put in string variable must be an object array containing Python strings')
5242 # flatten data array.
5243 data = data.flatten()
5244 if self.dtype == str:
5245 # convert all elements from strings to bytes
5246 # use _Encoding attribute to specify string encoding - if
5247 # not given, use 'utf-8'.
5248 encoding = getattr(self,'_Encoding','utf-8')
5249 for n in range(data.shape[0]):
5250 data[n] = _strencode(data[n],encoding=encoding)
5251 # vlen string (NC_STRING)
5252 # loop over elements of object array, put data buffer for
5253 # each element in struct.
5254 # allocate struct array to hold vlen data.
5255 strdata = <char **>malloc(sizeof(char *)*totelem)
5256 for i from 0<=i<totelem:
5257 strdata[i] = data[i]
5258 # strides all 1 or scalar variable, use put_vara (faster)
5259 if sum(stride) == ndims or ndims == 0:
5260 ierr = nc_put_vara(self._grpid, self._varid,
5261 startp, countp, strdata)
5262 else:
5263 raise IndexError('strides must all be 1 for string variables')
5264 #ierr = nc_put_vars(self._grpid, self._varid,
5265 # startp, countp, stridep, strdata)
5266 _ensure_nc_success(ierr)
5267 free(strdata)
5268 else:
5269 # regular vlen.
5270 # loop over elements of object array, put data buffer for
5271 # each element in struct.
5272 databuff = PyArray_BYTES(<ndarray>data)
5273 # allocate struct array to hold vlen data.
5274 vldata = <nc_vlen_t *>malloc(<size_t>totelem*sizeof(nc_vlen_t))
5275 for i from 0<=i<totelem:
5276 elptr = (<void**>databuff)[0]
5277 dataarr = <ndarray>elptr
5278 if self.dtype != dataarr.dtype.str[1:]:
5279 #dataarr = dataarr.astype(self.dtype) # cast data, if necessary.
5280 # casting doesn't work ?? just raise TypeError
5281 raise TypeError("wrong data type in object array: should be %s, got %s" % (self.dtype,dataarr.dtype))
5282 vldata[i].len = PyArray_SIZE(dataarr)
5283 vldata[i].p = PyArray_DATA(dataarr)
5284 databuff = databuff + PyArray_STRIDES(data)[0]
5285 # strides all 1 or scalar variable, use put_vara (faster)
5286 if sum(stride) == ndims or ndims == 0:
5287 ierr = nc_put_vara(self._grpid, self._varid,
5288 startp, countp, vldata)
5289 else:
5290 raise IndexError('strides must all be 1 for vlen variables')
5291 #ierr = nc_put_vars(self._grpid, self._varid,
5292 # startp, countp, stridep, vldata)
5293 _ensure_nc_success(ierr)
5294 # free the pointer array.
5295 free(vldata)
5296 free(startp)
5297 free(countp)
5298 free(stridep)
5299
5300 def _get(self,start,count,stride):
5301 """Private method to retrieve data from a netCDF variable"""
5302 cdef int ierr, ndims
5303 cdef size_t *startp
5304 cdef size_t *countp
5305 cdef ptrdiff_t *stridep
5306 cdef ndarray data, dataarr
5307 cdef void *elptr
5308 cdef char **strdata
5309 cdef nc_vlen_t *vldata
5310 # if one of the counts is negative, then it is an index
5311 # and not a slice so the resulting array
5312 # should be 'squeezed' to remove the singleton dimension.
5313 shapeout = ()
5314 squeeze_out = False
5315 for lendim in count:
5316 if lendim == -1:
5317 shapeout = shapeout + (1,)
5318 squeeze_out = True
5319 else:
5320 shapeout = shapeout + (lendim,)
5321 # rank of variable.
5322 ndims = len(self.dimensions)
5323 # fill up startp,countp,stridep.
5324 negstride = 0
5325 sl = []
5326 startp = <size_t *>malloc(sizeof(size_t) * ndims)
5327 countp = <size_t *>malloc(sizeof(size_t) * ndims)
5328 stridep = <ptrdiff_t *>malloc(sizeof(ptrdiff_t) * ndims)
5329 for n from 0 <= n < ndims:
5330 count[n] = abs(count[n]) # make -1 into +1
5331 countp[n] = count[n]
5332 # for neg strides, reverse order (then flip that axis after data read in)
5333 if stride[n] < 0:
5334 negstride = 1
5335 stridep[n] = -stride[n]
5336 startp[n] = start[n]+stride[n]*(count[n]-1)
5337 stride[n] = -stride[n]
5338 sl.append(slice(None, None, -1)) # this slice will reverse the data
5339 else:
5340 startp[n] = start[n]
5341 stridep[n] = stride[n]
5342 sl.append(slice(None,None, 1))
5343 if self._isprimitive or self._iscompound or self._isenum:
5344 data = numpy.empty(shapeout, self.dtype)
5345 # strides all 1 or scalar variable, use get_vara (faster)
5346 # if count contains a zero element, no data is being read
5347 if 0 not in count:
5348 if sum(stride) == ndims or ndims == 0:
5349 with nogil:
5350 ierr = nc_get_vara(self._grpid, self._varid,
5351 startp, countp, PyArray_DATA(data))
5352 else:
5353 with nogil:
5354 ierr = nc_get_vars(self._grpid, self._varid,
5355 startp, countp, stridep,
5356 PyArray_DATA(data))
5357 else:
5358 ierr = 0
5359 if ierr == NC_EINVALCOORDS:
5360 raise IndexError('index exceeds dimension bounds')
5361 elif ierr != NC_NOERR:
5362 _ensure_nc_success(ierr)
5363 elif self._isvlen:
5364 # allocate array of correct primitive type.
5365 data = numpy.empty(shapeout, 'O')
5366 # flatten data array.
5367 data = data.flatten()
5368 totelem = PyArray_SIZE(data)
5369 if self.dtype == str:
5370 # vlen string (NC_STRING)
5371 # allocate pointer array to hold string data.
5372 strdata = <char **>malloc(sizeof(char *) * totelem)
5373 # strides all 1 or scalar variable, use get_vara (faster)
5374 if sum(stride) == ndims or ndims == 0:
5375 with nogil:
5376 ierr = nc_get_vara(self._grpid, self._varid,
5377 startp, countp, strdata)
5378 else:
5379 # FIXME: is this a bug in netCDF4?
5380 raise IndexError('strides must all be 1 for string variables')
5381 #ierr = nc_get_vars(self._grpid, self._varid,
5382 # startp, countp, stridep, strdata)
5383 if ierr == NC_EINVALCOORDS:
5384 raise IndexError
5385 elif ierr != NC_NOERR:
5386 _ensure_nc_success(ierr)
5387 # loop over elements of object array, fill array with
5388 # contents of strdata.
5389 # use _Encoding attribute to decode string to bytes - if
5390 # not given, use 'utf-8'.
5391 encoding = getattr(self,'_Encoding','utf-8')
5392 for i from 0<=i<totelem:
5393 if strdata[i]:
5394 data[i] = strdata[i].decode(encoding)
5395 else:
5396 data[i] = "" # issue 915
5397 # reshape the output array
5398 data = numpy.reshape(data, shapeout)
5399 # free string data internally allocated in netcdf C lib
5400 ierr = nc_free_string(totelem, strdata)
5401 # free the pointer array
5402 free(strdata)
5403 else:
5404 # regular vlen
5405 # allocate struct array to hold vlen data.
5406 vldata = <nc_vlen_t *>malloc(totelem*sizeof(nc_vlen_t))
5407 for i in range(totelem):
5408 vldata[i].len = 0
5409 vldata[i].p = <void*>0
5410 # strides all 1 or scalar variable, use get_vara (faster)
5411 if sum(stride) == ndims or ndims == 0:
5412 with nogil:
5413 ierr = nc_get_vara(self._grpid, self._varid,
5414 startp, countp, vldata)
5415 else:
5416 raise IndexError('strides must all be 1 for vlen variables')
5417 #ierr = nc_get_vars(self._grpid, self._varid,
5418 # startp, countp, stridep, vldata)
5419 if ierr == NC_EINVALCOORDS:
5420 raise IndexError
5421 elif ierr != NC_NOERR:
5422 _ensure_nc_success(ierr)
5423 # loop over elements of object array, fill array with
5424 # contents of vlarray struct, put array in object array.
5425 for i from 0<=i<totelem:
5426 arrlen = vldata[i].len
5427 dataarr = numpy.empty(arrlen, self.dtype)
5428 #dataarr.data = <char *>vldata[i].p
5429 memcpy(PyArray_DATA(dataarr), vldata[i].p, dataarr.nbytes)
5430 data[i] = dataarr
5431 # reshape the output array
5432 data = numpy.reshape(data, shapeout)
5433 # free vlen data internally allocated in netcdf C lib
5434 ierr = nc_free_vlens(totelem, vldata)
5435 # free the pointer array
5436 free(vldata)
5437 free(startp)
5438 free(countp)
5439 free(stridep)
5440 if negstride:
5441 # reverse data along axes with negative strides.
5442 data = data[tuple(sl)].copy() # make a copy so data is contiguous.
5443 # netcdf-c always returns data in native byte order,
5444 # regardless of variable endian-ness. Here we swap the
5445 # bytes if the variable dtype is not native endian, so the
5446 # dtype of the returned numpy array matches the variable dtype.
5447 # (pull request #555, issue #554).
5448 if not data.dtype.isnative:
5449 data.byteswap(True) # in-place byteswap
5450 if not self.dimensions:
5451 return data[0] # a scalar
5452 elif squeeze_out:
5453 return numpy.squeeze(data)
5454 else:
5455 return data
5456
5457 def set_collective(self, value):
5458 """
5459 **`set_collective(self,True_or_False)`**
5460
5461 turn on or off collective parallel IO access. Ignored if file is not
5462 open for parallel access.
5463 """
5464 IF HAS_PARALLEL4_SUPPORT or HAS_PNETCDF_SUPPORT:
5465 # set collective MPI IO mode on or off
5466 if value:
5467 ierr = nc_var_par_access(self._grpid, self._varid,
5468 NC_COLLECTIVE)
5469 else:
5470 ierr = nc_var_par_access(self._grpid, self._varid,
5471 NC_INDEPENDENT)
5472 _ensure_nc_success(ierr)
5473 ELSE:
5474 pass # does nothing
5475
5476 def get_dims(self):
5477 """
5478 **`get_dims(self)`**
5479
5480 return a tuple of [Dimension](#Dimension) instances associated with this
5481 [Variable](#Variable).
5482 """
5483 return tuple(_find_dim(self._grp, dim) for dim in self.dimensions)
5484
5485 def __reduce__(self):
5486 # raise error is user tries to pickle a Variable object.
5487 raise NotImplementedError('Variable is not picklable')
5488
5489 # Compound datatype support.
5490
5491 cdef class CompoundType:
5492 """
5493 A [CompoundType](#CompoundType) instance is used to describe a compound data
5494 type, and can be passed to the the [Dataset.createVariable](#Dataset.createVariable) method of
5495 a [Dataset](#Dataset) or [Group](#Group) instance.
5496 Compound data types map to numpy structured arrays.
5497 See [CompoundType.__init__](#CompoundType.__init__) for more details.
5498
5499 The instance variables `dtype` and `name` should not be modified by
5500 the user.
5501 """
5502 cdef public nc_type _nc_type
5503 cdef public dtype, dtype_view, name
5504 def __init__(self, grp, object dt, object dtype_name, **kwargs):
5505 """
5506 ***`__init__(group, datatype, datatype_name)`***
5507
5508 CompoundType constructor.
5509
5510 **`group`**: [Group](#Group) instance to associate with the compound datatype.
5511
5512 **`datatype`**: A numpy dtype object describing a structured (a.k.a record)
5513 array. Can be composed of homogeneous numeric or character data types, or
5514 other structured array data types.
5515
5516 **`datatype_name`**: a Python string containing a description of the
5517 compound data type.
5518
5519 ***Note 1***: When creating nested compound data types,
5520 the inner compound data types must already be associated with CompoundType
5521 instances (so create CompoundType instances for the innermost structures
5522 first).
5523
5524 ***Note 2***: [CompoundType](#CompoundType) instances should be created using the
5525 [Dataset.createCompoundType](#Dataset.createCompoundType)
5526 method of a [Dataset](#Dataset) or [Group](#Group) instance, not using this class directly.
5527 """
5528 cdef nc_type xtype
5529 # convert dt to a numpy datatype object
5530 # and make sure the isalignedstruct flag is set to True
5531 # (so padding is added to the fields to match what a
5532 # C compiler would output for a similar C-struct).
5533 # This is needed because nc_get_vara is
5534 # apparently expecting the data buffer to include
5535 # padding to match what a C struct would have.
5536 # (this may or may not be still true, but empirical
5537 # evidence suggests that segfaults occur if this
5538 # alignment step is skipped - see issue #705).
5539 # numpy string subdtypes (i.e. 'S80') are
5540 # automatically converted to character array
5541 # subtypes (i.e. ('S1',80)). If '_Encoding'
5542 # variable attribute is set, data will be converted
5543 # to and from the string array representation with views.
5544 dt = _set_alignment(numpy.dtype(dt))
5545 # create a view datatype for converting char arrays to/from strings
5546 dtview = _set_viewdtype(numpy.dtype(dt))
5547 if 'typeid' in kwargs:
5548 xtype = kwargs['typeid']
5549 else:
5550 xtype = _def_compound(grp, dt, dtype_name)
5551 self._nc_type = xtype
5552 self.dtype = dt
5553 self.dtype_view = dtview
5554 self.name = dtype_name
5555
5556 def __repr__(self):
5557 return self.__unicode__()
5558
5559 def __unicode__(self):
5560 return "%r: name = '%s', numpy dtype = %s" %\
5561 (type(self), self.name, self.dtype)
5562
5563 def __reduce__(self):
5564 # raise error is user tries to pickle a CompoundType object.
5565 raise NotImplementedError('CompoundType is not picklable')
5566
5567 def _set_alignment(dt):
5568 # recursively set alignment flag in nested structured data type
5569 names = dt.names; formats = []
5570 for name in names:
5571 fmt = dt.fields[name][0]
5572 if fmt.kind == 'V':
5573 if fmt.shape == ():
5574 dtx = _set_alignment(dt.fields[name][0])
5575 else:
5576 if fmt.subdtype[0].kind == 'V': # structured dtype
5577 raise TypeError('nested structured dtype arrays not supported')
5578 else:
5579 dtx = dt.fields[name][0]
5580 else:
5581 # convert character string elements to char arrays
5582 if fmt.kind == 'S' and fmt.itemsize != 1:
5583 dtx = numpy.dtype('(%s,)S1' % fmt.itemsize)
5584 else:
5585 # primitive data type
5586 dtx = dt.fields[name][0]
5587 formats.append(dtx)
5588 # leave out offsets, they will be re-computed to preserve alignment.
5589 dtype_dict = {'names':names,'formats':formats}
5590 return numpy.dtype(dtype_dict, align=True)
5591
5592 def _set_viewdtype(dt):
5593 # recursively change character array dtypes to string dtypes
5594 names = dt.names; formats = []
5595 for name in names:
5596 fmt = dt.fields[name][0]
5597 if fmt.kind == 'V':
5598 if fmt.shape == ():
5599 dtx = _set_viewdtype(dt.fields[name][0])
5600 else:
5601 if fmt.subdtype[0].kind == 'V': # structured dtype
5602 raise TypeError('nested structured dtype arrays not supported')
5603 elif fmt.subdtype[0].kind == 'S' and len(dt.fields[name][0].shape) == 1:
5604 lenchar = dt.fields[name][0].shape[0]
5605 dtx = numpy.dtype('S%s' % lenchar)
5606 else:
5607 dtx = dt.fields[name][0]
5608 else:
5609 # primitive data type
5610 dtx = dt.fields[name][0]
5611 formats.append(dtx)
5612 dtype_dict = {'names':names,'formats':formats}
5613 return numpy.dtype(dtype_dict, align=True)
5614
5615 cdef _def_compound(grp, object dt, object dtype_name):
5616 # private function used to construct a netcdf compound data type
5617 # from a numpy dtype object by CompoundType.__init__.
5618 cdef nc_type xtype, xtype_tmp
5619 cdef int ierr, ndims
5620 cdef size_t offset, size
5621 cdef char *namstring
5622 cdef char *nested_namstring
5623 cdef int *dim_sizes
5624 bytestr = _strencode(dtype_name)
5625 namstring = bytestr
5626 size = dt.itemsize
5627 ierr = nc_def_compound(grp._grpid, size, namstring, &xtype)
5628 _ensure_nc_success(ierr)
5629 names = list(dt.fields.keys())
5630 formats = [v[0] for v in dt.fields.values()]
5631 offsets = [v[1] for v in dt.fields.values()]
5632 # make sure entries in lists sorted by offset.
5633 # (don't know why this is necessary, but it is for version 4.0.1)
5634 names = _sortbylist(names, offsets)
5635 formats = _sortbylist(formats, offsets)
5636 offsets.sort()
5637 for name, format, offset in zip(names, formats, offsets):
5638 bytestr = _strencode(name)
5639 namstring = bytestr
5640 if format.kind != 'V': # scalar primitive type
5641 try:
5642 xtype_tmp = _nptonctype[format.str[1:]]
5643 except KeyError:
5644 raise ValueError('Unsupported compound type element')
5645 ierr = nc_insert_compound(grp._grpid, xtype, namstring,
5646 offset, xtype_tmp)
5647 _ensure_nc_success(ierr)
5648 else:
5649 if format.shape == (): # nested scalar compound type
5650 # find this compound type in this group or it's parents.
5651 xtype_tmp = _find_cmptype(grp, format)
5652 bytestr = _strencode(name)
5653 nested_namstring = bytestr
5654 ierr = nc_insert_compound(grp._grpid, xtype,\
5655 nested_namstring,\
5656 offset, xtype_tmp)
5657 _ensure_nc_success(ierr)
5658 else: # nested array compound element
5659 ndims = len(format.shape)
5660 dim_sizes = <int *>malloc(sizeof(int) * ndims)
5661 for n from 0 <= n < ndims:
5662 dim_sizes[n] = format.shape[n]
5663 if format.subdtype[0].kind != 'V': # primitive type.
5664 try:
5665 xtype_tmp = _nptonctype[format.subdtype[0].str[1:]]
5666 except KeyError:
5667 raise ValueError('Unsupported compound type element')
5668 ierr = nc_insert_array_compound(grp._grpid,xtype,namstring,
5669 offset,xtype_tmp,ndims,dim_sizes)
5670 _ensure_nc_success(ierr)
5671 else: # nested array compound type.
5672 raise TypeError('nested structured dtype arrays not supported')
5673 # this code is untested and probably does not work, disable
5674 # for now...
5675 # # find this compound type in this group or it's parents.
5676 # xtype_tmp = _find_cmptype(grp, format.subdtype[0])
5677 # bytestr = _strencode(name)
5678 # nested_namstring = bytestr
5679 # ierr = nc_insert_array_compound(grp._grpid,xtype,\
5680 # nested_namstring,\
5681 # offset,xtype_tmp,\
5682 # ndims,dim_sizes)
5683 # _ensure_nc_success(ierr)
5684 free(dim_sizes)
5685 return xtype
5686
5687 cdef _find_cmptype(grp, dtype):
5688 # look for data type in this group and it's parents.
5689 # return datatype id when found, if not found, raise exception.
5690 cdef nc_type xtype
5691 match = False
5692 for cmpname, cmpdt in grp.cmptypes.items():
5693 xtype = cmpdt._nc_type
5694 names1 = dtype.fields.keys()
5695 names2 = cmpdt.dtype.fields.keys()
5696 formats1 = [v[0] for v in dtype.fields.values()]
5697 formats2 = [v[0] for v in cmpdt.dtype.fields.values()]
5698 formats2v = [v[0] for v in cmpdt.dtype_view.fields.values()]
5699 # match names, formats, but not offsets (they may be changed
5700 # by netcdf lib).
5701 if names1==names2 and formats1==formats2 or (formats1 == formats2v):
5702 match = True
5703 break
5704 if not match:
5705 try:
5706 parent_grp = grp.parent
5707 except AttributeError:
5708 raise ValueError("cannot find compound type in this group or parent groups")
5709 if parent_grp is None:
5710 raise ValueError("cannot find compound type in this group or parent groups")
5711 else:
5712 xtype = _find_cmptype(parent_grp,dtype)
5713 return xtype
5714
5715 cdef _read_compound(group, nc_type xtype, endian=None):
5716 # read a compound data type id from an existing file,
5717 # construct a corresponding numpy dtype instance,
5718 # then use that to create a CompoundType instance.
5719 # called by _get_vars, _get_types and _get_att.
5720 # Calls itself recursively for nested compound types.
5721 cdef int ierr, nf, numdims, ndim, classp, _grpid
5722 cdef size_t nfields, offset
5723 cdef nc_type field_typeid
5724 cdef int *dim_sizes
5725 cdef char field_namstring[NC_MAX_NAME+1]
5726 cdef char cmp_namstring[NC_MAX_NAME+1]
5727 # get name and number of fields.
5728 _grpid = group._grpid
5729 with nogil:
5730 ierr = nc_inq_compound(_grpid, xtype, cmp_namstring, NULL, &nfields)
5731 _ensure_nc_success(ierr)
5732 name = cmp_namstring.decode('utf-8')
5733 # loop over fields.
5734 names = []
5735 formats = []
5736 offsets = []
5737 for nf from 0 <= nf < nfields:
5738 with nogil:
5739 ierr = nc_inq_compound_field(_grpid,
5740 xtype,
5741 nf,
5742 field_namstring,
5743 &offset,
5744 &field_typeid,
5745 &numdims,
5746 NULL)
5747 _ensure_nc_success(ierr)
5748 dim_sizes = <int *>malloc(sizeof(int) * numdims)
5749 with nogil:
5750 ierr = nc_inq_compound_field(_grpid,
5751 xtype,
5752 nf,
5753 field_namstring,
5754 &offset,
5755 &field_typeid,
5756 &numdims,
5757 dim_sizes)
5758 _ensure_nc_success(ierr)
5759 field_name = field_namstring.decode('utf-8')
5760 names.append(field_name)
5761 offsets.append(offset)
5762 # if numdims=0, not an array.
5763 field_shape = ()
5764 if numdims != 0:
5765 for ndim from 0 <= ndim < numdims:
5766 field_shape = field_shape + (dim_sizes[ndim],)
5767 free(dim_sizes)
5768 # check to see if this field is a nested compound type.
5769 try:
5770 field_type = _nctonptype[field_typeid]
5771 if endian is not None:
5772 format = endian + format
5773 except KeyError:
5774 with nogil:
5775 ierr = nc_inq_user_type(_grpid,
5776 field_typeid,NULL,NULL,NULL,NULL,&classp)
5777 if classp == NC_COMPOUND: # a compound type
5778 # recursively call this function?
5779 field_type = _read_compound(group, field_typeid, endian=endian)
5780 else:
5781 raise KeyError('compound field of an unsupported data type')
5782 if field_shape != ():
5783 formats.append((field_type,field_shape))
5784 else:
5785 formats.append(field_type)
5786 # make sure entries in lists sorted by offset.
5787 names = _sortbylist(names, offsets)
5788 formats = _sortbylist(formats, offsets)
5789 offsets.sort()
5790 # create a dict that can be converted into a numpy dtype.
5791 dtype_dict = {'names':names,'formats':formats,'offsets':offsets}
5792 return CompoundType(group, dtype_dict, name, typeid=xtype)
5793
5794 # VLEN datatype support.
5795
5796 cdef class VLType:
5797 """
5798 A [VLType](#VLType) instance is used to describe a variable length (VLEN) data
5799 type, and can be passed to the the [Dataset.createVariable](#Dataset.createVariable) method of
5800 a [Dataset](#Dataset) or [Group](#Group) instance. See
5801 [VLType.__init__](#VLType.__init__)for more details.
5802
5803 The instance variables `dtype` and `name` should not be modified by
5804 the user.
5805 """
5806 cdef public nc_type _nc_type
5807 cdef public dtype, name
5808 def __init__(self, grp, object dt, object dtype_name, **kwargs):
5809 """
5810 **`__init__(group, datatype, datatype_name)`**
5811
5812 VLType constructor.
5813
5814 **`group`**: [Group](#Group) instance to associate with the VLEN datatype.
5815
5816 **`datatype`**: An numpy dtype object describing the component type for the
5817 variable length array.
5818
5819 **`datatype_name`**: a Python string containing a description of the
5820 VLEN data type.
5821
5822 ***`Note`***: [VLType](#VLType) instances should be created using the
5823 [Dataset.createVLType](#Dataset.createVLType)
5824 method of a [Dataset](#Dataset) or [Group](#Group) instance, not using this class directly.
5825 """
5826 cdef nc_type xtype
5827 if 'typeid' in kwargs:
5828 xtype = kwargs['typeid']
5829 else:
5830 xtype, dt = _def_vlen(grp, dt, dtype_name)
5831 self._nc_type = xtype
5832 self.dtype = dt
5833 if dt == str:
5834 self.name = None
5835 else:
5836 self.name = dtype_name
5837
5838 def __repr__(self):
5839 return self.__unicode__()
5840
5841 def __unicode__(self):
5842 if self.dtype == str:
5843 return '%r: string type' % (type(self),)
5844 else:
5845 return "%r: name = '%s', numpy dtype = %s" %\
5846 (type(self), self.name, self.dtype)
5847
5848 def __reduce__(self):
5849 # raise error is user tries to pickle a VLType object.
5850 raise NotImplementedError('VLType is not picklable')
5851
5852 cdef _def_vlen(grp, object dt, object dtype_name):
5853 # private function used to construct a netcdf VLEN data type
5854 # from a numpy dtype object or python str object by VLType.__init__.
5855 cdef nc_type xtype, xtype_tmp
5856 cdef int ierr, ndims
5857 cdef size_t offset, size
5858 cdef char *namstring
5859 cdef char *nested_namstring
5860 if dt == str: # python string, use NC_STRING
5861 xtype = NC_STRING
5862 # dtype_name ignored
5863 else: # numpy datatype
5864 bytestr = _strencode(dtype_name)
5865 namstring = bytestr
5866 dt = numpy.dtype(dt) # convert to numpy datatype.
5867 if dt.str[1:] in _supportedtypes:
5868 # find netCDF primitive data type corresponding to
5869 # specified numpy data type.
5870 xtype_tmp = _nptonctype[dt.str[1:]]
5871 ierr = nc_def_vlen(grp._grpid, namstring, xtype_tmp, &xtype);
5872 _ensure_nc_success(ierr)
5873 else:
5874 raise KeyError("unsupported datatype specified for VLEN")
5875 return xtype, dt
5876
5877 cdef _read_vlen(group, nc_type xtype, endian=None):
5878 # read a VLEN data type id from an existing file,
5879 # construct a corresponding numpy dtype instance,
5880 # then use that to create a VLType instance.
5881 # called by _get_types, _get_vars.
5882 cdef int ierr, _grpid
5883 cdef size_t vlsize
5884 cdef nc_type base_xtype
5885 cdef char vl_namstring[NC_MAX_NAME+1]
5886 _grpid = group._grpid
5887 if xtype == NC_STRING:
5888 dt = str
5889 name = None
5890 else:
5891 with nogil:
5892 ierr = nc_inq_vlen(_grpid, xtype, vl_namstring, &vlsize, &base_xtype)
5893 _ensure_nc_success(ierr)
5894 name = vl_namstring.decode('utf-8')
5895 try:
5896 datatype = _nctonptype[base_xtype]
5897 if endian is not None: datatype = endian + datatype
5898 dt = numpy.dtype(datatype) # see if it is a primitive type
5899 except KeyError:
5900 raise KeyError("unsupported component type for VLEN")
5901 return VLType(group, dt, name, typeid=xtype)
5902
5903 # Enum datatype support.
5904
5905 cdef class EnumType:
5906 """
5907 A [EnumType](#EnumType) instance is used to describe an Enum data
5908 type, and can be passed to the the [Dataset.createVariable](#Dataset.createVariable) method of
5909 a [Dataset](#Dataset) or [Group](#Group) instance. See
5910 [EnumType.__init__](#EnumType.__init__) for more details.
5911
5912 The instance variables `dtype`, `name` and `enum_dict` should not be modified by
5913 the user.
5914 """
5915 cdef public nc_type _nc_type
5916 cdef public dtype, name, enum_dict
5917 def __init__(self, grp, object dt, object dtype_name, object enum_dict, **kwargs):
5918 """
5919 **`__init__(group, datatype, datatype_name, enum_dict)`**
5920
5921 EnumType constructor.
5922
5923 **`group`**: [Group](#Group) instance to associate with the VLEN datatype.
5924
5925 **`datatype`**: An numpy integer dtype object describing the base type
5926 for the Enum.
5927
5928 **`datatype_name`**: a Python string containing a description of the
5929 Enum data type.
5930
5931 **`enum_dict`**: a Python dictionary containing the Enum field/value
5932 pairs.
5933
5934 ***`Note`***: [EnumType](#EnumType) instances should be created using the
5935 [Dataset.createEnumType](#Dataset.createEnumType)
5936 method of a [Dataset](#Dataset) or [Group](#Group) instance, not using this class directly.
5937 """
5938 cdef nc_type xtype
5939 if 'typeid' in kwargs:
5940 xtype = kwargs['typeid']
5941 else:
5942 xtype, dt = _def_enum(grp, dt, dtype_name, enum_dict)
5943 self._nc_type = xtype
5944 self.dtype = dt
5945 self.name = dtype_name
5946 self.enum_dict = enum_dict
5947
5948 def __repr__(self):
5949 return self.__unicode__()
5950
5951 def __unicode__(self):
5952 return "%r: name = '%s', numpy dtype = %s, fields/values =%s" %\
5953 (type(self), self.name, self.dtype, self.enum_dict)
5954
5955 def __reduce__(self):
5956 # raise error is user tries to pickle a EnumType object.
5957 raise NotImplementedError('EnumType is not picklable')
5958
5959 cdef _def_enum(grp, object dt, object dtype_name, object enum_dict):
5960 # private function used to construct a netCDF Enum data type
5961 # from a numpy dtype object or python str object by EnumType.__init__.
5962 cdef nc_type xtype, xtype_tmp
5963 cdef int ierr
5964 cdef char *namstring
5965 cdef ndarray value_arr
5966 bytestr = _strencode(dtype_name)
5967 namstring = bytestr
5968 dt = numpy.dtype(dt) # convert to numpy datatype.
5969 if dt.str[1:] in _intnptonctype.keys():
5970 # find netCDF primitive data type corresponding to
5971 # specified numpy data type.
5972 xtype_tmp = _intnptonctype[dt.str[1:]]
5973 ierr = nc_def_enum(grp._grpid, xtype_tmp, namstring, &xtype);
5974 _ensure_nc_success(ierr)
5975 else:
5976 msg="unsupported datatype specified for ENUM (must be integer)"
5977 raise KeyError(msg)
5978 # insert named members into enum type.
5979 for field in enum_dict:
5980 value_arr = numpy.array(enum_dict[field],dt)
5981 bytestr = _strencode(field)
5982 namstring = bytestr
5983 ierr = nc_insert_enum(grp._grpid, xtype, namstring,
5984 PyArray_DATA(value_arr))
5985 _ensure_nc_success(ierr)
5986 return xtype, dt
5987
5988 cdef _read_enum(group, nc_type xtype, endian=None):
5989 # read a Enum data type id from an existing file,
5990 # construct a corresponding numpy dtype instance,
5991 # then use that to create a EnumType instance.
5992 # called by _get_types, _get_vars.
5993 cdef int ierr, _grpid, nmem
5994 cdef char enum_val
5995 cdef nc_type base_xtype
5996 cdef char enum_namstring[NC_MAX_NAME+1]
5997 cdef size_t nmembers
5998 _grpid = group._grpid
5999 # get name, datatype, and number of members.
6000 with nogil:
6001 ierr = nc_inq_enum(_grpid, xtype, enum_namstring, &base_xtype, NULL,\
6002 &nmembers)
6003 _ensure_nc_success(ierr)
6004 enum_name = enum_namstring.decode('utf-8')
6005 try:
6006 datatype = _nctonptype[base_xtype]
6007 if endian is not None: datatype = endian + datatype
6008 dt = numpy.dtype(datatype) # see if it is a primitive type
6009 except KeyError:
6010 raise KeyError("unsupported component type for ENUM")
6011 # loop over members, build dict.
6012 enum_dict = {}
6013 for nmem from 0 <= nmem < nmembers:
6014 with nogil:
6015 ierr = nc_inq_enum_member(_grpid, xtype, nmem, \
6016 enum_namstring, &enum_val)
6017 _ensure_nc_success(ierr)
6018 name = enum_namstring.decode('utf-8')
6019 enum_dict[name] = int(enum_val)
6020 return EnumType(group, dt, enum_name, enum_dict, typeid=xtype)
6021
6022 cdef _strencode(pystr,encoding=None):
6023 # encode a string into bytes. If already bytes, do nothing.
6024 # uses 'utf-8' for default encoding.
6025 if encoding is None:
6026 encoding = 'utf-8'
6027 try:
6028 return pystr.encode(encoding)
6029 except (AttributeError, UnicodeDecodeError):
6030 return pystr # already bytes or unicode?
6031
6032 def _to_ascii(bytestr):
6033 # encode a byte string to an ascii encoded string.
6034 return str(bytestr,encoding='ascii')
6035
6036 def stringtoarr(string,NUMCHARS,dtype='S'):
6037 """
6038 **`stringtoarr(a, NUMCHARS,dtype='S')`**
6039
6040 convert a string to a character array of length `NUMCHARS`
6041
6042 **`a`**: Input python string.
6043
6044 **`NUMCHARS`**: number of characters used to represent string
6045 (if len(a) < `NUMCHARS`, it will be padded on the right with blanks).
6046
6047 **`dtype`**: type of numpy array to return. Default is `'S'`, which
6048 means an array of dtype `'S1'` will be returned. If dtype=`'U'`, a
6049 unicode array (dtype = `'U1'`) will be returned.
6050
6051 returns a rank 1 numpy character array of length NUMCHARS with datatype `'S1'`
6052 (default) or `'U1'` (if dtype=`'U'`)"""
6053 if dtype not in ["S","U"]:
6054 raise ValueError("dtype must string or unicode ('S' or 'U')")
6055 arr = numpy.zeros(NUMCHARS,dtype+'1')
6056 arr[0:len(string)] = tuple(string)
6057 return arr
6058
6059 def stringtochar(a,encoding='utf-8'):
6060 """
6061 **`stringtochar(a,encoding='utf-8')`**
6062
6063 convert a string array to a character array with one extra dimension
6064
6065 **`a`**: Input numpy string array with numpy datatype `'SN'` or `'UN'`, where N
6066 is the number of characters in each string. Will be converted to
6067 an array of characters (datatype `'S1'` or `'U1'`) of shape `a.shape + (N,)`.
6068
6069 optional kwarg `encoding` can be used to specify character encoding (default
6070 `utf-8`). If `encoding` is 'none' or 'bytes', a `numpy.string_` the input array
6071 is treated a raw byte strings (`numpy.string_`).
6072
6073 returns a numpy character array with datatype `'S1'` or `'U1'`
6074 and shape `a.shape + (N,)`, where N is the length of each string in a."""
6075 dtype = a.dtype.kind
6076 if dtype not in ["S","U"]:
6077 raise ValueError("type must string or unicode ('S' or 'U')")
6078 if encoding in ['none','None','bytes']:
6079 b = numpy.array(tuple(a.tobytes()),'S1')
6080 else:
6081 b = numpy.array(tuple(a.tobytes().decode(encoding)),dtype+'1')
6082 b.shape = a.shape + (a.itemsize,)
6083 return b
6084
6085 def chartostring(b,encoding='utf-8'):
6086 """
6087 **`chartostring(b,encoding='utf-8')`**
6088
6089 convert a character array to a string array with one less dimension.
6090
6091 **`b`**: Input character array (numpy datatype `'S1'` or `'U1'`).
6092 Will be converted to a array of strings, where each string has a fixed
6093 length of `b.shape[-1]` characters.
6094
6095 optional kwarg `encoding` can be used to specify character encoding (default
6096 `utf-8`). If `encoding` is 'none' or 'bytes', a `numpy.string_` btye array is
6097 returned.
6098
6099 returns a numpy string array with datatype `'UN'` (or `'SN'`) and shape
6100 `b.shape[:-1]` where where `N=b.shape[-1]`."""
6101 dtype = b.dtype.kind
6102 if dtype not in ["S","U"]:
6103 raise ValueError("type must be string or unicode ('S' or 'U')")
6104 if encoding in ['none','None','bytes']:
6105 bs = b.tobytes()
6106 else:
6107 bs = b.tobytes().decode(encoding)
6108 slen = int(b.shape[-1])
6109 if encoding in ['none','None','bytes']:
6110 a = numpy.array([bs[n1:n1+slen] for n1 in range(0,len(bs),slen)],'S'+repr(slen))
6111 else:
6112 a = numpy.array([bs[n1:n1+slen] for n1 in range(0,len(bs),slen)],'U'+repr(slen))
6113 a.shape = b.shape[:-1]
6114 return a
6115
6116 class MFDataset(Dataset):
6117 """
6118 Class for reading multi-file netCDF Datasets, making variables
6119 spanning multiple files appear as if they were in one file.
6120 Datasets must be in `NETCDF4_CLASSIC, NETCDF3_CLASSIC, NETCDF3_64BIT_OFFSET
6121 or NETCDF3_64BIT_DATA` format (`NETCDF4` Datasets won't work).
6122
6123 Adapted from [pycdf](http://pysclint.sourceforge.net/pycdf) by Andre Gosselin.
6124
6125 Example usage (See [MFDataset.__init__](#MFDataset.__init__) for more details):
6126
6127 ```python
6128 >>> import numpy as np
6129 >>> # create a series of netCDF files with a variable sharing
6130 >>> # the same unlimited dimension.
6131 >>> for nf in range(10):
6132 ... with Dataset("mftest%s.nc" % nf, "w", format='NETCDF4_CLASSIC') as f:
6133 ... f.createDimension("x",None)
6134 ... x = f.createVariable("x","i",("x",))
6135 ... x[0:10] = np.arange(nf*10,10*(nf+1))
6136 >>> # now read all those files in at once, in one Dataset.
6137 >>> f = MFDataset("mftest*nc")
6138 >>> print(f.variables["x"][:])
6139 [ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
6140 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
6141 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
6142 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
6143 96 97 98 99]
6144 ```
6145 """
6146
6147 def __init__(self, files, check=False, aggdim=None, exclude=[],
6148 master_file=None):
6149 """
6150 **`__init__(self, files, check=False, aggdim=None, exclude=[],
6151 master_file=None)`**
6152
6153 Open a Dataset spanning multiple files, making it look as if it was a
6154 single file. Variables in the list of files that share the same
6155 dimension (specified with the keyword `aggdim`) are aggregated. If
6156 `aggdim` is not specified, the unlimited is aggregated. Currently,
6157 `aggdim` must be the leftmost (slowest varying) dimension of each
6158 of the variables to be aggregated.
6159
6160 **`files`**: either a sequence of netCDF files or a string with a
6161 wildcard (converted to a sorted list of files using glob) If
6162 the `master_file` kwarg is not specified, the first file
6163 in the list will become the "master" file, defining all the
6164 variables with an aggregation dimension which may span
6165 subsequent files. Attribute access returns attributes only from "master"
6166 file. The files are always opened in read-only mode.
6167
6168 **`check`**: True if you want to do consistency checking to ensure the
6169 correct variables structure for all of the netcdf files. Checking makes
6170 the initialization of the MFDataset instance much slower. Default is
6171 False.
6172
6173 **`aggdim`**: The name of the dimension to aggregate over (must
6174 be the leftmost dimension of each of the variables to be aggregated).
6175 If None (default), aggregate over the unlimited dimension.
6176
6177 **`exclude`**: A list of variable names to exclude from aggregation.
6178 Default is an empty list.
6179
6180 **`master_file`**: file to use as "master file", defining all the
6181 variables with an aggregation dimension and all global attributes.
6182 """
6183
6184 # Open the master file in the base class, so that the CDFMF instance
6185 # can be used like a CDF instance.
6186 if isinstance(files, str):
6187 if files.startswith('http'):
6188 msg='cannot using file globbing for remote (OPeNDAP) datasets'
6189 raise ValueError(msg)
6190 else:
6191 files = sorted(glob(files))
6192
6193 if not files:
6194 msg='no files specified (file list is empty)'
6195 raise IOError(msg)
6196
6197 if master_file is not None:
6198 if master_file not in files:
6199 raise ValueError('master_file not in files list')
6200 else:
6201 master = master_file
6202 else:
6203 master = files[0]
6204
6205 # Open the master again, this time as a classic CDF instance. This will avoid
6206 # calling methods of the CDFMF subclass when querying the master file.
6207 cdfm = Dataset(master)
6208 # copy attributes from master.
6209 for name, value in cdfm.__dict__.items():
6210 self.__dict__[name] = value
6211
6212 # Make sure the master defines a dim with name aggdim,
6213 # or an unlimited dimension.
6214 aggDimId = None
6215 for dimname,dim in cdfm.dimensions.items():
6216 if aggdim is None:
6217 if dim.isunlimited():
6218 aggDimId = dim
6219 aggDimName = dimname
6220 else:
6221 if dimname == aggdim:
6222 aggDimId = dim
6223 aggDimName = dimname
6224 if aggDimId is None:
6225 raise IOError("master dataset %s does not have a aggregation dimension" % master)
6226
6227 # Get info on all aggregation variables defined in the master.
6228 # Make sure the master defines at least one aggregation variable.
6229 masterRecVar = {}
6230 for vName,v in cdfm.variables.items():
6231 # skip variables specified in exclude list.
6232 if vName in exclude: continue
6233 dims = v.dimensions
6234 shape = v.shape
6235 dtype = v.dtype
6236 # Be careful: we may deal with a scalar (dimensionless) variable.
6237 # Unlimited dimension always occupies index 0.
6238 if (len(dims) > 0 and aggDimName == dims[0]):
6239 masterRecVar[vName] = (dims, shape, dtype)
6240 if len(masterRecVar) == 0:
6241 raise IOError("master dataset %s does not have any variables to aggregate" % master)
6242
6243 # Create the following:
6244 # cdf list of Dataset instances
6245 # cdfVLen list unlimited dimension lengths in each CDF instance
6246 # cdfRecVar dictionary indexed by the aggregation var names; each key holds
6247 # a list of the corresponding Variable instance, one for each
6248 # cdf file of the file set
6249 cdf = []
6250 self._cdf = cdf # Store this now, because dim() method needs it
6251 cdfVLen = []
6252 cdfRecVar = {}
6253
6254 # Open each remaining file in read-only mode.
6255 # Make sure each file defines the same aggregation variables as the master
6256 # and that the variables are defined in the same way (name, shape and type)
6257 for f in files:
6258 if f == master:
6259 part = cdfm
6260 else:
6261 part = Dataset(f)
6262 if cdfRecVar == {}:
6263 empty_cdfRecVar = True
6264 else:
6265 empty_cdfRecVar = False
6266 varInfo = part.variables
6267 for v in masterRecVar.keys():
6268 if check:
6269 # Make sure master rec var is also defined here.
6270 if v not in varInfo.keys():
6271 raise IOError("aggregation variable %s not defined in %s" % (v, f))
6272
6273 #if not vInst.dimensions[0] != aggDimName:
6274
6275 masterDims, masterShape, masterType = masterRecVar[v][:3]
6276 extDims = varInfo[v].dimensions
6277 extShape = varInfo[v].shape
6278 extType = varInfo[v].dtype
6279 # Check that dimension names are identical.
6280 if masterDims != extDims:
6281 raise IOError("variable %s : dimensions mismatch between "
6282 "master %s (%s) and extension %s (%s)" %
6283 (v, master, masterDims, f, extDims))
6284
6285 # Check that the ranks are identical, and the dimension lengths are
6286 # identical (except for that of the unlimited dimension, which of
6287 # course may vary.
6288 if len(masterShape) != len(extShape):
6289 raise IOError("variable %s : rank mismatch between "
6290 "master %s (%s) and extension %s (%s)" %
6291 (v, master, len(masterShape), f, len(extShape)))
6292 if masterShape[1:] != extShape[1:]:
6293 raise IOError("variable %s : shape mismatch between "
6294 "master %s (%s) and extension %s (%s)" %
6295 (v, master, masterShape, f, extShape))
6296
6297 # Check that the data types are identical.
6298 if masterType != extType:
6299 raise IOError("variable %s : data type mismatch between "
6300 "master %s (%s) and extension %s (%s)" %
6301 (v, master, masterType, f, extType))
6302
6303 # Everything ok.
6304 if empty_cdfRecVar:
6305 cdfRecVar[v] = [part.variables[v]]
6306 else:
6307 cdfRecVar[v].append(part.variables[v])
6308 else:
6309 # No making sure of anything -- assume this is ok..
6310 if empty_cdfRecVar:
6311 cdfRecVar[v] = [part.variables[v]]
6312 else:
6313 cdfRecVar[v].append(part.variables[v])
6314
6315 cdf.append(part)
6316 cdfVLen.append(len(part.dimensions[aggDimName]))
6317
6318 # Attach attributes to the MFDataset instance.
6319 # A local __setattr__() method is required for them.
6320 self._files = files # list of cdf file names in the set
6321 self._cdfVLen = cdfVLen # list of unlimited lengths
6322 self._cdfTLen = sum(cdfVLen) # total length
6323 self._cdfRecVar = cdfRecVar # dictionary of Variable instances for all
6324 # the aggregation variables
6325 self._dims = cdfm.dimensions
6326 self._grps = cdfm.groups
6327 for dimname, dim in self._dims.items():
6328 if dimname == aggDimName:
6329 self._dims[dimname] = _Dimension(dimname, dim, self._cdfVLen, self._cdfTLen)
6330 self._vars = cdfm.variables
6331 for varname,var in self._vars.items():
6332 if varname in self._cdfRecVar.keys():
6333 self._vars[varname] = _Variable(self, varname, var, aggDimName)
6334 self._file_format = []
6335 self._data_model = []
6336 self._disk_format = []
6337 for dset in self._cdf:
6338 if dset.file_format == 'NETCDF4' or dset.data_model == 'NETCDF4':
6339 raise ValueError('MFNetCDF4 only works with NETCDF3_* and NETCDF4_CLASSIC formatted files, not NETCDF4')
6340 self._file_format.append(dset.file_format)
6341 self._data_model.append(dset.data_model)
6342 self._disk_format.append(dset.disk_format)
6343 self._path = '/'
6344
6345 def __setattr__(self, name, value):
6346 """override base class attribute creation"""
6347 self.__dict__[name] = value
6348
6349 def __getattribute__(self, name):
6350 if name in ['variables','dimensions','file_format','groups',\
6351 'data_model','disk_format','path']:
6352 if name == 'dimensions': return self._dims
6353 if name == 'variables': return self._vars
6354 if name == 'file_format': return self._file_format
6355 if name == 'data_model': return self._data_model
6356 if name == 'disk_format': return self._disk_format
6357 if name == 'path': return self._path
6358 if name == 'groups': return self._grps
6359 else:
6360 return Dataset.__getattribute__(self, name)
6361
6362 def ncattrs(self):
6363 """
6364 **`ncattrs(self)`**
6365
6366 return the netcdf attribute names from the master file.
6367 """
6368 return self._cdf[0].__dict__.keys()
6369
6370 def close(self):
6371 """
6372 **`close(self)`**
6373
6374 close all the open files.
6375 """
6376 for dset in self._cdf:
6377 dset.close()
6378
6379 def __repr__(self):
6380 ncdump = [repr(type(self))]
6381 dimnames = tuple(str(dimname) for dimname in self.dimensions.keys())
6382 varnames = tuple(str(varname) for varname in self.variables.keys())
6383 grpnames = ()
6384 if self.path == '/':
6385 ncdump.append('root group (%s data model, file format %s):' %
6386 (self.data_model[0], self.disk_format[0]))
6387 else:
6388 ncdump.append('group %s:' % self.path)
6389 for name in self.ncattrs():
6390 ncdump.append(' %s: %s' % (name, self.__dict__[name]))
6391 ncdump.append(' dimensions = %s' % str(dimnames))
6392 ncdump.append(' variables = %s' % str(varnames))
6393 ncdump.append(' groups = %s' % str(grpnames))
6394 return '\n'.join(ncdump)
6395
6396 def __reduce__(self):
6397 # raise error is user tries to pickle a MFDataset object.
6398 raise NotImplementedError('MFDataset is not picklable')
6399
6400 class _Dimension(object):
6401 def __init__(self, dimname, dim, dimlens, dimtotlen):
6402 self.dimlens = dimlens
6403 self.dimtotlen = dimtotlen
6404 self._name = dimname
6405 def __len__(self):
6406 return self.dimtotlen
6407 def isunlimited(self):
6408 return True
6409 def __repr__(self):
6410 if self.isunlimited():
6411 return "%r (unlimited): name = '%s', size = %s" %\
6412 (type(self), self._name, len(self))
6413 else:
6414 return "%r: name = '%s', size = %s" %\
6415 (type(self), self._name, len(self))
6416
6417 class _Variable(object):
6418 def __init__(self, dset, varname, var, recdimname):
6419 self.dimensions = var.dimensions
6420 self._dset = dset
6421 self._grp = dset
6422 self._mastervar = var
6423 self._recVar = dset._cdfRecVar[varname]
6424 self._recdimname = recdimname
6425 self._recLen = dset._cdfVLen
6426 self.dtype = var.dtype
6427 self._name = var._name
6428 # copy attributes from master.
6429 for name, value in var.__dict__.items():
6430 self.__dict__[name] = value
6431 def typecode(self):
6432 return self.dtype
6433 def ncattrs(self):
6434 return self._mastervar.__dict__.keys()
6435 def __getattr__(self,name):
6436 if name == 'shape': return self._shape()
6437 if name == 'ndim': return len(self._shape())
6438 try:
6439 return self.__dict__[name]
6440 except:
6441 raise AttributeError(name)
6442 def __repr__(self):
6443 ncdump = [repr(type(self))]
6444 dimnames = tuple(str(dimname) for dimname in self.dimensions)
6445 ncdump.append('%s %s%s' % (self.dtype, self._name, dimnames))
6446 for name in self.ncattrs():
6447 ncdump.append(' %s: %s' % (name, self.__dict__[name]))
6448 unlimdims = []
6449 for dimname in self.dimensions:
6450 dim = _find_dim(self._grp, dimname)
6451 if dim.isunlimited():
6452 unlimdims.append(str(dimname))
6453 ncdump.append('unlimited dimensions = %r' % (tuple(unlimdims),))
6454 ncdump.append('current size = %r' % (self.shape,))
6455 return '\n'.join(ncdump)
6456 def __len__(self):
6457 if not self._shape:
6458 raise TypeError('len() of unsized object')
6459 else:
6460 return self._shape()[0]
6461 def _shape(self):
6462 recdimlen = len(self._dset.dimensions[self._recdimname])
6463 return (recdimlen,) + self._mastervar.shape[1:]
6464 def set_auto_chartostring(self,val):
6465 for v in self._recVar:
6466 v.set_auto_chartostring(val)
6467 def set_auto_maskandscale(self,val):
6468 for v in self._recVar:
6469 v.set_auto_maskandscale(val)
6470 def set_auto_mask(self,val):
6471 for v in self._recVar:
6472 v.set_auto_mask(val)
6473 def set_auto_scale(self,val):
6474 for v in self._recVar:
6475 v.set_auto_scale(val)
6476 def set_always_mask(self,val):
6477 for v in self._recVar:
6478 v.set_always_mask(val)
6479 def __getitem__(self, elem):
6480 """Get records from a concatenated set of variables."""
6481
6482 # This special method is used to index the netCDF variable
6483 # using the "extended slice syntax". The extended slice syntax
6484 # is a perfect match for the "start", "count" and "stride"
6485 # arguments to the nc_get_var() function, and is much more easy
6486 # to use.
6487 start, count, stride, put_ind =\
6488 _StartCountStride(elem, self.shape)
6489 datashape = _out_array_shape(count)
6490 data = ma.empty(datashape, dtype=self.dtype)
6491
6492 # Determine which dimensions need to be squeezed
6493 # (those for which elem is an integer scalar).
6494 # The convention used is that for those cases,
6495 # put_ind for this dimension is set to -1 by _StartCountStride.
6496 squeeze = data.ndim * [slice(None),]
6497 for i,n in enumerate(put_ind.shape[:-1]):
6498 if n == 1 and put_ind[...,i].ravel()[0] == -1:
6499 squeeze[i] = 0
6500
6501 # Reshape the arrays so we can iterate over them.
6502 strt = start.reshape((-1, self.ndim or 1))
6503 cnt = count.reshape((-1, self.ndim or 1))
6504 strd = stride.reshape((-1, self.ndim or 1))
6505 put_ind = put_ind.reshape((-1, self.ndim or 1))
6506
6507 # Fill output array with data chunks.
6508 # Number of variables making up the MFVariable.Variable.
6509 nv = len(self._recLen)
6510 for (start,count,stride,ind) in zip(strt, cnt, strd, put_ind):
6511 # make sure count=-1 becomes count=1
6512 count = [abs(cnt) for cnt in count]
6513 if (numpy.array(stride) < 0).any():
6514 raise IndexError('negative strides not allowed when slicing MFVariable Variable instance')
6515 # Start, stop and step along 1st dimension, eg the unlimited
6516 # dimension.
6517 sta = start[0]
6518 step = stride[0]
6519 stop = sta + count[0] * step
6520
6521 # Build a list representing the concatenated list of all records in
6522 # the MFVariable variable set. The list is composed of 2-elem lists
6523 # each holding:
6524 # the record index inside the variables, from 0 to n
6525 # the index of the Variable instance to which each record belongs
6526 idx = [] # list of record indices
6527 vid = [] # list of Variable indices
6528 for n in range(nv):
6529 k = self._recLen[n] # number of records in this variable
6530 idx.extend(range(k))
6531 vid.extend([n] * k)
6532
6533 # Merge the two lists to get a list of 2-elem lists.
6534 # Slice this list along the first dimension.
6535 lst = list(zip(idx, vid)).__getitem__(slice(sta, stop, step))
6536
6537 # Rebuild the slicing expression for dimensions 1 and ssq.
6538 newSlice = [slice(None, None, None)]
6539 for n in range(1, len(start)): # skip dimension 0
6540 s = slice(start[n],start[n] + count[n] * stride[n], stride[n])
6541 newSlice.append(s)
6542
6543 # Apply the slicing expression to each var in turn, extracting records
6544 # in a list of arrays.
6545 lstArr = []
6546 ismasked = False
6547 for n in range(nv):
6548 # Get the list of indices for variable 'n'.
6549 idx = [i for i,numv in lst if numv == n]
6550 if idx:
6551 # Rebuild slicing expression for dimension 0.
6552 newSlice[0] = slice(idx[0], idx[-1] + 1, step)
6553 # Extract records from the var, and append them to a list
6554 # of arrays.
6555 dat = Variable.__getitem__(self._recVar[n],tuple(newSlice))
6556 if ma.isMA(dat) and not ismasked:
6557 ismasked=True
6558 fill_value = dat.fill_value
6559 lstArr.append(dat)
6560 if ismasked:
6561 lstArr = ma.concatenate(lstArr)
6562 else:
6563 lstArr = numpy.concatenate(lstArr)
6564 if lstArr.dtype != data.dtype: data = data.astype(lstArr.dtype)
6565 # sometimes there are legitimate singleton dimensions, in which
6566 # case the array shapes won't conform. If so, a ValueError will
6567 # result, and no squeeze will be done.
6568 try:
6569 data[tuple(ind)] = lstArr.squeeze()
6570 except ValueError:
6571 data[tuple(ind)] = lstArr
6572
6573 # Remove extra singleton dimensions.
6574 data = data[tuple(squeeze)]
6575
6576 # if no masked elements, return numpy array.
6577 if ma.isMA(data) and not data.mask.any():
6578 data = data.filled()
6579
6580 return data
6581
6582
6583 class MFTime(_Variable):
6584 """
6585 Class providing an interface to a MFDataset time Variable by imposing a unique common
6586 time unit and/or calendar to all files.
6587
6588 Example usage (See [MFTime.__init__](#MFTime.__init__) for more details):
6589
6590 ```python
6591 >>> import numpy
6592 >>> f1 = Dataset("mftest_1.nc","w", format="NETCDF4_CLASSIC")
6593 >>> f2 = Dataset("mftest_2.nc","w", format="NETCDF4_CLASSIC")
6594 >>> f1.createDimension("time",None)
6595 >>> f2.createDimension("time",None)
6596 >>> t1 = f1.createVariable("time","i",("time",))
6597 >>> t2 = f2.createVariable("time","i",("time",))
6598 >>> t1.units = "days since 2000-01-01"
6599 >>> t2.units = "days since 2000-02-01"
6600 >>> t1.calendar = "standard"
6601 >>> t2.calendar = "standard"
6602 >>> t1[:] = numpy.arange(31)
6603 >>> t2[:] = numpy.arange(30)
6604 >>> f1.close()
6605 >>> f2.close()
6606 >>> # Read the two files in at once, in one Dataset.
6607 >>> f = MFDataset("mftest_*nc")
6608 >>> t = f.variables["time"]
6609 >>> print(t.units)
6610 days since 2000-01-01
6611 >>> print(t[32]) # The value written in the file, inconsistent with the MF time units.
6612 1
6613 >>> T = MFTime(t)
6614 >>> print(T[32])
6615 32
6616 ```
6617 """
6618
6619 def __init__(self, time, units=None, calendar=None):
6620 """
6621 **`__init__(self, time, units=None, calendar=None)`**
6622
6623 Create a time Variable with units consistent across a multifile
6624 dataset.
6625
6626 **`time`**: Time variable from a [MFDataset](#MFDataset).
6627
6628 **`units`**: Time units, for example, `'days since 1979-01-01'`. If `None`,
6629 use the units from the master variable.
6630
6631 **`calendar`**: Calendar overload to use across all files, for example,
6632 `'standard'` or `'gregorian'`. If `None`, check that the calendar attribute
6633 is present on each variable and values are unique across files raising a
6634 `ValueError` otherwise.
6635 """
6636 import datetime
6637 self.__time = time
6638
6639 # copy attributes from master time variable.
6640 for name, value in time.__dict__.items():
6641 self.__dict__[name] = value
6642
6643 # Make sure calendar attribute present in all files if no default calendar
6644 # is provided. Also assert this value is the same across files.
6645 if calendar is None:
6646 calendars = [None] * len(self._recVar)
6647 for idx, t in enumerate(self._recVar):
6648 if not hasattr(t, 'calendar'):
6649 msg = 'MFTime requires that the time variable in all files ' \
6650 'have a calendar attribute if no default calendar is provided.'
6651 raise ValueError(msg)
6652 else:
6653 calendars[idx] = t.calendar
6654 calendars = set(calendars)
6655 if len(calendars) > 1:
6656 msg = 'MFTime requires that the same time calendar is ' \
6657 'used by all files if no default calendar is provided.'
6658 raise ValueError(msg)
6659 else:
6660 calendar = list(calendars)[0]
6661
6662 # Set calendar using the default or the unique calendar value across all files.
6663 self.calendar = calendar
6664
6665 # Override units if units is specified.
6666 self.units = units or time.units
6667
6668 # Reference date to compute the difference between different time units.
6669 ref_date = datetime.datetime(1900,1,1)
6670 ref_num = date2num(ref_date, self.units, self.calendar)
6671
6672 # Create delta vector: delta = ref_num(ref_date) - num(ref_date)
6673 # So that ref_num(date) = num(date) + delta
6674 self.__delta = numpy.empty(len(self), time.dtype)
6675
6676 i0 = 0; i1 = 0
6677 for i,v in enumerate(self._recVar):
6678 n = self._recLen[i] # Length of time vector.
6679 num = date2num(ref_date, v.units, self.calendar)
6680 i1 += n
6681 self.__delta[i0:i1] = ref_num - num
6682 i0 += n
6683
6684
6685 def __getitem__(self, elem):
6686 return self.__time[elem] + self.__delta[elem]
0 from __future__ import print_function
1
2 import sys
3 import numpy as np
4 from numpy import ma
5 from numpy.lib.stride_tricks import as_strided
6 import warnings
7 import getopt
8 import os
9
10 python3 = sys.version_info[0] > 2
11 if python3:
12 # no unicode type in python 3, use bytes instead when testing
13 # for a string-like object
14 unicode = str
15 else:
16 range = xrange
17 try:
18 bytes
19 except NameError:
20 # no bytes type in python < 2.6
21 bytes = str
22
23 def _safecast(a,b):
24 # check to see if array a can be safely cast
25 # to array b. A little less picky than numpy.can_cast.
26 try:
27 is_safe = ((a == b) | (np.isnan(a) & np.isnan(b))).all()
28 #is_safe = np.allclose(a, b, equal_nan=True) # numpy 1.10.0
29 except:
30 try:
31 is_safe = (a == b).all() # string arrays.
32 except:
33 is_safe = False
34 return is_safe
35
36 def _sortbylist(A,B):
37 # sort one list (A) using the values from another list (B)
38 return [A[i] for i in sorted(range(len(A)), key=B.__getitem__)]
39
40 def _find_dim(grp, dimname):
41 # find Dimension instance given group and name.
42 # look in current group, and parents.
43 group = grp
44 dim = None
45 while 1:
46 try:
47 dim = group.dimensions[dimname]
48 break
49 except:
50 try:
51 group = group.parent
52 except:
53 raise ValueError("cannot find dimension %s in this group or parent groups" % dimname)
54 return dim
55
56 def _walk_grps(topgrp):
57 """Iterate through all (sub-) groups of topgrp, similar to os.walktree.
58
59 """
60 grps = topgrp.groups.values()
61 yield grps
62 for grp in topgrp.groups.values():
63 for children in _walk_grps(grp):
64 yield children
65
66 def _quantize(data,least_significant_digit):
67 """
68 quantize data to improve compression. data is quantized using
69 around(scale*data)/scale, where scale is 2**bits, and bits is determined
70 from the least_significant_digit. For example, if
71 least_significant_digit=1, bits will be 4.
72 """
73 precision = pow(10.,-least_significant_digit)
74 exp = np.log10(precision)
75 if exp < 0:
76 exp = int(np.floor(exp))
77 else:
78 exp = int(np.ceil(exp))
79 bits = np.ceil(np.log2(pow(10.,-exp)))
80 scale = pow(2.,bits)
81 datout = np.around(scale*data)/scale
82 if ma.isMA(datout):
83 datout.set_fill_value(data.fill_value)
84 return datout
85 else:
86 return datout
87
88 def _StartCountStride(elem, shape, dimensions=None, grp=None, datashape=None,\
89 put=False, use_get_vars = False):
90 """Return start, count, stride and indices needed to store/extract data
91 into/from a netCDF variable.
92
93 This function is used to convert a slicing expression into a form that is
94 compatible with the nc_get_vars function. Specifically, it needs
95 to interpret integers, slices, Ellipses, and 1-d sequences of integers
96 and booleans.
97
98 Numpy uses "broadcasting indexing" to handle array-valued indices.
99 "Broadcasting indexing" (a.k.a "fancy indexing") treats all multi-valued
100 indices together to allow arbitrary points to be extracted. The index
101 arrays can be multidimensional, and more than one can be specified in a
102 slice, as long as they can be "broadcast" against each other.
103 This style of indexing can be very powerful, but it is very hard
104 to understand, explain, and implement (and can lead to hard to find bugs).
105 Most other python packages and array processing
106 languages (such as netcdf4-python, xray, biggus, matlab and fortran)
107 use "orthogonal indexing" which only allows for 1-d index arrays and
108 treats these arrays of indices independently along each dimension.
109
110 The implementation of "orthogonal indexing" used here requires that
111 index arrays be 1-d boolean or integer. If integer arrays are used,
112 the index values must be sorted and contain no duplicates.
113
114 In summary, slicing netcdf4-python variable objects with 1-d integer or
115 boolean arrays is allowed, but may give a different result than slicing a
116 numpy array.
117
118 Numpy also supports slicing an array with a boolean array of the same
119 shape. For example x[x>0] returns a 1-d array with all the positive values of x.
120 This is also not supported in netcdf4-python, if x.ndim > 1.
121
122 Orthogonal indexing can be used in to select netcdf variable slices
123 using the dimension variables. For example, you can use v[lat>60,lon<180]
124 to fetch the elements of v obeying conditions on latitude and longitude.
125 Allow for this sort of simple variable subsetting is the reason we decided to
126 deviate from numpy's slicing rules.
127
128 This function is used both by the __setitem__ and __getitem__ method of
129 the Variable class.
130
131 Parameters
132 ----------
133 elem : tuple of integer, slice, ellipsis or 1-d boolean or integer
134 sequences used to slice the netCDF Variable (Variable[elem]).
135 shape : tuple containing the current shape of the netCDF variable.
136 dimensions : sequence
137 The name of the dimensions.
138 __setitem__.
139 grp : netCDF Group
140 The netCDF group to which the variable being set belongs to.
141 datashape : sequence
142 The shape of the data that is being stored. Only needed by __setitem__
143 put : True|False (default False). If called from __setitem__, put is True.
144
145 Returns
146 -------
147 start : ndarray (..., n)
148 A starting indices array of dimension n+1. The first n
149 dimensions identify different independent data chunks. The last dimension
150 can be read as the starting indices.
151 count : ndarray (..., n)
152 An array of dimension (n+1) storing the number of elements to get.
153 stride : ndarray (..., n)
154 An array of dimension (n+1) storing the steps between each datum.
155 indices : ndarray (..., n)
156 An array storing the indices describing the location of the
157 data chunk in the target/source array (__getitem__/__setitem__).
158
159 Notes:
160
161 netCDF data is accessed via the function:
162 nc_get_vars(grpid, varid, start, count, stride, data)
163
164 Assume that the variable has dimension n, then
165
166 start is a n-tuple that contains the indices at the beginning of data chunk.
167 count is a n-tuple that contains the number of elements to be accessed.
168 stride is a n-tuple that contains the step length between each element.
169
170 """
171 # Adapted from pycdf (http://pysclint.sourceforge.net/pycdf)
172 # by Andre Gosselin..
173 # Modified by David Huard to handle efficiently fancy indexing with
174 # sequences of integers or booleans.
175
176 nDims = len(shape)
177 if nDims == 0:
178 nDims = 1
179 shape = (1,)
180
181 # is there an unlimited dimension? (only defined for __setitem__)
182 if put:
183 hasunlim = False
184 unlimd={}
185 if dimensions:
186 for i in range(nDims):
187 dimname = dimensions[i]
188 # is this dimension unlimited?
189 # look in current group, and parents for dim.
190 dim = _find_dim(grp, dimname)
191 unlimd[dimname]=dim.isunlimited()
192 if unlimd[dimname]:
193 hasunlim = True
194 else:
195 hasunlim = False
196
197 # When a single array or (non-tuple) sequence of integers is given
198 # as a slice, assume it applies to the first dimension,
199 # and use ellipsis for remaining dimensions.
200 if np.iterable(elem):
201 if type(elem) == np.ndarray or (type(elem) != tuple and \
202 np.array([_is_int(e) for e in elem]).all()):
203 elem = [elem]
204 for n in range(len(elem)+1,nDims+1):
205 elem.append(slice(None,None,None))
206 else: # Convert single index to sequence
207 elem = [elem]
208
209 # ensure there is at most 1 ellipse
210 # we cannot use elem.count(Ellipsis), as with fancy indexing would occur
211 # np.array() == Ellipsis which gives ValueError: The truth value of an
212 # array with more than one element is ambiguous. Use a.any() or a.all()
213 if sum(1 for e in elem if e is Ellipsis) > 1:
214 raise IndexError("At most one ellipsis allowed in a slicing expression")
215
216 # replace boolean arrays with sequences of integers.
217 newElem = []
218 IndexErrorMsg=\
219 "only integers, slices (`:`), ellipsis (`...`), and 1-d integer or boolean arrays are valid indices"
220 i=0
221 for e in elem:
222 # string-like object try to cast to int
223 # needs to be done first, since strings are iterable and
224 # hard to distinguish from something castable to an iterable numpy array.
225 if type(e) in [str,bytes,unicode]:
226 try:
227 e = int(e)
228 except:
229 raise IndexError(IndexErrorMsg)
230 ea = np.asarray(e)
231 # Raise error if multidimensional indexing is used.
232 if ea.ndim > 1:
233 raise IndexError("Index cannot be multidimensional")
234 # set unlim to True if dimension is unlimited and put==True
235 # (called from __setitem__)
236 if hasunlim and put and dimensions:
237 try:
238 dimname = dimensions[i]
239 unlim = unlimd[dimname]
240 except IndexError: # more slices than dimensions (issue 371)
241 unlim = False
242 else:
243 unlim = False
244 # convert boolean index to integer array.
245 if np.iterable(ea) and ea.dtype.kind =='b':
246 # check that boolen array not too long
247 if not unlim and shape[i] != len(ea):
248 msg="""
249 Boolean array must have the same shape as the data along this dimension."""
250 raise IndexError(msg)
251 ea = np.flatnonzero(ea)
252 # an iterable (non-scalar) integer array.
253 if np.iterable(ea) and ea.dtype.kind == 'i':
254 # convert negative indices in 1d array to positive ones.
255 ea = np.where(ea < 0, ea + shape[i], ea)
256 if np.any(ea < 0):
257 raise IndexError("integer index out of range")
258 # if unlim, let integer index be longer than current dimension
259 # length.
260 if ea.shape != (0,):
261 elen = shape[i]
262 if unlim:
263 elen = max(ea.max()+1,elen)
264 if ea.max()+1 > elen:
265 msg="integer index exceeds dimension size"
266 raise IndexError(msg)
267 newElem.append(ea)
268 # integer scalar
269 elif ea.dtype.kind == 'i':
270 newElem.append(e)
271 # slice or ellipsis object
272 elif type(e) == slice or type(e) == type(Ellipsis):
273 if not use_get_vars and type(e) == slice and e.step not in [None,-1,1] and\
274 dimensions is not None and grp is not None:
275 # convert strided slice to integer sequence if possible
276 # (this will avoid nc_get_vars, which is slow - issue #680).
277 start = e.start if e.start is not None else 0
278 step = e.step
279 if e.stop is None and dimensions is not None and grp is not None:
280 stop = len(_find_dim(grp, dimensions[i]))
281 else:
282 stop = e.stop
283 if stop < 0:
284 stop = len(_find_dim(grp, dimensions[i])) + stop
285 try:
286 ee = np.arange(start,stop,e.step)
287 if len(ee) > 0:
288 e = ee
289 except:
290 pass
291 newElem.append(e)
292 else: # castable to a scalar int, otherwise invalid
293 try:
294 e = int(e)
295 newElem.append(e)
296 except:
297 raise IndexError(IndexErrorMsg)
298 if type(e)==type(Ellipsis):
299 i+=1+nDims-len(elem)
300 else:
301 i+=1
302 elem = newElem
303
304 # replace Ellipsis and integer arrays with slice objects, if possible.
305 newElem = []
306 for e in elem:
307 ea = np.asarray(e)
308 # Replace ellipsis with slices.
309 if type(e) == type(Ellipsis):
310 # The ellipsis stands for the missing dimensions.
311 newElem.extend((slice(None, None, None),) * (nDims - len(elem) + 1))
312 # Replace sequence of indices with slice object if possible.
313 elif np.iterable(e) and len(e) > 1:
314 start = e[0]
315 stop = e[-1]+1
316 step = e[1]-e[0]
317 try:
318 ee = range(start,stop,step)
319 except ValueError: # start, stop or step is not valid for a range
320 ee = False
321 if ee and len(e) == len(ee) and (e == np.arange(start,stop,step)).all():
322 # don't convert to slice unless abs(stride) == 1
323 # (nc_get_vars is very slow, issue #680)
324 if not use_get_vars and step not in [1,-1]:
325 newElem.append(e)
326 else:
327 newElem.append(slice(start,stop,step))
328 else:
329 newElem.append(e)
330 elif np.iterable(e) and len(e) == 1:
331 newElem.append(slice(e[0], e[0] + 1, 1))
332 else:
333 newElem.append(e)
334 elem = newElem
335
336 # If slice doesn't cover all dims, assume ellipsis for rest of dims.
337 if len(elem) < nDims:
338 for n in range(len(elem)+1,nDims+1):
339 elem.append(slice(None,None,None))
340
341 # make sure there are not too many dimensions in slice.
342 if len(elem) > nDims:
343 raise ValueError("slicing expression exceeds the number of dimensions of the variable")
344
345 # Compute the dimensions of the start, count, stride and indices arrays.
346 # The number of elements in the first n dimensions corresponds to the
347 # number of times the _get method will be called.
348 sdim = []
349 for i, e in enumerate(elem):
350 # at this stage e is a slice, a scalar integer, or a 1d integer array.
351 # integer array: _get call for each True value
352 if np.iterable(e):
353 sdim.append(len(e))
354 # Scalar int or slice, just a single _get call
355 else:
356 sdim.append(1)
357
358 # broadcast data shape when assigned to full variable (issue #919)
359 try:
360 fullslice = elem.count(slice(None,None,None)) == len(elem)
361 except: # fails if elem contains a numpy array.
362 fullslice = False
363 if fullslice and datashape and put and not hasunlim:
364 datashape = broadcasted_shape(shape, datashape)
365
366 # pad datashape with zeros for dimensions not being sliced (issue #906)
367 # only used when data covers slice over subset of dimensions
368 if datashape and len(datashape) != len(elem) and\
369 len(datashape) == sum(1 for e in elem if type(e) == slice):
370 datashapenew = (); i=0
371 for e in elem:
372 if type(e) != slice and not np.iterable(e): # scalar integer slice
373 datashapenew = datashapenew + (0,)
374 else: # slice object
375 datashapenew = datashapenew + (datashape[i],)
376 i+=1
377 datashape = datashapenew
378
379 # Create the start, count, stride and indices arrays.
380
381 sdim.append(max(nDims, 1))
382 start = np.empty(sdim, dtype=int)
383 count = np.empty(sdim, dtype=int)
384 stride = np.empty(sdim, dtype=int)
385 indices = np.empty(sdim, dtype=object)
386
387 for i, e in enumerate(elem):
388
389 ea = np.asarray(e)
390
391 # set unlim to True if dimension is unlimited and put==True
392 # (called from __setitem__). Note: grp and dimensions must be set.
393 if hasunlim and put and dimensions:
394 dimname = dimensions[i]
395 unlim = unlimd[dimname]
396 else:
397 unlim = False
398
399 # SLICE #
400 if type(e) == slice:
401
402 # determine length parameter for slice.indices.
403
404 # shape[i] can be zero for unlim dim that hasn't been written to
405 # yet.
406 # length of slice may be longer than current shape
407 # if dimension is unlimited (and we are writing, not reading).
408 if unlim and e.stop is not None and e.stop > shape[i]:
409 length = e.stop
410 elif unlim and e.stop is None and datashape != ():
411 try:
412 if e.start is None:
413 length = datashape[i]
414 else:
415 length = e.start+datashape[i]
416 except IndexError:
417 raise IndexError("shape of data does not conform to slice")
418 else:
419 if unlim and datashape == () and len(dim) == 0:
420 # writing scalar along unlimited dimension using slicing
421 # syntax (var[:] = 1, when var.shape = ())
422 length = 1
423 else:
424 length = shape[i]
425
426 beg, end, inc = e.indices(length)
427 n = len(range(beg,end,inc))
428
429 start[...,i] = beg
430 count[...,i] = n
431 stride[...,i] = inc
432 indices[...,i] = slice(None)
433
434 # ITERABLE #
435 elif np.iterable(e) and np.array(e).dtype.kind in 'i': # Sequence of integers
436 start[...,i] = np.apply_along_axis(lambda x: e*x, i, np.ones(sdim[:-1]))
437 indices[...,i] = np.apply_along_axis(lambda x: np.arange(sdim[i])*x, i, np.ones(sdim[:-1], int))
438
439 count[...,i] = 1
440 stride[...,i] = 1
441
442 # all that's left is SCALAR INTEGER #
443 else:
444 if e >= 0:
445 start[...,i] = e
446 elif e < 0 and (-e <= shape[i]) :
447 start[...,i] = e+shape[i]
448 else:
449 raise IndexError("Index out of range")
450
451 count[...,i] = 1
452 stride[...,i] = 1
453 indices[...,i] = -1 # Use -1 instead of 0 to indicate that
454 # this dimension shall be squeezed.
455
456 return start, count, stride, indices#, out_shape
457
458 def _out_array_shape(count):
459 """Return the output array shape given the count array created by getStartCountStride"""
460
461 s = list(count.shape[:-1])
462 out = []
463
464 for i, n in enumerate(s):
465 if n == 1:
466 c = count[..., i].ravel()[0] # All elements should be identical.
467 out.append(c)
468 else:
469 out.append(n)
470 return out
471
472 def _is_container(a):
473 # is object container-like? (can test for
474 # membership with "is in", but not a string)
475 try: 1 in a
476 except: return False
477 if type(a) == type(basestring): return False
478 return True
479
480 def _is_int(a):
481 try:
482 return int(a) == a
483 except:
484 return False
485
486 def _tostr(s):
487 try:
488 ss = str(s)
489 except:
490 ss = s
491 return ss
492
493
494 def _getgrp(g,p):
495 import posixpath
496 grps = p.split("/")
497 for gname in grps:
498 if gname == "": continue
499 g = g.groups[gname]
500 return g
501
502 def ncinfo():
503
504 from netCDF4 import Dataset
505
506
507 usage = """
508 Print summary information about a netCDF file.
509
510 usage: %s [-h/--help] [-g grp or --group=grp] [-v var or --variable=var] [-d dim or --dimension=dim] filename
511
512 -h/--help -- Print usage message.
513 -g <group name> or --group=<group name> -- Print info for this group
514 (default is root group). Nested groups specified
515 using posix paths ("group1/group2/group3").
516 -v <variable name> or --variable=<variable name> -- Print info for this variable.
517 -d <dimension name> or --dimension=<dimension name> -- Print info for this dimension.
518
519 netcdf filename must be last argument.
520 \n""" % os.path.basename(sys.argv[0])
521
522 try:
523 opts, pargs = getopt.getopt(sys.argv[1:],'hv:g:d:',
524 ['group=',
525 'variable=',
526 'dimension='])
527 except:
528 (type, value, traceback) = sys.exc_info()
529 sys.stdout.write("Error parsing the options. The error was: %s\n" % value)
530 sys.stderr.write(usage)
531 sys.exit(0)
532
533 # Get the options
534 group = None; var = None; dim=None
535 for option in opts:
536 if option[0] == '-h' or option[0] == '--help':
537 sys.stderr.write(usage)
538 sys.exit(0)
539 elif option[0] == '--group' or option[0] == '-g':
540 group = option[1]
541 elif option[0] == '--variable' or option[0] == '-v':
542 var = option[1]
543 elif option[0] == '--dimension' or option[0] == '-d':
544 dim = option[1]
545 else:
546 sys.stdout.write("%s: Unrecognized option\n" % option[0])
547 sys.stderr.write(usage)
548 sys.exit(0)
549
550 # filename passed as last argumenbt
551 try:
552 filename = pargs[-1]
553 except IndexError:
554 sys.stdout.write("You need to pass netcdf filename!\n.")
555 sys.stderr.write(usage)
556 sys.exit(0)
557
558 f = Dataset(filename)
559 if group is None:
560 if var is None and dim is None:
561 print(f)
562 else:
563 if var is not None:
564 print(f.variables[var])
565 if dim is not None:
566 print(f.dimensions[dim])
567 else:
568 if var is None and dim is None:
569 print(_getgrp(f,group))
570 else:
571 g = _getgrp(f,group)
572 if var is not None:
573 print(g.variables[var])
574 if dim is not None:
575 print(g.dimensions[var])
576 f.close()
577
578 def _nc4tonc3(filename4,filename3,clobber=False,nchunk=10,quiet=False,format='NETCDF3_64BIT'):
579 """convert a netcdf 4 file (filename4) in NETCDF4_CLASSIC format
580 to a netcdf 3 file (filename3) in NETCDF3_64BIT format."""
581
582 from netCDF4 import Dataset
583
584 ncfile4 = Dataset(filename4,'r')
585 if ncfile4.file_format != 'NETCDF4_CLASSIC':
586 raise IOError('input file must be in NETCDF4_CLASSIC format')
587 ncfile3 = Dataset(filename3,'w',clobber=clobber,format=format)
588 # create dimensions. Check for unlimited dim.
589 unlimdimname = False
590 unlimdim = None
591 # create global attributes.
592 if not quiet: sys.stdout.write('copying global attributes ..\n')
593 #for attname in ncfile4.ncattrs():
594 # setattr(ncfile3,attname,getattr(ncfile4,attname))
595 ncfile3.setncatts(ncfile4.__dict__)
596 if not quiet: sys.stdout.write('copying dimensions ..\n')
597 for dimname,dim in ncfile4.dimensions.items():
598 if dim.isunlimited():
599 unlimdimname = dimname
600 unlimdim = dim
601 ncfile3.createDimension(dimname,None)
602 else:
603 ncfile3.createDimension(dimname,len(dim))
604 # create variables.
605 for varname,ncvar in ncfile4.variables.items():
606 if not quiet:
607 sys.stdout.write('copying variable %s\n' % varname)
608 # is there an unlimited dimension?
609 if unlimdimname and unlimdimname in ncvar.dimensions:
610 hasunlimdim = True
611 else:
612 hasunlimdim = False
613 if hasattr(ncvar, '_FillValue'):
614 FillValue = ncvar._FillValue
615 else:
616 FillValue = None
617 var = ncfile3.createVariable(varname,ncvar.dtype,ncvar.dimensions,fill_value=FillValue)
618 # fill variable attributes.
619 attdict = ncvar.__dict__
620 if '_FillValue' in attdict:
621 del attdict['_FillValue']
622 var.setncatts(attdict)
623 #for attname in ncvar.ncattrs():
624 # if attname == '_FillValue': continue
625 # setattr(var,attname,getattr(ncvar,attname))
626 # fill variables with data.
627 if hasunlimdim: # has an unlim dim, loop over unlim dim index.
628 # range to copy
629 if nchunk:
630 start = 0; stop = len(unlimdim); step = nchunk
631 if step < 1:
632 step = 1
633 for n in range(start, stop, step):
634 nmax = n+nchunk
635 if nmax > len(unlimdim):
636 nmax=len(unlimdim)
637 var[n:nmax] = ncvar[n:nmax]
638 else:
639 var[0:len(unlimdim)] = ncvar[:]
640 else: # no unlim dim or 1-d variable, just copy all data at once.
641 var[:] = ncvar[:]
642 ncfile3.sync() # flush data to disk
643 # close files.
644 ncfile3.close()
645 ncfile4.close()
646
647 def nc4tonc3():
648 usage = """
649 Convert a netCDF 4 file (in NETCDF4_CLASSIC format) to netCDF 3 format.
650
651 usage: %s [-h/--help] [-o] [--chunk] netcdf4filename netcdf3filename
652 -h/--help -- Print usage message.
653 -o -- Overwrite destination file (default is to raise an error if output file already exists).
654 --quiet=(0|1) -- if 1, don't print diagnostic information.
655 --format -- netcdf3 format to use (NETCDF3_64BIT by default, can be set to NETCDF3_CLASSIC)
656 --chunk=(integer) -- number of records along unlimited dimension to
657 write at once. Default 10. Ignored if there is no unlimited
658 dimension. chunk=0 means write all the data at once.
659 \n""" % os.path.basename(sys.argv[0])
660
661 try:
662 opts, pargs = getopt.getopt(sys.argv[1:], 'ho',
663 ['format=','chunk=','quiet='])
664 except:
665 (type, value, traceback) = sys.exc_info()
666 sys.stdout.write("Error parsing the options. The error was: %s\n" % value)
667 sys.stderr.write(usage)
668 sys.exit(0)
669
670 # default options
671 quiet = 0
672 chunk = 1000
673 format = 'NETCDF3_64BIT'
674 overwritefile = 0
675
676 # Get the options
677 for option in opts:
678 if option[0] == '-h' or option[0] == '--help':
679 sys.stderr.write(usage)
680 sys.exit(0)
681 elif option[0] == '-o':
682 overwritefile = 1
683 elif option[0] == '--quiet':
684 quiet = int(option[1])
685 elif option[0] == '--format':
686 format = option[1]
687 elif option[0] == '--chunk':
688 chunk = int(option[1])
689 else:
690 sys.stdout.write("%s : Unrecognized option\n" % options[0])
691 sys.stderr.write(usage)
692 sys.exit(0)
693
694 # if we pass a number of files different from 2, abort
695 if len(pargs) < 2 or len(pargs) > 2:
696 sys.stdout.write("You need to pass both source and destination!\n.")
697 sys.stderr.write(usage)
698 sys.exit(0)
699
700 # Catch the files passed as the last arguments
701 filename4 = pargs[0]
702 filename3 = pargs[1]
703
704 # copy the data from filename4 to filename3.
705 _nc4tonc3(filename4,filename3,clobber=overwritefile,quiet=quiet,format=format)
706
707
708 def _nc3tonc4(filename3,filename4,unpackshort=True,
709 zlib=True,complevel=6,shuffle=True,fletcher32=False,
710 clobber=False,lsd_dict=None,nchunk=10,quiet=False,classic=0,
711 vars=None,istart=0,istop=-1):
712 """convert a netcdf 3 file (filename3) to a netcdf 4 file
713 The default format is 'NETCDF4', but can be set
714 to NETCDF4_CLASSIC if classic=1.
715 If unpackshort=True, variables stored as short
716 integers with a scale and offset are unpacked to floats.
717 in the netcdf 4 file. If the lsd_dict is not None, variable names
718 corresponding to the keys of the dict will be truncated to the decimal place
719 specified by the values of the dict. This improves compression by
720 making it 'lossy'..
721 If vars is not None, only variable names in the list
722 will be copied (plus all the dimension variables).
723 The zlib, complevel and shuffle keywords control
724 how the compression is done."""
725
726 from netCDF4 import Dataset
727
728 ncfile3 = Dataset(filename3,'r')
729 if classic:
730 ncfile4 = Dataset(filename4,'w',clobber=clobber,format='NETCDF4_CLASSIC')
731 else:
732 ncfile4 = Dataset(filename4,'w',clobber=clobber,format='NETCDF4')
733 mval = 1.e30 # missing value if unpackshort=True
734 # create dimensions. Check for unlimited dim.
735 unlimdimname = False
736 unlimdim = None
737 # create global attributes.
738 if not quiet: sys.stdout.write('copying global attributes ..\n')
739 #for attname in ncfile3.ncattrs():
740 # setattr(ncfile4,attname,getattr(ncfile3,attname))
741 ncfile4.setncatts(ncfile3.__dict__)
742 if not quiet: sys.stdout.write('copying dimensions ..\n')
743 for dimname,dim in ncfile3.dimensions.items():
744 if dim.isunlimited():
745 unlimdimname = dimname
746 unlimdim = dim
747 ncfile4.createDimension(dimname,None)
748 if istop == -1: istop=len(unlimdim)
749 else:
750 ncfile4.createDimension(dimname,len(dim))
751 # create variables.
752 if vars is None:
753 varnames = ncfile3.variables.keys()
754 else:
755 # variables to copy specified
756 varnames = vars
757 # add dimension variables
758 for dimname in ncfile3.dimensions.keys():
759 if dimname in ncfile3.variables.keys() and\
760 dimname not in varnames:
761 varnames.append(dimname)
762 for varname in varnames:
763 ncvar = ncfile3.variables[varname]
764 if not quiet: sys.stdout.write('copying variable %s\n' % varname)
765 # quantize data?
766 if lsd_dict is not None and varname in lsd_dict:
767 lsd = lsd_dict[varname]
768 if not quiet: sys.stdout.write('truncating to least_significant_digit = %d\n'%lsd)
769 else:
770 lsd = None # no quantization.
771 # unpack short integers to floats?
772 if unpackshort and hasattr(ncvar,'scale_factor') and hasattr(ncvar,'add_offset'):
773 dounpackshort = True
774 datatype = 'f4'
775 else:
776 dounpackshort = False
777 datatype = ncvar.dtype
778 # is there an unlimited dimension?
779 if unlimdimname and unlimdimname in ncvar.dimensions:
780 hasunlimdim = True
781 else:
782 hasunlimdim = False
783 if dounpackshort:
784 if not quiet: sys.stdout.write('unpacking short integers to floats ...\n')
785 sys.stdout.write('')
786 # is there missing value?
787 if hasattr(ncvar, '_FillValue'):
788 fillvalue3 = ncvar._FillValue
789 elif hasattr(ncvar, 'missing_value'):
790 fillvalue3 = ncvar.missing_value
791 else:
792 fillvalue3 = None
793 if fillvalue3 is not None:
794 fillvalue4 = fillvalue3 if not dounpackshort else mval
795 else:
796 fillvalue4 = None
797 var = ncfile4.createVariable(varname,datatype,ncvar.dimensions, fill_value=fillvalue4, least_significant_digit=lsd,zlib=zlib,complevel=complevel,shuffle=shuffle,fletcher32=fletcher32)
798 # fill variable attributes.
799 attdict = ncvar.__dict__
800 if '_FillValue' in attdict: del attdict['_FillValue']
801 if dounpackshort and 'add_offset' in attdict:
802 del attdict['add_offset']
803 if dounpackshort and 'scale_factor' in attdict:
804 del attdict['scale_factor']
805 if dounpackshort and 'missing_value' in attdict:
806 attdict['missing_value'] = fillvalue4
807 var.setncatts(attdict)
808 # fill variables with data.
809 if hasunlimdim: # has an unlim dim, loop over unlim dim index.
810 # range to copy
811 if nchunk:
812 start = istart; stop = istop; step = nchunk
813 if step < 1: step = 1
814 for n in range(start, stop, step):
815 nmax = n+nchunk
816 if nmax > istop: nmax=istop
817 var[n-istart:nmax-istart] = ncvar[n:nmax]
818 else:
819 var[0:len(unlimdim)] = ncvar[:]
820 else: # no unlim dim or 1-d variable, just copy all data at once.
821 var[:] = ncvar[:]
822 ncfile4.sync() # flush data to disk
823 # close files.
824 ncfile3.close()
825 ncfile4.close()
826
827
828 def nc3tonc4():
829 usage = """
830 Convert a netCDF 3 file to netCDF 4 format, optionally
831 unpacking variables packed as short integers (with scale_factor and add_offset)
832 to floats, and adding zlib compression (with the HDF5 shuffle filter and fletcher32 checksum).
833 Data may also be quantized (truncated) to a specified precision to improve compression.
834
835 usage: %s [-h/--help] [-o] [--vars=var1,var2,..] [--zlib=(0|1)] [--complevel=(1-9)] [--shuffle=(0|1)] [--fletcher32=(0|1)] [--unpackshort=(0|1)] [--quantize=var1=n1,var2=n2,..] netcdf3filename netcdf4filename
836 -h/--help -- Print usage message.
837 -o -- Overwrite destination file (default is to raise an error if output file already exists).
838 --vars -- comma separated list of variable names to copy (default is to copy
839 all variables)
840 --classic=(0|1) -- use NETCDF4_CLASSIC format instead of NETCDF4 (default 1)
841 --zlib=(0|1) -- Activate (or disable) zlib compression (default is activate).
842 --complevel=(1-9) -- Set zlib compression level (6 is default).
843 --shuffle=(0|1) -- Activate (or disable) the shuffle filter (active by default).
844 --fletcher32=(0|1) -- Activate (or disable) the fletcher32 checksum (not
845 active by default).
846 --unpackshort=(0|1) -- Unpack short integer variables to float variables
847 using scale_factor and add_offset netCDF variable attributes (active by default).
848 --quantize=(comma separated list of "variable name=integer" pairs) --
849 Truncate the data in the specified variables to a given decimal precision.
850 For example, 'speed=2, height=-2, temp=0' will cause the variable
851 'speed' to be truncated to a precision of 0.01, 'height' to a precision of 100
852 and 'temp' to 1. This can significantly improve compression. The default
853 is not to quantize any of the variables.
854 --quiet=(0|1) -- if 1, don't print diagnostic information.
855 --chunk=(integer) -- number of records along unlimited dimension to
856 write at once. Default 10. Ignored if there is no unlimited
857 dimension. chunk=0 means write all the data at once.
858 --istart=(integer) -- number of record to start at along unlimited dimension.
859 Default 0. Ignored if there is no unlimited dimension.
860 --istop=(integer) -- number of record to stop at along unlimited dimension.
861 Default -1. Ignored if there is no unlimited dimension.
862 \n""" % os.path.basename(sys.argv[0])
863
864 try:
865 opts, pargs = getopt.getopt(sys.argv[1:], 'ho',
866 ['classic=',
867 'vars=',
868 'zlib=',
869 'quiet=',
870 'complevel=',
871 'shuffle=',
872 'fletcher32=',
873 'unpackshort=',
874 'quantize=',
875 'chunk=',
876 'istart=',
877 'istop='])
878 except:
879 (type, value, traceback) = sys.exc_info()
880 sys.stdout.write("Error parsing the options. The error was: %s\n" % value)
881 sys.stderr.write(usage)
882 sys.exit(0)
883
884 # default options
885 overwritefile = 0
886 complevel = 6
887 classic = 1
888 zlib = 1
889 shuffle = 1
890 fletcher32 = 0
891 unpackshort = 1
892 vars = None
893 quantize = None
894 quiet = 0
895 chunk = 1000
896 istart = 0
897 istop = -1
898
899 # Get the options
900 for option in opts:
901 if option[0] == '-h' or option[0] == '--help':
902 sys.stderr.write(usage)
903 sys.exit(0)
904 elif option[0] == '-o':
905 overwritefile = 1
906 elif option[0] == '--classic':
907 classic = int(option[1])
908 elif option[0] == '--zlib':
909 zlib = int(option[1])
910 elif option[0] == '--quiet':
911 quiet = int(option[1])
912 elif option[0] == '--complevel':
913 complevel = int(option[1])
914 elif option[0] == '--shuffle':
915 shuffle = int(option[1])
916 elif option[0] == '--fletcher32':
917 fletcher32 = int(option[1])
918 elif option[0] == '--unpackshort':
919 unpackshort = int(option[1])
920 elif option[0] == '--chunk':
921 chunk = int(option[1])
922 elif option[0] == '--vars':
923 vars = option[1]
924 elif option[0] == '--quantize':
925 quantize = option[1]
926 elif option[0] == '--istart':
927 istart = int(option[1])
928 elif option[0] == '--istop':
929 istop = int(option[1])
930 else:
931 sys.stdout.write("%s: Unrecognized option\n" % option[0])
932 sys.stderr.write(usage)
933 sys.exit(0)
934
935 # if we pass a number of files different from 2, abort
936 if len(pargs) < 2 or len(pargs) > 2:
937 sys.stdout.write("You need to pass both source and destination!.\n")
938 sys.stderr.write(usage)
939 sys.exit(0)
940
941 # Catch the files passed as the last arguments
942 filename3 = pargs[0]
943 filename4 = pargs[1]
944
945 # Parse the quantize option, create a dictionary from key/value pairs.
946 if quantize is not None:
947 lsd_dict = {}
948 for p in quantize.split(','):
949 kv = p.split('=')
950 lsd_dict[kv[0]] = int(kv[1])
951 else:
952 lsd_dict=None
953
954 # Parse the vars option, create a list of variable names.
955 if vars is not None:
956 vars = vars.split(',')
957
958 # copy the data from filename3 to filename4.
959 _nc3tonc4(filename3,filename4,unpackshort=unpackshort,
960 zlib=zlib,complevel=complevel,shuffle=shuffle,
961 fletcher32=fletcher32,clobber=overwritefile,lsd_dict=lsd_dict,
962 nchunk=chunk,quiet=quiet,vars=vars,classic=classic,
963 istart=istart,istop=istop)
964
965 def broadcasted_shape(shp1, shp2):
966 # determine shape of array of shp1 and shp2 broadcast against one another.
967 x = np.array([1])
968 # trick to define array with certain shape that doesn't allocate all the
969 # memory.
970 a = as_strided(x, shape=shp1, strides=[0] * len(shp1))
971 b = as_strided(x, shape=shp2, strides=[0] * len(shp2))
972 return np.broadcast(a, b).shape
3737 test_files.remove('tst_dap.py')
3838 test_files.insert(0,'tst_dap.py')
3939
40 # Don't run CDL test (that requires ncdump/ncgen)
41 if os.getenv('NO_CDL'):
42 test_files.remove('tst_cdl.py');
43 sys.stdout.write('not running tst_cdl.py ...\n')
44
4045 # Build the test suite from the tests found in the test files.
4146 testsuite = unittest.TestSuite()
4247 for f in test_files:
0 import unittest
1 import netCDF4
2 import os
3
4 test_ncdump="""netcdf ubyte {
5 dimensions:
6 d = 2 ;
7 variables:
8 byte ub(d) ;
9 ub:_Unsigned = "true" ;
10 byte sb(d) ;
11
12 // global attributes:
13 :_Format = "classic" ;
14 }
15 """
16 test_ncdump2="""netcdf ubyte {
17 dimensions:
18 d = 2 ;
19 variables:
20 byte ub(d) ;
21 ub:_Unsigned = "true" ;
22 byte sb(d) ;
23
24 // global attributes:
25 :_Format = "classic" ;
26 data:
27
28 ub = 0, -1 ;
29
30 sb = -128, 127 ;
31 }
32 """
33
34 class Test_CDL(unittest.TestCase):
35 """
36 Test import/export of CDL
37 """
38 def setUp(self):
39 f=netCDF4.Dataset('ubyte.nc')
40 f.tocdl(outfile='ubyte.cdl',data=True)
41 f.close()
42 def test_tocdl(self):
43 # treated as unsigned integers.
44 f=netCDF4.Dataset('ubyte.nc')
45 assert(f.tocdl() == test_ncdump)
46 assert(f.tocdl(data=True) == test_ncdump2)
47 f.close()
48 def test_fromcdl(self):
49 f1=netCDF4.Dataset.fromcdl('ubyte.cdl',ncfilename='ubyte2.nc')
50 f2=netCDF4.Dataset('ubyte.nc')
51 assert(f1.variables.keys() == f2.variables.keys())
52 assert(f1.filepath() == 'ubyte2.nc')
53 assert(f1.dimensions.keys() == f2.dimensions.keys())
54 assert(len(f1.dimensions['d']) == len(f2.dimensions['d']))
55 assert((f1['ub'][:] == f2['ub'][:]).all())
56 assert((f1['sb'][:] == f2['sb'][:]).all())
57 f1.close(); f2.close()
58 os.remove('ubyte2.nc')
59 def tearDown(self):
60 # Remove the temporary files
61 os.remove('ubyte.cdl')
62
63 if __name__ == '__main__':
64 unittest.main()
44 # test accessing data over http with opendap.
55
66 URL = "http://remotetest.unidata.ucar.edu/thredds/dodsC/testdods/testData.nc"
7 URL_https = 'https://podaac-opendap.jpl.nasa.gov/opendap/allData/modis/L3/aqua/11um/v2019.0/4km/daily/2017/365/AQUA_MODIS.20171231.L3m.DAY.NSST.sst.4km.nc'
78 varname = 'Z_sfc'
89 varmin = 0
910 varmax = 3292
2728 assert_array_almost_equal(data.min(),varmin)
2829 assert_array_almost_equal(data.max(),varmax)
2930 ncfile.close()
31 # test https support (linked curl lib must built with openssl support)
32 ncfile = netCDF4.Dataset(URL_https)
33 assert(ncfile['sst'].long_name=='Sea Surface Temperature')
34 ncfile.close()
3035
3136 if __name__ == '__main__':
3237 unittest.main()
2323 i = np.array([2,5,7],'i4')
2424 i2 = np.array([0,8],'i4')
2525 i3 = np.array([3,7,9,10],'i4')
26 ib = np.zeros(ydim,dtype=np.bool)
26 ib = np.zeros(ydim,dtype=np.bool_)
2727 ib[2] = True; ib[5] = True; ib[7] = True
28 ib2 = np.zeros(xdim, dtype=np.bool)
28 ib2 = np.zeros(xdim, dtype=np.bool_)
2929 ib2[1] = True; ib2[4] = True; ib2[6] = True
3030 # this one should be converted to a slice.
31 ib3 = np.zeros(xdim, dtype=np.bool)
31 ib3 = np.zeros(xdim, dtype=np.bool_)
3232 ib3[0] = True; ib2[4] = True; ib2[8] = True
3333 #seed(9) # fix seed
3434 data = randint(0,10,size=(xdim,ydim,zdim)).astype('i2')
8787 assert_array_equal(v[1:2,1:3,:], self.data[1:2,1:3,:])
8888 # Three integer sequences
8989 # sequences should be equivalent to booleans
90 ib1 = np.zeros(v.shape[0], np.bool); ib1[i]=True
91 ib2 = np.zeros(v.shape[1], np.bool); ib2[i2]=True
92 ib3 = np.zeros(v.shape[2], np.bool); ib3[i3]=True
90 ib1 = np.zeros(v.shape[0], np.bool_); ib1[i]=True
91 ib2 = np.zeros(v.shape[1], np.bool_); ib2[i2]=True
92 ib3 = np.zeros(v.shape[2], np.bool_); ib3[i3]=True
9393 assert_array_equal(v[i,i2,i3], v[ib1,ib2,ib3])
9494 assert_equal(v[i,i2,i3].shape, (len(i),len(i2),len(i3)))
9595
6363 v = f.createVariable('v',np.float32,'x',zlib=True,least_significant_digit=1)
6464 # assign masked array to that variable with one missing value.
6565 data =\
66 ma.array([1.5678,99.99,3.75145,4.127654],mask=np.array([False,True,False,False],np.bool))
66 ma.array([1.5678,99.99,3.75145,4.127654],mask=np.array([False,True,False,False],np.bool_))
6767 data.mask[1]=True
6868 v[:] = data
6969 f.close()
0 from netCDF4 import Dataset, MFDataset, MFTime, num2date, date2num, date2index
0 from netCDF4 import Dataset, MFDataset, MFTime
11 import numpy as np
22 from numpy.random import seed, randint
33 from numpy.testing import assert_array_equal, assert_equal
118118 calendar = 'standard'
119119
120120 # Get the real dates
121 # skip this until cftime pull request #55 is in a released
122 # version (1.0.1?). Otherwise, fix for issue #808 breaks this
123 if parse_version(cftime.__version__) >= parse_version('1.0.1'):
124 dates = []
125 for file in self.files:
126 f = Dataset(file)
127 t = f.variables['time']
128 dates.extend(num2date(t[:], t.units, calendar))
129 f.close()
130
121 dates = []
122 for file in self.files:
123 f = Dataset(file)
124 t = f.variables['time']
125 dates.extend(cftime.num2date(t[:], t.units, calendar))
126 f.close()
131127 # Compare with the MF dates
132128 f = MFDataset(self.files,check=True)
133129 t = f.variables['time']
134
135130 T = MFTime(t, calendar=calendar)
136131 assert_equal(T.calendar, calendar)
137132 assert_equal(len(T), len(t))
141136 # skip this until cftime pull request #55 is in a released
142137 # version (1.0.1?). Otherwise, fix for issue #808 breaks this
143138 if parse_version(cftime.__version__) >= parse_version('1.0.1'):
144 assert_array_equal(num2date(T[:], T.units, T.calendar), dates)
145 assert_equal(date2index(datetime.datetime(1980, 1, 2), T), 366)
139 assert_array_equal(cftime.num2date(T[:], T.units, T.calendar), dates)
140 assert_equal(cftime.date2index(datetime.datetime(1980, 1, 2), T), 366)
146141 f.close()
147142
148143 # Test exception is raised when no calendar attribute is available on the
0 from netCDF4 import Dataset, MFDataset, MFTime, num2date, date2num, date2index
0 from netCDF4 import Dataset, MFDataset, MFTime
11 import numpy as np
22 from numpy.random import seed, randint
33 from numpy.testing import assert_array_equal, assert_equal
110110 for file in self.files:
111111 f = Dataset(file)
112112 t = f.variables['time']
113 dates.extend(num2date(t[:], t.units, t.calendar))
113 dates.extend(cftime.num2date(t[:], t.units, t.calendar))
114114 f.close()
115115
116116 # Compare with the MF dates
117117 f = MFDataset(self.files,check=True)
118118 t = f.variables['time']
119 mfdates = num2date(t[:], t.units, t.calendar)
119 mfdates = cftime.num2date(t[:], t.units, t.calendar)
120120
121121 T = MFTime(t)
122122 assert_equal(len(T), len(t))
126126 # skip this until cftime pull request #55 is in a released
127127 # version (1.0.1?). Otherwise, fix for issue #808 breaks this
128128 if parse_version(cftime.__version__) >= parse_version('1.0.1'):
129 assert_array_equal(num2date(T[:], T.units, T.calendar), dates)
130 assert_equal(date2index(datetime.datetime(1980, 1, 2), T), 366)
129 assert_array_equal(cftime.num2date(T[:], T.units, T.calendar), dates)
130 assert_equal(cftime.date2index(datetime.datetime(1980, 1, 2), T), 366)
131131 f.close()
132132
133133 if __name__ == '__main__':
2323 return
2424
2525 with netCDF4.Dataset('foo_bar', memory=nc_bytes) as nc:
26 print(nc.filepath())
2726 assert nc.filepath() == 'foo_bar'
2827 assert nc.project_summary == 'Dummy netCDF file'
2928
44 file_name = tempfile.NamedTemporaryFile(suffix='.nc', delete=False).name
55 xdim=None; ydim=121; zdim=169
66 datashape = (ydim,zdim)
7 data = np.ones(datashape,dtype=np.float)
7 data = np.ones(datashape,dtype=np.float_)
88
99 class ShapeTestCase(unittest.TestCase):
1010
1414 f.createDimension('x',xdim)
1515 f.createDimension('y',ydim)
1616 f.createDimension('z',zdim)
17 v = f.createVariable('data',np.float,('x','y','z'))
17 v = f.createVariable('data',np.float_,('x','y','z'))
1818 f.close()
1919
2020 def tearDown(self):
128128 nlons = 12; lon = f.createDimension('lon',nlons)
129129 nlevs = 1; lev = f.createDimension('lev',nlevs)
130130 time = f.createDimension('time',None)
131 var = f.createVariable('var',np.float,('time','lev','lat','lon'))
131 var = f.createVariable('var',np.float_,('time','lev','lat','lon'))
132132 a = np.random.uniform(size=(10,nlevs,nlats,nlons))
133133 var[0:10] = a
134134 f.close()
167167 nlats = 11; lat = f.createDimension('lat',nlats)
168168 nlons = 20; lon = f.createDimension('lon',nlons)
169169 time = f.createDimension('time',None)
170 var = f.createVariable('var',np.float,('time','lat','lon'))
170 var = f.createVariable('var',np.float_,('time','lat','lon'))
171171 a = np.random.uniform(size=(3,nlats,nlons))
172172 var[[True,True,False,False,False,True]] = a
173173 var[0,2.0,"-1"] = 0 # issue 312
202202 td = nc.createDimension('t',None)
203203 xd = nc.createDimension('x',33)
204204 yd = nc.createDimension('y',4)
205 v = nc.createVariable('v',np.float,('t','x','y'))
205 v = nc.createVariable('v',np.float_,('t','x','y'))
206206 nc.close()
207207 nc = Dataset(self.file)
208208 data = np.empty(nc['v'].shape, nc['v'].dtype)
215215 f.createDimension('d1',3)
216216 f.createDimension('d2',None)
217217 f.createDimension('d3',5)
218 f.createVariable('v2',np.float,('d1','d2','d3'))
218 f.createVariable('v2',np.float_,('d1','d2','d3'))
219219 f['v2'][:] = np.zeros((3,4,5))
220220 f['v2'][0,:,0] = np.arange(4)
221221 f['v2'][0,:,:] = np.ones((4,5))
248248 assert_array_equal(f['v2'][:,1:3],np.arange(6,dtype=np.int).reshape(3,2))
249249 assert_array_equal(f['v2'][:,0],np.arange(3,dtype=np.int))
250250
251 def test_issue1083(self):
252 with Dataset(self.file, "w") as nc:
253 nc.createDimension("test", 5)
254 v = nc.createVariable("var", "f8", ("test", "test", "test"))
255 v[:] = 1 # works
256 v[:] = np.ones(()) # works
257 v[:] = np.ones((1,)) # works
258 v[:] = np.ones((5,)) # works
259 v[:] = np.ones((5,5,5)) # works
260 v[:] = np.ones((5,1,1)) # fails (before PR #1084)
261 v[:] = np.ones((5,1,5)) # fails (before PR #1084)
262 v[:] = np.ones((5,5,1)) # fails (before PR #1084)
263
251264 if __name__ == '__main__':
252265 unittest.main()
1717 f.attribute2 = ATT2
1818 f.attribute3 = ATT3
1919 d = f.createDimension(DIM_NAME, None)
20 v = f.createVariable(VAR_NAME, np.float, (DIM_NAME,))
20 v = f.createVariable(VAR_NAME, np.float_, (DIM_NAME,))
2121 f.close()
2222
2323 def tearDown(self):