grib2io.tables API documentation

# grib2io.tables

Functions for retreiving data from NCEP GRIB2 Tables.

View Source

      1"""
      2Functions for retreiving data from NCEP GRIB2 Tables.
      3"""
      4
      5from .section0 import *
      6from .section1 import *
      7from .section3 import *
      8from .section4 import *
      9from .section5 import *
     10from .originating_centers import *
     11
     12
     13def get_table(table, expand=False):
     14    """
     15    Return GRIB2 code table as a dictionary.
     16
     17    Parameters
     18    ----------
     19
     20    **`table`**: Code table number (e.g. '1.0'). NOTE: Code table '4.1' requires a 3rd value
     21    representing the product discipline (e.g. '4.1.0').
     22
     23    **`expand`**: If `True`, expand output dictionary where keys are a range.
     24
     25    Returns
     26    -------
     27
     28    **`dict`**
     29    """
     30    if len(table) == 3 and table == '4.1':
     31        raise Exception('GRIB2 Code Table 4.1 requires a 3rd value representing the discipline.')
     32    if len(table) == 3 and table.startswith('4.2'):
     33        raise Exception('Use function get_varinfo_from_table() for GRIB2 Code Table 4.2')
     34    try:
     35        tbl = globals()['table_'+table.replace('.','_')]
     36        if expand:
     37            _tbl = {}
     38            for k,v in tbl.items():
     39                if '-' in k:
     40                    irng = [int(i) for i in k.split('-')]
     41                    for i in range(irng[0],irng[1]+1):
     42                        _tbl[str(i)] = v
     43                else:
     44                    _tbl[k] = v
     45            tbl = _tbl
     46        return tbl
     47    except(KeyError):
     48        return {}
     49
     50
     51def get_value_from_table(value, table):
     52    """
     53    Return the definition given a GRIB2 code table.
     54
     55    Parameters
     56    ----------
     57
     58    **`value`**: `int` or `str` code table value.
     59
     60    **`table`**: `str` code table number.
     61
     62    Returns
     63    -------
     64
     65    Table value or `None` if not found.
     66    """
     67    try:
     68        tbl = get_table(table,expand=True)
     69        if isinstance(value,int): value = str(value)
     70        return tbl[value]
     71    except(KeyError):
     72        return None
     73
     74
     75def get_varinfo_from_table(discipline,parmcat,parmnum):
     76    """
     77    Return the GRIB2 variable information given values of `discipline`,
     78    `parmcat`, and `parmnum`. NOTE: This functions allows for all arguments
     79    to be converted to a string type if arguments are integer.
     80
     81    Parameters
     82    ----------
     83
     84    **`discipline`**: `int` or `str` of Discipline code value of a GRIB2 message.
     85
     86    **`parmcat`**: `int` or `str` of Parameter Category value of a GRIB2 message.
     87
     88    **`parmnum`**: `int` or `str` of Parameter Number value of a GRIB2 message.
     89
     90    Returns
     91    -------
     92
     93    **`list`**: containing variable information. "Unknown" is given for item of
     94    information if variable is not found.
     95    - list[0] = full name
     96    - list[1] = units
     97    - list[2] = short name (abbreviated name)
     98    """
     99    if isinstance(discipline,int): discipline = str(discipline)
    100    if isinstance(parmcat,int): parmcat = str(parmcat)
    101    if isinstance(parmnum,int): parmnum = str(parmnum)
    102    try:
    103        tblname = 'table_4_2_'+discipline+'_'+parmcat
    104        modname = '.section4_discipline'+discipline
    105        exec('from '+modname+' import *')
    106        return locals()[tblname][parmnum]
    107    except(ImportError,KeyError):
    108        return ['Unknown','Unknown','Unknown']
    109
    110
    111def get_wgrib2_level_string(type1,sfac1,sval1,type2,sfac2,sval2):
    112    """
    113    Return a string that describes the level or layer of the GRIB2 message. The
    114    format and language of the string is an exact replica of how wgrib2 produces
    115    the level/layer string in its inventory output.
    116
    117    Contents of wgrib2 source, [Level.c](https://github.com/NOAA-EMC/NCEPLIBS-wgrib2/blob/develop/wgrib2/Level.c),
    118    were converted into a Python dictionary and stored in grib2io as table
    119    'wgrib2_level_string'.
    120
    121    Parameters
    122    ----------
    123
    124    **`type1`**: `int` type of first fixed surface.
    125
    126    **`sfac1`**: `int` scale factor of first fixed surface.
    127
    128    **`sval1`**: `int` scaled value of first fixed surface.
    129
    130    **`type2`**: `int` type of second fixed surface.
    131
    132    **`sfac2`**: `int` scale factor of second fixed surface.
    133
    134    **`sval2`**: `int` scaled value of second fixed surface.
    135
    136    Returns
    137    -------
    138
    139    **`str`**: wgrib2-formatted level/layer string.
    140    """
    141    lvlstr = ''
    142    val1 = sval1/10**sfac1
    143    if type1 in [100,108]: val1 *= 0.01
    144    if type2 != 255:
    145        # Layer
    146        #assert type2 == type1, "Surface types are not equal: %g - %g" % (type1,type2)
    147        val2 = sval2/10**sfac2
    148        if type2 in [100,108]: val2 *= 0.01
    149        lvlstr = get_value_from_table(type1,table='wgrib2_level_string')[1]
    150        vals = (val1,val2)
    151    else:
    152        # Level
    153        lvlstr = get_value_from_table(type1,table='wgrib2_level_string')[0]
    154        vals = (val1)
    155    if '%g' in lvlstr: lvlstr %= vals
    156    return lvlstr

def get_table(table, expand=False) View Source

    14def get_table(table, expand=False):
    15    """
    16    Return GRIB2 code table as a dictionary.
    17
    18    Parameters
    19    ----------
    20
    21    **`table`**: Code table number (e.g. '1.0'). NOTE: Code table '4.1' requires a 3rd value
    22    representing the product discipline (e.g. '4.1.0').
    23
    24    **`expand`**: If `True`, expand output dictionary where keys are a range.
    25
    26    Returns
    27    -------
    28
    29    **`dict`**
    30    """
    31    if len(table) == 3 and table == '4.1':
    32        raise Exception('GRIB2 Code Table 4.1 requires a 3rd value representing the discipline.')
    33    if len(table) == 3 and table.startswith('4.2'):
    34        raise Exception('Use function get_varinfo_from_table() for GRIB2 Code Table 4.2')
    35    try:
    36        tbl = globals()['table_'+table.replace('.','_')]
    37        if expand:
    38            _tbl = {}
    39            for k,v in tbl.items():
    40                if '-' in k:
    41                    irng = [int(i) for i in k.split('-')]
    42                    for i in range(irng[0],irng[1]+1):
    43                        _tbl[str(i)] = v
    44                else:
    45                    _tbl[k] = v
    46            tbl = _tbl
    47        return tbl
    48    except(KeyError):
    49        return {}

Return GRIB2 code table as a dictionary.

## Parameters

`table`: Code table number (e.g. '1.0'). NOTE: Code table '4.1' requires a 3rd value representing the product discipline (e.g. '4.1.0').

`expand`: If `True`, expand output dictionary where keys are a range.

## Returns

`dict`

def get_value_from_table(value, table) View Source

    52def get_value_from_table(value, table):
    53    """
    54    Return the definition given a GRIB2 code table.
    55
    56    Parameters
    57    ----------
    58
    59    **`value`**: `int` or `str` code table value.
    60
    61    **`table`**: `str` code table number.
    62
    63    Returns
    64    -------
    65
    66    Table value or `None` if not found.
    67    """
    68    try:
    69        tbl = get_table(table,expand=True)
    70        if isinstance(value,int): value = str(value)
    71        return tbl[value]
    72    except(KeyError):
    73        return None

Return the definition given a GRIB2 code table.

## Parameters

`value`: `int` or `str` code table value.

`table`: `str` code table number.

## Returns

Table value or `None` if not found.

def get_varinfo_from_table(discipline, parmcat, parmnum) View Source

     76def get_varinfo_from_table(discipline,parmcat,parmnum):
     77    """
     78    Return the GRIB2 variable information given values of `discipline`,
     79    `parmcat`, and `parmnum`. NOTE: This functions allows for all arguments
     80    to be converted to a string type if arguments are integer.
     81
     82    Parameters
     83    ----------
     84
     85    **`discipline`**: `int` or `str` of Discipline code value of a GRIB2 message.
     86
     87    **`parmcat`**: `int` or `str` of Parameter Category value of a GRIB2 message.
     88
     89    **`parmnum`**: `int` or `str` of Parameter Number value of a GRIB2 message.
     90
     91    Returns
     92    -------
     93
     94    **`list`**: containing variable information. "Unknown" is given for item of
     95    information if variable is not found.
     96    - list[0] = full name
     97    - list[1] = units
     98    - list[2] = short name (abbreviated name)
     99    """
    100    if isinstance(discipline,int): discipline = str(discipline)
    101    if isinstance(parmcat,int): parmcat = str(parmcat)
    102    if isinstance(parmnum,int): parmnum = str(parmnum)
    103    try:
    104        tblname = 'table_4_2_'+discipline+'_'+parmcat
    105        modname = '.section4_discipline'+discipline
    106        exec('from '+modname+' import *')
    107        return locals()[tblname][parmnum]
    108    except(ImportError,KeyError):
    109        return ['Unknown','Unknown','Unknown']

Return the GRIB2 variable information given values of `discipline`, `parmcat`, and `parmnum`. NOTE: This functions allows for all arguments to be converted to a string type if arguments are integer.

## Parameters

`discipline`: `int` or `str` of Discipline code value of a GRIB2 message.

`parmcat`: `int` or `str` of Parameter Category value of a GRIB2 message.

`parmnum`: `int` or `str` of Parameter Number value of a GRIB2 message.

## Returns

`list`: containing variable information. "Unknown" is given for item of information if variable is not found.

- list[0] = full name
- list[1] = units
- list[2] = short name (abbreviated name)

def get_wgrib2_level_string(type1, sfac1, sval1, type2, sfac2, sval2) View Source

    112def get_wgrib2_level_string(type1,sfac1,sval1,type2,sfac2,sval2):
    113    """
    114    Return a string that describes the level or layer of the GRIB2 message. The
    115    format and language of the string is an exact replica of how wgrib2 produces
    116    the level/layer string in its inventory output.
    117
    118    Contents of wgrib2 source, [Level.c](https://github.com/NOAA-EMC/NCEPLIBS-wgrib2/blob/develop/wgrib2/Level.c),
    119    were converted into a Python dictionary and stored in grib2io as table
    120    'wgrib2_level_string'.
    121
    122    Parameters
    123    ----------
    124
    125    **`type1`**: `int` type of first fixed surface.
    126
    127    **`sfac1`**: `int` scale factor of first fixed surface.
    128
    129    **`sval1`**: `int` scaled value of first fixed surface.
    130
    131    **`type2`**: `int` type of second fixed surface.
    132
    133    **`sfac2`**: `int` scale factor of second fixed surface.
    134
    135    **`sval2`**: `int` scaled value of second fixed surface.
    136
    137    Returns
    138    -------
    139
    140    **`str`**: wgrib2-formatted level/layer string.
    141    """
    142    lvlstr = ''
    143    val1 = sval1/10**sfac1
    144    if type1 in [100,108]: val1 *= 0.01
    145    if type2 != 255:
    146        # Layer
    147        #assert type2 == type1, "Surface types are not equal: %g - %g" % (type1,type2)
    148        val2 = sval2/10**sfac2
    149        if type2 in [100,108]: val2 *= 0.01
    150        lvlstr = get_value_from_table(type1,table='wgrib2_level_string')[1]
    151        vals = (val1,val2)
    152    else:
    153        # Level
    154        lvlstr = get_value_from_table(type1,table='wgrib2_level_string')[0]
    155        vals = (val1)
    156    if '%g' in lvlstr: lvlstr %= vals
    157    return lvlstr

Return a string that describes the level or layer of the GRIB2 message. The format and language of the string is an exact replica of how wgrib2 produces the level/layer string in its inventory output.

Contents of wgrib2 source, Level.c, were converted into a Python dictionary and stored in grib2io as table 'wgrib2_level_string'.

## Parameters

`type1`: `int` type of first fixed surface.

`sfac1`: `int` scale factor of first fixed surface.

`sval1`: `int` scaled value of first fixed surface.

`type2`: `int` type of second fixed surface.

`sfac2`: `int` scale factor of second fixed surface.

`sval2`: `int` scaled value of second fixed surface.

## Returns

`str`: wgrib2-formatted level/layer string.