Ctrl+K

Interfacing with Flag Information

Interfacing with Flag Information#

obsarray enables users to define, store and interface with flag variables in xarray.Dataset’s following the CF Convention metadata standard.

To access the information from a particular flag variable, use the dataset’s flag accessor.

You can see which dataset variables are flag variables by looking at the flag accessor keys.

In [1]: import obsarray

In [2]: ds.flag.keys()
Out[2]: ['time_flags']

This means this dataset contains one flag variable called "time_flags".

Interfacing with a Flag Variable#

To inspect the data for a particular flag defined for a flag variable, index the flag accessor with it’s name.

In [3]: ds.flag["time_flags"]
Out[3]: 
<FlagVariable>
FlagVariable: 'time_flags'
['dubious', 'invalid']

This returns a FlagVariable object, which provides an interface to the flags defined by a flag variable. You can see which flags are defined by the flag variable by looking at the its keys.

In [4]: ds.flag["time_flags"].keys()
Out[4]: ['dubious', 'invalid']

This means the time_flags variable defines two flags called "dubious" and "invalid". Therefore, the first two datum bits for each element of the time_flags variable array corresponds to boolean condition flags with these meanings (as per the CF Convention). obarray makes the bit handling for these flags simple.

Interfacing with Flags in Flag Variables#

To inspect a specific flag of particular flag variable, index the flag variable with its name.

In [5]: ds.flag["time_flags"]["dubious"]
Out[5]: 
<Flag> 
(time: 3)> Size: 3B
array([False, False, False])
Dimensions without coordinates: time

This returns a Flag object, which provides an interface to a specific uncertainty variable.

The mask that represents the flag can be returned as an xarray.DataArray as:

In [6]: print(ds.flag["time_flags"]["dubious"].value)
<xarray.DataArray (time: 3)> Size: 3B
array([False, False, False])
Dimensions without coordinates: time

Flag values can be set:

In [7]: ds.flag["time_flags"]["dubious"][0] = True

In [8]: print(ds.flag["time_flags"]["dubious"])
<Flag> 
(time: 3)> Size: 3B
array([ True, False, False])
Dimensions without coordinates: time

Adding/Removing Flags#

The same interface can be used to add/remove flags from the dataset. A new flag variable can be added following a similar syntax to the xarray convention, as ds.flag["flag_var"] = (dims, attributes). The attributes must contain a list of "flag_meanings".

In [9]: ds.flag["spatial_flags"] = (
   ...:     ["lat", "lon"],
   ...:     {"flag_meanings": ["land", "ocean"]}
   ...: )
   ...: 

In [10]: print(ds.flag)
<FlagAccessor>
Dataset Flags:
* <FlagVariable>
FlagVariable: 'time_flags'
['dubious', 'invalid']
* <FlagVariable>
FlagVariable: 'spatial_flags'
['land', 'ocean']

A new flag to an existing flag variable as follows,

In [11]: ds.flag["spatial_flags"]["ice"] = False

In [12]: print(ds.flag)
<FlagAccessor>
Dataset Flags:
* <FlagVariable>
FlagVariable: 'time_flags'
['dubious', 'invalid']
* <FlagVariable>
FlagVariable: 'spatial_flags'
['land', 'ocean', 'ice']
Contents