PyNGL Home > Functions > Array query

Ngl.dim_gbits

Unpacks bit chunks from the rightmost dimension of the input array.

Available in version 1.4.0 or later.

Prototype

isam = Ngl.dim_gbits (npack,ibit,nbits,nskip,iter)

Arguments

npack

A numpy byte, ubyte, short, ushort, or integer array of any dimensionality. The rightmost dimension will be unpacked. Python ints will work as well.

ibit

A bit-count offset to be used before the first bit chunk is unpacked. For example, if npack is one-dimensional and if ibit=3 and nbits=5, then 3 bits in npack will be skipped and the next 5 bits will be unpacked into the returned array.

nbits

The number of bits in each bit chunk to be unpacked.

nskip

The number of bits to skip between each bit chunk to be unpacked (after the first bit chunk has been unpacked).

iter

The number of bit chunks to be unpacked. Usually, iter is the same size as the rightmost dimension of npack.

Return value

isam

The return array will be the same type as npack. The dimensionality will depend on the remaining input parameters (see description and examples below).

Description

Ngl.dim_gbits unpacks bit chunks from the input array npack into an output array isam. iter bit chunks of length nbits with nskip bits being skipped between each bit chunk in the input array are unpacked into isam. Each bit chunk in the input array is unpacked into a separate word in isam, right-justified with zero-fill. Initially, ibit bits will be skipped at the beginning of the input array before unpacking.

The following depicts the role of each argument. Assume ibit=5, nbits=2, nskip=3 and iter=4:

    npack:    0101011111100100110100
              ^^^^^                       skip first 5 bits
                   ^^                     iter=1 extract 11 ==> integer 3
                     ^^^                  skip 3 bits
                        ^^                iter=2 extract 10 ==> integer 2
                          ^^^             skip 3 bits    
                             ^^           iter=3         01 ==> integer 1
                               ^^^        skip 3 bits
                                  ^^      iter=4         00 ==> integer 0    

Examples

Example 1

Assume x is a one dimensional array of length N.

import Ngl
isam = Ngl.dim_gbits (x,3,6,9,2)

3 bits will be skipped at the beginning of x. The next 6 bits will be unpacked into xchunk(0) right-justified with zero-fill. 9 bits will be skipped in x. The next six bits of x will be unpacked into xchunk(1) right-justified with zero-fill. The return array xchunk will be the same type as x and be of length 2.

Example 2

Assume x is a 5D array with dimensions ntim x klvl x nlat x mlon x N and of type byte. Then:

xchunk = Ngl.dim_gbits (x,0,2,6,N)

0 bits will be skipped at the beginning of the rightmost dimension of x. The first 2 bits of the rightmost dimension will be unpacked into the rightmost dimension of xchunk({...},0) right-justified with zero-fill. 6 bits will be skipped in the rightmost dimension of x. The next 2 bits of x will be unpacked into xchunk({...},1) right-justified with zero-fill. This will continue N times. The return array xchunk will be the same type and shape as x.

Also see example "hdf1.py" in the PyNGL gallery.