Metview's Python interface provides access to all of Metview's Macro language functions, with automatic translations between data types. Here's an example that shows how to retrieve model and observation data and compute their difference, and the weighted mean value of that difference, both in Macro and in Python.

MacroPython


# Metview Macro

t2m_fc48 = retrieve(
    type    : "fc",
    levtype : "sfc",
    param   : "2t",
    date    : -5,
    step    : 48,
    grid    : "o1280")

synop = retrieve(
    type   : "ob",
    repres : "bu",
    date   : -3)

synop_t2m = obsfilter(
    output    : "geopoints",
    parameter : 012004,
    data      : synop)

diff = t2m_fc48 - synop_t2m
print(integrate(diff))



import metview as mv

t2m_fc48 = mv.retrieve(
    type    = "fc",
    levtype = "sfc",
    param   = "2t",
    date    = -5,
    step    = 48,
    grid    = "o1280")

synop = mv.retrieve(
    type   = "ob",
    repres = "bu",
    date   = -3)

synop_t2m = mv.obsfilter(
    output    = "geopoints",
    parameter = "012004",
    data      = synop)

diff = t2m_fc48 - synop_t2m
print(mv.integrate(diff))


You can see that the Macro functions are all available through the namespace defined in the import command.

More examples are available in the Gallery.

Variable types

When calling Macro functions from Python, variables passed as input to or output from those functions undergo a conversion as described in this table:

MacroPythonNotes
numbernumber
stringstring
listlistCan also pass a tuple to Macro, and it will be converted to a Macro list
fieldsetFieldsetLightweight wrapper class in Meview-Python
geopointsGeopointsLightweight wrapper class in Meview-Python
observationsBufrLightweight wrapper class in Meview-Python
netcdfNetCDFLightweight wrapper class in Meview-Python
odbOdbLightweight wrapper class in Meview-Python
tableTableLightweight wrapper class in Meview-Python
vectornumPy array
datedatetimeCan also pass a date or a datetime64 to Macro
definitiondictionary
nilNone

Additional data export features

NumPy arrays

Any Metview function that normally returns a vector will return a numPy array when called from Python. For example, the follownig fieldset functions return numPy arrays:

a = mv.read('my_data.grib') # returns a Fieldset
lats = mv.latitudes(a)      # returns a numPy array
lons = mv.longitudes(a)     # returns a numPy array
vals = mv.values(a)         # returns a numPy array

Pandas Dataframes

The Geopoints data type has an additional function, to_dataframe(), which can be used to produce a Pandas Dataframe object as shown:

import metview as mv
import pandas as pd

gpt = mv.read("gpts.gpt") # returns a Geopoints
df = gpt.to_dataframe()   # returns a Pandas Dataframe
print(df.head())

Output:

                 date  latitude   level  longitude    value
0 2018-01-14 12:00:00      30.0  1000.0      -24.0  288.736
1 2018-01-14 12:00:00      30.0  1000.0      -18.0  288.736
2 2018-01-14 12:00:00      30.0  1000.0      -12.0  286.736
3 2018-01-14 12:00:00      30.0  1000.0       -6.0      NaN
4 2018-01-14 12:00:00      30.0  1000.0        0.0      NaN

Xarray Datasets

The Fieldset object has an additional method, to_dataset(), which produces an xarray Dataset object from the given fieldset. This is an N-dimensional data array based on the Common Data Model used in netCDF. For example:

import metview as mv

t2m_fc = mv.retrieve(
	type    = 'fc',
	levtype = 'sfc',
	param   = ['2t', '2d'],
	date    = -5,
	step    = list(range(0, 48+1, 6)),
	grid    = [1,1]
)

xa = t2m_fc.to_dataset()
print(xa)

will produce the following output:

<xarray.Dataset>
Dimensions:    (latitude: 181, longitude: 360, step: 9, time: 1)
Coordinates:
  * time       (time) datetime64[ns] 2018-05-10T12:00:00
  * step       (step) timedelta64[ns] 0 days 00:00:00 0 days 06:00:00 ...
  * latitude   (latitude) float64 90.0 89.0 88.0 87.0 86.0 85.0 84.0 83.0 ...
  * longitude  (longitude) float64 0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 ...
Data variables:
    2t         (time, step, latitude, longitude) float32 ...
    2d         (time, step, latitude, longitude) float32 ...
Attributes:
    Conventions:  CF-1.7
    comment:      GRIB to CF translation performed by xarray-grib

This is based on the Open Source cfgrib package which is planned to be ultimately integrated into xarray.

Icon functions

Macro functions which correspond to icons, such as retrieve(), which corresponds to the Mars Retrieval icon, can take their arguments in a number of ways:

MethodExample
Named argumentsa = mv.retrieve(type = 'fc', date = -5)
Dictionary

params = {'type' : 'fc', 'date' : -5}
a = mv.retrieve(params)

Combination

common_params = {'type' : 'fc'}
a = mv.retrieve(common_params, date = -5)

Object-oriented calling

Metview's Python interface also provides a more object-oriented way of using the wrapper classes such as Fieldset. The following two snippets of code are equivalent:

FunctionObject method

# find the locations where t is > 310K

t = mv.retrieve(param = 't', grid = [1,1])
hot = t > 310
locs = find(hot, 1)

# find the locations where t is > 310K

t = mv.retrieve(param = 't', grid = [1,1])
hot = t > 310
locs = hot.find(1)

Calling user-defined Macro functions from Python

Any user-defined Macro function can be called from Python as long as it satisfies both of these criteria:

  1. the function must reside in a file of the same name as the function
  2. the file must be in a directory listed in the METVIEW_MACRO_PATH environment variable; this variable can be modified by the user, but by default it will include $HOME/metview/System/Macros.

If these are satisfied, then the function may be invoked using the call() command as shown here:

import metview as mv
mv.call('my_func', 4, 1, 'my_string_arg'))

The first argument is the name of the function, the subsequent arguments will be passed to the function.

Things to watch out for

Although it's easy to convert an existing macro into a Python script, there are some things to be aware of.