.. _mhovmoeller_vertical_icon:


mhovmoeller_vertical
===============================================

.. container::
    
    .. container:: leftside

        .. image:: /_static/MHOVMOELLERDATA.png
           :width: 48px

    .. container:: rightside

		Generates a vertical Hovmoeller diagram data unit for a given geographical area for GRIB (:class:`Fieldset`) input. The generated data can be used to display a two-dimensional graph with levels as one axis and time as the other. 
		
		The resulting data can be plotted (using a default visualisation and with the plot area based on the range of data values) or saved as a NetCDF data file using :func:`write`.
		
		If access to the computed values is not required, or for more control of the plotting, use :func:`mhovmoellerview`.
		
		.. note::
		
		    See also :func:`mhovmoeller_area`, :func:`mhovmoeller_line` and :func:`mhovmoeller_expand`.


		.. note:: This function performs the same task as the **Hovmoeller Data** icon in Metview’s :ref:`user interface <user_interface>`. It accepts its parameters as keyword arguments, described below.


.. py:function:: mhovmoeller_vertical(**kwargs)
  
    Provides input for Hovemoeller diagrams derived at an input geographical location/area and on a set of levels.


    :param input_mode: Defines the horizontal data selection method:
		
		* "point": the data is interpolated to the location specified by ``point``
		* "nearest_gridpoint": the nearest gridpoint to the location specified by ``point`` is extracted
		* "area": the values inside the ``area`` are averaged using :func:`integrate`
		
		*New in Metview version 5.16.0*
    :type input_mode: {"point", "nearest_gridpoint", "area"}, default: "area"

    :param point: Specifies the coordinates (as [lat, lon]) of the point for which the vertical Hovmoeller is computed. Enabled when ``input_mode`` is "point" or "nearest_gridpoint". *New in Metview version 5.16.0*
    :type point: list[number], default: [0, 0]

    :param area: Specifies the coordinates of the area (as [north, west, south, east]) over which the Hovmoeller diagram is calculated. Enabled when ``input_mode`` is "area".
    :type area: list[number], default: [30, -30, -30, 30]

    :param area_statistics: Specifies the type of computation performed for the ``area``. For "mean", "stdev" or "variance" the aggregation is weighted by the cosine of the latitudes. Enabled when ``input_mode`` is "area". *New in Metview version 5.18.0*
    :type area_statistics: {"mean", "minimum", "maximum", "stdev", "variance", "median"}, default: "mean"

    :param data: Specifies the input GRIB data for the Hovmeller diagram. ``data`` must contain a time-series of a single meteorological variable on a latitude-longitude or Gaussian grid, on a set of vertical levels. If ``data`` is specified on ECMWF model levels and ``vertical_level_type`` is "pressure" ``data`` must also contain an Logarithm of Surface Pressure (LNSP) field (see ``lnsp_param``) for each step, otherwise the pressure on the model levels cannot be computed.
    :type data: :class:`Fieldset`

    :param vertical_level_type: Specifies the output vertical level type:
		
		* "as_in_data": the level type of ``data`` is used. In this case ``top_level`` and ``bottom_level`` must always be set carefully, since their default values are set for pressure in hPa.
		* "pressure": indicates that the ``data`` is defined on ECMWF model levels and the output vertical coordinate should be pressure in hPa. When this option is selected the input data must contain the corresponding Logarithm of Surface Pressure (LNSP) fields, unless a fixed surface pressure is used (see ``use_fixed_surface_pressure``).
		* "user": the vertical coordinates (both input and output) are defined by the fields of ``vertical_coordinate_param``. In this case ``top_level`` and ``bottom_level`` must always be set carefully, since their default values are set for pressure in hPa. *New in Metview version 5.16.0*
    :type vertical_level_type: {"as_in_data", "pressure", "user"}, default: "as_in_data"

    :param lnsp_param: Specifies the ecCodes paramId used to identify the Logarithm of Surface Pressure (LNSP) in the input data.  Enabled when ``vertical_level_type`` is "pressure".
    :type lnsp_param: number, default: 152

    :param use_fixed_surface_pressure: When it is "on" a fixed surface pressure value will be used in the computations and no LNSP fields have to be specified. Enabled when ``vertical_level_type`` is "pressure".  *New in Metview version 5.17.0*
    :type use_fixed_surface_pressure: {"on", "off"}, default: "off"

    :param fixed_surface_pressure: Specify the fixed surface pressure value in hPa when ``use_fixed_surface_pressure`` is "on".  *New in Metview version 5.17.0*
    :type fixed_surface_pressure: number, default: 1013.25

    :param vertical_coordinate_param: Specifies the ecCodes paramId used to identify the vertical coordinate fields in the input data.  Enabled when ``vertical_level_type`` is "user". *New in Metview version 5.16.0*
    :type vertical_coordinate_param: number

    :param vertical_coordinate_extrapolate: Performs an extrapolation for the ``top_level`` and ``bottom_level`` when the output vertical level range does not contain these levels.  The purpose is to avoid blank areas in the plot near the bottom ot top. Only used when ``vertical_level_type`` is "pressure" or "user". *New in Metview version 5.16.0*
    :type vertical_coordinate_extrapolate: {"on", "off"}, default: "off"

    :param vertical_coordinate_extrapolate_mode: Specifies the extrapolation technique. In "constant" mode the values on the nearest input levels are copied onto the target extrapolated levels. In "linear" mode a linear extrapolation is performed using the nearest two input levels. Enabled when ``vertical_coordinate_extrapolate`` is "on". *New in Metview version 5.16.0*
    :type vertical_coordinate_extrapolate_mode: {"constant", "linear"}, default: "constant"

    :param vertical_coordinate_extrapolate_fixed_sign: When ``vertical_coordinate_extrapolate_mode`` is "on" it controls whether the extrapolated values can differ in sign from the values on the nearest input levels. When it is "on" it prevents e.g. wind components to change sign due to extrapolation. *New in Metview version 5.16.0*
    :type vertical_coordinate_extrapolate_fixed_sign: {"on", "off"}, default: "on"

    :param bottom_level: Specifies the lower (closest to the surface) limit of the Hovmoeller data in the units of the vertical coordinates. Only levels in the range defined by ``top_level`` and ``bottom_level`` are included in the output data. An extra level on either side of this range is also added. Enabled when ``vertical_level_type`` is "pressure" or "param".
    :type bottom_level: number, default: 1015.0

    :param top_level: Specifies the upper (furthest from the surface) limit of the Hovmoeller data in the units of the vertical coordinates. Only levels in the range defined by ``top_level`` and ``bottom_level`` are included in the output data. An extra level on either side of this range is also added. Enabled when ``vertical_level_type`` is "pressure" or "param".
    :type top_level: number, default: 0.01

    :rtype: :class:`NetCDF`

.. mv-minigallery:: mhovmoeller_vertical