.. _netcdf_visualiser_icon:


netcdf_visualiser
===============================================

.. container::
    
    .. container:: leftside

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

    .. container:: rightside

		Defines the visualisation of :class:`NetCDF` data allowing to specify which variables in the file should be used, and how to interpret them. The generated object can directly be used in :func:`plot`.


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


.. py:function:: netcdf_visualiser(**kwargs)
  
    Defines the visualisation of :class:`NetCDF` data.


    :param netcdf_plot_type: Specifies the type of plot to be generated. The available modes are as follows:
		
		* "geo_points"
		* "geo_vectors"
		* "geo_matrix"
		* "geo_matrix_vectors"
		* "xy_points"
		* "xy_vectors"
		* "xy_matrix"
		* "xy_matrix_vectors"
    :type netcdf_plot_type: str, default: "geo_points"

    :param netcdf_filename: Specifies the path to the NetCDF file to be used. Alternatively, use the ``netcdf_data`` field, which overrides ``netcdf_filename``.
    :type netcdf_filename: str, default: "off"

    :param netcdf_data: Specifies the input data as a :class:`NetCDF` object.
    :type netcdf_data: :class:`NetCDF`

    :param netcdf_latitude_variable: Specifies which variable to use for the latitude co-ordinates. Only available when ``netcdf_plot_type`` is 'geo_*'.'
    :type netcdf_latitude_variable: str

    :param netcdf_longitude_variable: Specifies which variable to use for the longitude co-ordinates. Only available when ``netcdf_plot_type`` is 'geo_*'.
    :type netcdf_longitude_variable: str

    :param netcdf_x_variable: Specifies which variable to use for the x co-ordinates. Only available when ``netcdf_plot_type`` is 'xy_*'.
    :type netcdf_x_variable: str

    :param netcdf_y_variable: Specifies which variable to use for the y co-ordinates. Only available when ``netcdf_plot_type`` is 'xy_*'.
    :type netcdf_y_variable: str

    :param netcdf_x2_variable: 
    :type netcdf_x2_variable: str

    :param netcdf_y2_variable: 
    :type netcdf_y2_variable: str

    :param netcdf_value_variable: Specifies which variable supplies the values.
    :type netcdf_value_variable: str

    :param netcdf_x_component_variable: When ``netcdf_plot_type`` is '*_vectors', this parameter specifies which variable defines the vector component in X or longitude direction (e.g. U-component of wind).
    :type netcdf_x_component_variable: str

    :param netcdf_y_component_variable: When ``netcdf_plot_type`` is '*_vectors', this parameter specifies which variable defines the vector component in Y or latitude direction (e.g. V-component of wind).
    :type netcdf_y_component_variable: str

    :param netcdf_dimension_setting_method: Method used to specify how to interpret the extraction of a subset, the range can by specified by value or by index.
    :type netcdf_dimension_setting_method: {"index", "value"}, default: "value"

    :param netcdf_dimension_setting: Extracts only of a subset of the data. Each dimension is specified as a str in "dim_name:start[:end]" format where the "end" is optional. The value for "start" and "end" have to be specified according to the settings in ``netcdf_dimension_setting_method``. Some examples: 
		
		
		In this example the subset is specified by the dimension called "level" and the subset is extracted for all "level" values between 100 and 500:
		
		.. code-block:: python
		
		    netcdf_dimension_setting_method="value"
		    netcdf_dimension_setting=["level:100:500"]
		
		In this example multiple dimensions are used:
		
		.. code-block:: python
		
		    netcdf_dimension_setting_method="value"
		    netcdf_dimension_setting=["level:100:500", "number:1:2"]
		
		In this example the subset is specified by the dimension called "time" and the subset is restricted to index=2:
		
		.. code-block:: python
		
		    netcdf_dimension_setting_method="index"
		    netcdf_dimension_setting=["time:2"]
		    
    :type netcdf_dimension_setting: list[str]

    :param netcdf_matrix_primary_index: 
    :type netcdf_matrix_primary_index: {"latitude", "longitude"}, default: "longitude"

    :param netcdf_position_type: Specifies how to interpret the data.
    :type netcdf_position_type: {"array", "matrix"}, default: "array"

    :param netcdf_missing_attribute: Specifies the NetCDF attribute that defines the missing value in the data.
    :type netcdf_missing_attribute: str, default: "_fillvalue"

    :rtype: :class:`Request`

.. mv-minigallery:: netcdf_visualiser