hydro.core
==========

.. py:module:: hydro.core

.. autoapi-nested-parse::

   Core operations on a CCHDO CF/netCDF file.



Attributes
----------

.. autoapisummary::

   hydro.core.dtype_map
   hydro.core.FLAG_SCHEME


Functions
---------

.. autoapisummary::

   hydro.core.dataarray_factory
   hydro.core.remove_param
   hydro.core.add_param
   hydro.core.add_profile_level
   hydro.core.add_level
   hydro.core.add_profile
   hydro.core.create_new


Module Contents
---------------

.. py:data:: dtype_map

.. py:data:: FLAG_SCHEME
   :type:  dict[str, type[cchdo.hydro.flags.ExchangeFlag]]

.. py:function:: dataarray_factory(param, ctype='data', N_PROF=0, N_LEVELS=0, strlen=0)

.. py:function:: remove_param(ds, param, *, delete_param = False, delete_flag = False, delete_error = False, delete_ancillary=False, require_empty = True)

   Remove a parameter and/or its ancillary variables from a dataset.

   Since this function is rather destructive, by default, it is basically a no-op, you must make a choice when calling to delete the parameter or ancillary variable.

   :param ds: The dataset to remove a param from.
   :param param: A string or ``WHPName`` instance of a parameter, strings are in the form ``"param [unit]"`` or ``"param"`` if unitless, e.g. ``"OXYGEN [UMOL/KG]"`` or ``"EXPOCODE"``
   :param delete_param: If True, delete this parameter and all associated ancillary variables. Defaults to False.
   :param delete_flag: If True, delete this parameters flag, Defaults to False.
   :param delete_error: If True, delete this parameters error variable. Defaults to False.
   :param delete_ancillary: Currently a no-op.
   :param require_empty: If True, require that all the variables that will be deleted contain exclusively fill values, defualts to True

   :returns: A new dataset with the requested variables removed, will return a new dataset even if the results of calling this function are no-op


.. py:function:: add_param(ds, param, *, with_flag = False, with_error = False, with_ancillary=None)

   Add a new parameter, and optionally some ancillary associated variables to a dataset.

   This function is idempotent and will not overwrite any existing data or parameters.
   To add a flag or error parameter to an existing parameter is done by setting the `with_flag` or `with_error` arguments to `True`.

   :param ds: Dataset to add a param to
   :param param: A string or ``WHPName`` instance of a parameter, strings are in the form ``"param [unit]"`` or ``"param"`` if unitless, e.g. ``"OXYGEN [UMOL/KG]"`` or ``"EXPOCODE"``
   :param with_flag: If True, also add a quality flag variable, defaults to False
   :param with_error: If True, also add an error variable if one is defined for this parent parameter, defaults to False
   :param with_ancillary: Currently a no-op, hopefully will be used to add ancillary variable for things like analytical temperature
   :return: A new dataset with the requested variables added, will return a new dataset even if the results of calling this function are no-op


.. py:function:: add_profile_level(ds, idx, levels)

.. py:function:: add_level(ds, n_levels=1)

   Expand the size of N_LEVELS

   This essentially expands the slots avaialble for data and does not add any actual valid levels to a profile.


.. py:function:: add_profile(ds, expocode, station, cast, time, latitude, longitude, profile_type)

   Add one or more profiles to the dataset.

   Arguments maybe be scalar or 1d arrays, all 1d arrays must be of the same size.
   Scalars will be broadcast against any 1d arrays


.. py:function:: create_new()

   Create an empty CF Dataset with the minimum required contents.