.. _stvl_icon:


stvl
=====================================================

.. container::
    
    .. container:: leftside

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

    .. container:: rightside

		Retrieves point data from the STVL database in :class:`Geopoints` or :class:`Geopointset` formats. The output format depends on the retrieval options. The generic rule is that STVL generates one :class:`Geopoints` object per date, time and step. When STVL generates a single :class:`Geopoints` this is returned as is. However, when multiple :class:`Geopoints` objects are generated they are merged into a single :class:`Geopointset` on return. The following examples show how it works.
		
		This code retrieves a **single** date and time: 
		
		    .. code-block:: python
		
		        import metview as mv
		
		        r = mv.stvl(
		            parameter="2t",
		            dates=20200511,
		            times=12
		        )
		        
		        print(f"type={type(r)}")
		        print(f"len={len(r)}")   
		
		generating this output::
		
		        type=<class 'metview.bindings.Geopoints'>
		        len=8474
		
		This code retrieves **multiple** times:
		
		    .. code-block:: python
		
		        import metview as mv
		
		        r = mv.stvl(
		            parameter="2t",
		            dates=20200511,
		            times=[0, 12]
		        )
		        
		        print(f"type={type(r)}")
		        print(f"len={len(r)}")   
		        for i, g in enumerate(r):
		            print(f"len[{i}]={len(g)}")   
		    
		
		and the output looks like this::
		
		    type=<class 'metview.bindings.GeopointSet'>
		    len=2
		    len[0]=7792
		    len[1]=8474
		      
		 
		


		.. warning:: This function is only available for internal ECMWF use.

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


.. py:function:: stvl(**kwargs)
  
    Retrieves point data from the STVL database in :class:`Geopoints` or :class:`Geopointset` formats.
    
    .. warning:: This function is only available for internal ECMWF use.


    :param parameter: Specifies the parameter name as an ecCodes shortName.
    :type parameter: str

    :param period: Observation period in hours (0-24), only valid for certain parameters.
    :type period: str

    :param dates: Observation or forecast start dates. It can be one or more YYYYMMDD values or a MARS-style interval YYYYMMDD/to/YYYYMMDD/by/H (e.g. 20160102/to/20160229/by/3).
    :type dates: list or str or number

    :param times: Observation or forecast start times.
    :type times: list or str or number

    :param steps: The list of forecast steps. It can be one or more steps in hours separated or a MARS- like interval, e.g. 24/to/120/by/12. Only available when ``table`` is "model".
    :type steps: list or str or number

    :param table: Database table to retrieve data from.
    :type table: {"observation", "model"}, default: "observation"

    :param mclass: The MARS class of model data. Only available when ``table`` is "model".
    :type mclass: str, default: "od"

    :param stream: The MARS stream of model data. Only available when ``table`` is "model".
    :type stream: str, default: "oper"

    :param expver: The MARS experiment version of model data. Only available when ``table`` is "model".
    :type expver: str, default: "0001"

    :param mtype: The MARS type of model data. Only available when ``table`` is "model".
    :type mtype: str, default: "fc"

    :param origin: The MARS origin of model data. Only available when ``table`` is "model".
    :type origin: str

    :param anoffset: The MARS analysis offset of model data. Only available when ``table`` is "model".
    :type anoffset: number

    :param columns: Optional list of value columns in the output file. If not set all the columns will be stored.
    :type columns: list

    :param sources: List of original sources of observations.
    :type sources: list

    :rtype: :class:`Geopoints` or :class:`Geopointset`

.. mv-minigallery:: stvl