access_nri_intake.aliases
=========================

.. py:module:: access_nri_intake.aliases

.. autoapi-nested-parse::

   Aliasing support for intake catalogs to provide user-friendly field names and value mappings.

   RATIONALE
   ---------
   This module provides aliasing functionality to make ACCESS-NRI data more discoverable by
   researchers familiar with CMIP vocabularies and conventions. The primary goal is to enable
   users who typically work with CMIP data to find raw ACCESS model outputs using familiar
   variable names, model names, and other CMIP-standard terminology.

   For example:
   - CMIP users searching for "ci" (convection time fraction) will find the corresponding
     raw ACCESS model variables (e.g., "fld_s05i269" in ACCESS-ESM1.6)
   - Users searching for "tas" (near-surface air temperature) will find the corresponding
     raw ACCESS model temperature fields
   - Users familiar with CMIP standard names can also search using intuitive aliases like
     "temp", "temperature", or "air_temperature" - all of which map to find "tas" variables
   - Users familiar with CMIP model names can use shortcuts like "ACCESS-ESM1" to find
     "ACCESS-ESM1-5" model data
   - Frequency specifications can use human-readable terms like "daily" instead of "1day"

   This bridging functionality allows CMIP users to leverage their existing vocabulary knowledge
   to discover raw ACCESS model data, while maintaining full backward compatibility with existing workflows.

   The aliasing works in both directions - field name aliasing (e.g., "variable" → "variable_id")
   and value aliasing (e.g., "temp" → "tas") - allowing for flexible and intuitive data discovery.
   The system also includes CMIP-to-ACCESS variable mappings that allow users to search for CMIP
   variable names and find the corresponding native ACCESS model variable names.

   Bottom value returns (ie. `return obj`) if no conditions are met have been flagged with pragma: no cover
   to avoid creating unhelpful tests.

   ..
       !! processed by numpydoc !!


Attributes
----------

.. autoapisummary::

   access_nri_intake.aliases.T
   access_nri_intake.aliases.DATAFRAME_FIELD_ALIASES
   access_nri_intake.aliases.ESM_FIELD_ALIASES
   access_nri_intake.aliases.VALUE_ALIASES


Classes
-------

.. autoapisummary::

   access_nri_intake.aliases.AliasedESMCatalog
   access_nri_intake.aliases.AliasedDataframeCatalog


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

.. py:data:: T

.. py:class:: AliasedESMCatalog(cat, field_aliases = None, value_aliases = None, show_warnings = True)

   Bases: :py:obj:`wrapt.ObjectProxy`


   Thin wrapper around an intake-esm ESMDataStore that:
     - maps public field names → canonical fields (FIELD_ALIASES)
     - maps value aliases → canonical values per field (VALUE_ALIASES)

   :param cat: The underlying ESM datastore to wrap
   :type cat: ESMDataStore
   :param field_aliases: Mapping of user-facing field names to canonical field names
   :type field_aliases: dict, optional
   :param value_aliases: Mapping of field names to value alias dictionaries
   :type value_aliases: dict, optional
   :param show_warnings: Whether to show warnings when aliasing occurs
   :type show_warnings: bool, default True

   Create an object proxy around the given object.
















   ..
       !! processed by numpydoc !!


   .. py:attribute:: field_aliases


   .. py:attribute:: value_aliases


   .. py:attribute:: show_warnings
      :value: True



   .. py:method:: search(**kwargs)

      
      Search the catalog with aliased field names and values
















      ..
          !! processed by numpydoc !!


   .. py:method:: unwrap()

      
      Get the underlying dataframe catalog without aliasing
















      ..
          !! processed by numpydoc !!


.. py:class:: AliasedDataframeCatalog(cat, field_aliases = None, value_aliases = None, show_warnings = True)

   Bases: :py:obj:`wrapt.ObjectProxy`


   Wrapper around an intake dataframe catalog that provides alias support
   for catalog entries that are ESM datastores.

   :param cat: The underlying dataframe catalog to wrap
   :type cat: DataframeCatalog
   :param field_aliases: Mapping of user-facing field names to canonical field names (for dataframe level)
   :type field_aliases: dict, optional
   :param value_aliases: Mapping of field names to value alias dictionaries
   :type value_aliases: dict, optional
   :param show_warnings: Whether to show warnings when aliasing occurs in ESM datastores
   :type show_warnings: bool, default True

   Create an object proxy around the given object.
















   ..
       !! processed by numpydoc !!


   .. py:attribute:: field_aliases


   .. py:attribute:: value_aliases


   .. py:attribute:: show_warnings
      :value: True



   .. py:method:: search(**kwargs)

      
      Search the dataframe catalog - apply aliases and wrap results
















      ..
          !! processed by numpydoc !!


   .. py:method:: to_source(**kwargs)

      
      Get ESM datastore from catalog search result - wrap with aliasing
















      ..
          !! processed by numpydoc !!


   .. py:method:: to_source_dict(**kwargs)

      
      Get dict of ESM datastores from catalog search result - wrap each with aliasing
















      ..
          !! processed by numpydoc !!


   .. py:method:: unwrap()

      
      Get the underlying dataframe catalog without aliasing
















      ..
          !! processed by numpydoc !!


.. py:data:: DATAFRAME_FIELD_ALIASES
   :type:  dict[str, str]

.. py:data:: ESM_FIELD_ALIASES
   :type:  dict[str, tuple[str]]

.. py:data:: VALUE_ALIASES