odb_visualiser

../../_images/ODB_VISUALISER.png

Defines the visualisation for Odb data using various plot types. Optionally it can perform an ODB/SQL query on the input ODB and visualises the resulting data. It works for both databases (ODB-1) and files (ODB-2 or ODC).

Tip

A tutorial about using ODB in Metview can be found here.

How can ODB/SQL queries be used in odb_visualiser?

The queries cannot directly be used but have to be mapped for a specific set of arguments. We illustrate it with a simple example. Let us suppose we want to perform this ODB/SQL query on our data:

SELECT
    lat@hdr,
    lon@hdr,
    fg_depar@body
WHERE
    vertco_reference_1@body = 5
ORDERBY
    obsvalue@body

and want to plot the results as points (symbols) on a map. To achieve this we need to use the following code:

import metview as mv

db = mv.read("my_data.odb")

vis = mv.odb_viusaliser(
    odb_data=db,
    odb_latitude_variable="lat@hdr",
    odb_longitude_variable="lon@hdr",
    odb_value_variable="fg_depar@body",
    odb_where="vertco_reference_1@body = 5",
    odb_orderby="obsvalue@body")

mv.plot(vis)

Note

This function performs the same task as the ODB Visualiser icon in Metview’s user interface. It accepts its parameters as keyword arguments, described below.

odb_visualiser(**kwargs)

Defines the visualisation for ODB data.

Parameters

  • odb_plot_type ({"geo_points", "geo_vectors", "xy_points", "xy_vectors", "xy_binning"}, default: "geo_points") –

    Specifies the plot type to be generated. The possible values are as follows:

    • ”geo_points”: points plotted onto a map

    • ”geo_vectors”: vectors plotted onto a map

    • ”xy_points”: points plotted into a cartesianview()

    • ”xy_vectors”: vectors plotted into a cartesianview()

    • ”xy_binning”: gridded values formed by 2D-binning plotted into a cartesianview()

  • odb_filename (str, default: "off") – Specifies the path to the input ODB.

  • odb_data (Odb) – Specifies the input Odb. If both odb_data and odb_filename are specified odb_data takes precedence.

  • odb_x_type ({"number", "date"}, default: "number") – Specifies the type of the x coordinate when odb_plot_type is set to “xy_points”, “xy_vectors” or “xy_binning”.

  • odb_y_type ({"number", "date"}, default: "number") – Specifies the type of the y coordinate when odb_plot_type is set to “xy_points”, “xy_vectors” or “xy_binning”.

  • odb_x_variable (str) – Specifies the ODB column interpreted as the x coordinate when odb_plot_type is set to “geo_vectors”, “xy_vectors” or “xy_binning”. The default is an empty string.

  • odb_y_variable (str) – Specifies the ODB column interpreted as the y coordinate when odb_plot_type is set to “geo_vectors”, “xy_vectors” or “xy_binning”. The default is an empty string.

  • odb_latitude_variable (str, default: "lat@hdr") – Specifies the ODB column interpreted as latitude when odb_plot_type is set to “geo_points” or “geo_vectors”.

  • odb_longitude_variable (str, default: "lon@hdr") – Specifies the ODB column interpreted as longitude when odb_plot_type is set to “geo_points” or “geo_vectors”.

  • odb_x_component_variable (str, default: "obsvalue@body") – Specifies the ODB column interpreted as the x component of the vector when odb_plot_type is set to “geo_vectors” or “xy_vectors”.

  • odb_y_component_variable (str, default: "obsvalue@body#1") – Specifies the ODB column interpreted as the y component of the vector when odb_plot_type is set to “geo_vectors” or “xy_vectors”.

  • odb_value_variable (str, default: "obsvalue@body") – Specifies the ODB column interpreted as the value in each plot type.

  • odb_metadata_variables (str or list[str]) – Specifies the list of columns extracted and added to the resulting ODB file on top of the columns directly used for visualisation. This parameter accepts wildcards (e.g. “*.hdr”), to add all the columns from the source ODB to the result use “*”. The default is an empty string (no extra columns added).

  • odb_parameters (str) –

  • odb_from (str) – Defines the FROM statement of the ODB/SQL query.

  • odb_where (str) – Defines the WHERE statement of the ODB/SQL query.

  • odb_orderby (str) – Defines the ORDERBY statement of the ODB/SQL query.

  • odb_nb_rows (number, default: -1) – Specifies the maximum number of rows in the result. If it is set to -1 the number of rows is not limited in the output.

  • odb_coordinates_unit ({"degrees", "radians"}, default: "degrees") – Specifies the units of the geographical co-ordinates in the input ODB. For older ODBs column “latlon_rad@desc” tells us the geographical co-ordinate units. Its 0 value indicates “degrees” while 1 means radians. Newer ODBs, especially the ones retrieved from MARS, as a generic rule, always use “degrees” as geographical co-ordinate units.

  • odb_binning (Request) – Specifies the binning() to create gridded data out of scattered data when the odb_plot_type is “xy_binning”.

  • fail_on_empty_output ({"yes", "no"}, default: "yes") – Controls the behaviour when the resulting Odb is empty. If it is set to “no” odb_visualiser() will return None, while if the value is “yes” the Python script running odb_visualiser() will abort.

Return type

Request