.. _flextra_prepare_icon: flextra_prepare =============================================== .. container:: .. container:: leftside .. image:: /_static/FLEXTRA_PREPARE.png :width: 48px .. container:: rightside Generates the gridded input data and the AVAILABLE file needed to run the :ref:`FLEXTRA ` trajectory model. The input forecast or analysis fields are either automatically retrieved from ECMWF's MARS archive or read from the specified input file. .. tip:: A tutorial on using FLEXTRA from within Metview is available :ref:`here `. **What data is available?** :func:`flextra_prepare` is currently only able to handle data from the operational ECMWF forecasts/analyses 2008, 4 June onwards. From Metview version 5.17.0 onwards when ``flextra_prepare_mode`` is "period" the analysis can also be retrieved from ERA5 (by setting ``flextra_an_mars_class`` to "ea"). **About the FLEXTRA input data** The following is for information only - :func:`flextra_prepare` handles these details internally. FLEXTRA requires input fields on a regular latitude-longitude grid in GRIB format. The input data must contain four three-dimensional fields: the two horizontal wind components, vertical velocity and temperature. Two additional two-dimensional fields are needed as well: topography and surface pressure. The three-dimensional input data has to be available on ECMWF model (i.e. :math:`\eta`) levels defined by a hybrid vertical coordinate system. An important restriction is that all the data fields used within a FLEXTRA run must have the same domain size, resolution, number of levels, etc. All the required fields, with one exception, can be retrieved from ECMWF's MARS archive. The only exception is vertical velocity because FLEXTRA needs the following field for its computations: :math:`\dot \eta \frac{\partial \eta}{\partial p}`. Since only :math:`\dot \eta` is archived in MARS the full product needs to be computed during the data preparation process (:func:`flextra_prepare` does it for you). FLEXTRA requires all the input GRIB files to be in the same folder using the following file naming convention: **EN**\ *yymmddhh*\ . In addition to the GRIBs FLEXTRA needs several parameter files as well. Most of these files are automatically generated by Metview in the background, so users do not need to create them. The only exception is the file called AVAILABLE because it can be optionally provided by the user. .. note:: This function performs the same task as the **Flextra Prepare** icon in Metview’s :ref:`user interface `. It accepts its parameters as keyword arguments, described below. .. py:function:: flextra_prepare(**kwargs) Generates the gridded input data and the AVAILABLE file needed to run the :ref:`FLEXTRA ` trajectory model. :param flextra_prepare_mode: Specifies the data preparation mode. The possible values are: * "forecast": the selected steps of a given forecast can be used for data generation. * "period": a period with a start and end date and constant time-step can be defined. In this case :func:`flextra_prepare` tries to retrieve analysis fields from MARS whenever it is possible (for dates in the past) and uses forecast fields otherwise (for dates in the future). :type flextra_prepare_mode: {"forecast", "period"}, default: "forecast" :param flextra_input_source: Specifies the source of the input GRIB data. If it is set to "mars" the input GRIB data is retrieved from the MARS archive. When ``flextra_prepare_mode`` is forecast ``flextra_input_source`` can also be set to "file". In this case the GRIB file specified in ``flextra_input_file`` will be used as input data. :type flextra_input_source: {"mars", "file"}, default: "mars" :param flextra_input_file: Specifies the full path to the file containing the input GRIB data. Available when ``flextra_prepare_mode`` is "forecast" and ``flextra_input_source`` is "file". :type flextra_input_file: str :param flextra_an_mars_class: The MARS class of the analysis fields. The possible values are "od" (operational analysis) and "ea" (ERA5). The "ea" mode can only be used internally at ECMWF. Enabled when ``flextra_prepare_mode`` is "period". *New in Metview version 5.17.0* :type flextra_an_mars_class: {"od", "ea"}, default: "od" :param flextra_fc_mars_expver: The MARS experiment identifier of the forecast fields. The default value is "1" (operational forecast). :type flextra_fc_mars_expver: str, default: "1" :param flextra_an_mars_expver: The MARS experiment identifier of the analysis fields. The default value is "1" (operational analysis). Enabled when ``flextra_prepare_mode`` is "period". :type flextra_an_mars_expver: str, default: "1" :param flextra_date: Specifies the run date of the forecast. Available when ``flextra_prepare_mode`` is "forecast". :type flextra_date: str, default: "-1" :param flextra_time: Specifies the run time of the forecast . Available when ``flextra_prepare_mode`` is "forecast". :type flextra_time: str, default: "0" :param flextra_step: Specifies the forecast steps in hours. Available when ``flextra_prepare_mode`` is "forecast". :type flextra_step: str or list[str] :param flextra_period_start_date: Specifies the start date of the period. Available when ``flextra_prepare_mode`` is "period". :type flextra_period_start_date: str, default: "-1" :param flextra_period_start_time: Specifies the start time of the period. Available when ``flextra_prepare_mode`` is "period". :type flextra_period_start_time: str, default: "0" :param flextra_period_end_date: Specifies the end date of the period. Available when ``flextra_prepare_mode`` is "period". :type flextra_period_end_date: str, default: "-1" :param flextra_period_end_time: Specifies the end time of the period. Available when ``flextra_prepare_mode`` is Period. :type flextra_period_end_time: str, default: "0" :param flextra_period_step: Specifies the time step of the period in hours. Available when ``flextra_prepare_mode`` is "period". :type flextra_period_step: {"3", "6"}, default: "3" :param flextra_grid_interpolation: Specifies if the input GRIB fields need to be interpolated onto a target grid specified by ``flextra_area`` and ``flextra_grid``. Available when ``flextra_input_source`` is "file". :type flextra_grid_interpolation: {"on", "off"}, default: "on" :param flextra_area: Specifies the area of the output ``flextra_grid`` in south/west/north/east format. .. note:: To make global domains work with FLEXTRA the western border must be set to one grid cell east of 180. E.g. if the east-west grid resolution is 1 degree ``flextra_area`` should be set to [-90, -179, 90, 180] etc. :type flextra_area: list[number], default: [-90, -179, 90, 180] :param flextra_grid: Specifies the resolution of the output grid in [dx/dy] format, where dx is the grid increment in east-west direction, while dy is the grid increment in north-south direction (both in units of degrees). :type flextra_grid: list[number], default: [1, 1] :param flextra_top_level: Only data on and below this model level will be used to generate the FLEXTRA input fields. This level can be specified either as a model level or as a pressure value. In the latter case :func:`flextra_prepare` will use the data retrieved for the first date to determine the topmost model level. The default value of this parameter is 1, which means that all the model levels will be used if ``flextra_top_level_units`` is set to "ml". :type flextra_top_level: number, default: 1 :param flextra_top_level_units: Specifies the units of the value of ``flextra_top_level``. :type flextra_top_level_units: {"ml", "hpa"}, default: "ml" :param flextra_reuse_input: If this parameter is set to "on" :func:`flextra_prepare` checks the existence of the data files to be generated and if they are already in place no new data is retrieved and processed. If it is "off" all the fields are always retrieved and processed and the existing data files are overwritten. The same happens to the AVAILABLE file. The existence of a FLEXTRA input GRIB file is checked by using the file name and a set of GRIB API keys from the first message in the file. These keys are as follows: date, time, stepRange, gridType, iDirectionIncrement, jDirectionIncrement, latitudeOfFirstGridPoint, latitudeOfLastGridPoint, longitudeOfFirstGridPoint, longitudeOfLastGridPoint. :type flextra_reuse_input: {"on", "off"}, default: "on" :param flextra_output_path: Specifies the output directory (can be a relative or absolute path) where the GRIB files and the AVAILABLE file will be generated. If this directory does not exist Metview will create it. The output GRIB files have the following naming convention: ENyymmddhh :type flextra_output_path: str :rtype: :class:`Request` .. mv-minigallery:: flextra_prepare