arctichoke.path.model_paths
===========================

.. py:module:: arctichoke.path.model_paths


Functions
---------

.. autoapisummary::

   arctichoke.path.model_paths.list_available_models
   arctichoke.path.model_paths.get_model_path


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

.. py:function:: list_available_models(data_dir: str = '/arctichoke_data/bergybits/data', project: str = 'CMIP6', activity_id: str = 'HighResMIP', institution_id: (str, [str]) = None)

   List the names of the models available alphabetically.

   Search the data directory that has been populated by `esgpull` and return a list of all the available models, or `source_id`'s.
   This assumes the `esgpull` convention of subdirectories: `data/project/activity_id/institution_id/source_id`.

   :param data_dir: The absolute file path to the data directory.
                    The `esgpull` convention means this should end in `/data`.
                    Default is `/arctichoke_data/bergybits/data`.
   :type data_dir: `str`, optional
   :param project: The name of the project in which to search for available models.
                   Default is `CMIP6`.
   :type project: `str`, optional
   :param activity_id: The name of the activity ID in which to search for available models.
                       Default is `HighResMIP`.
   :type activity_id: `str`, optional
   :param institution_id: The name(s) of the institution ID(s) in which to search for available models.
                          If `None` is given, all available institutions are included.
                          Default is `None`.
   :type institution_id: `str`, list of `str`, or `None`, optional

   :returns: **model_names** -- A list, sorted alphabetically, of the names of the available models.
   :rtype: List of `str`

   .. rubric:: Examples

   >>> from arctichoke.path.find_data import list_available_models
   >>> list_available_models()
   ['AWI/AWI-CM-1-1-HR', 'AWI/AWI-CM-1-1-LR', 'BCC/BCC-CSM2-HR', 'EC-Earth-Consortium/EC-Earth3P', 'EC-Earth-Consortium/EC-Earth3P-HR', 'MOHC/HadGEM3-GC31-HH', 'MOHC/HadGEM3-GC31-HM', 'MOHC/HadGEM3-GC31-LL', 'MOHC/HadGEM3-GC31-MM', 'NCAR/CESM1-CAM5-SE-HR', 'NCAR/CESM1-CAM5-SE-LR', 'NERC/HadGEM3-GC31-HH', 'NERC/HadGEM3-GC31-HM']
   >>> list_available_models(institution_id = 'EC-Earth-Consortium')
   ['EC-Earth-Consortium/EC-Earth3P', 'EC-Earth-Consortium/EC-Earth3P-HR']
   >>> list_available_models(institution_id = 'MOHC')
   ['MOHC/HadGEM3-GC31-HH', 'MOHC/HadGEM3-GC31-HM', 'MOHC/HadGEM3-GC31-LL', 'MOHC/HadGEM3-GC31-MM']
   >>> list_available_models(institution_id = ['MOHC', 'NERC'])
   ['MOHC/HadGEM3-GC31-HH', 'MOHC/HadGEM3-GC31-HM', 'MOHC/HadGEM3-GC31-LL', 'MOHC/HadGEM3-GC31-MM', 'NERC/HadGEM3-GC31-HH', 'NERC/HadGEM3-GC31-HM']


.. py:function:: get_model_path(source_id: str, data_dir: str = '/arctichoke_data/bergybits/data', project: str = 'CMIP6', activity_id: str = 'HighResMIP')

   Find the file path for the specified model.

   Search the data directory that has been populated by `esgpull` for a model's `source_id` and return the file path.
   This assumes the `esgpull` convention of subdirectories: `data/project/activity_id/institution_id/source_id`.

   :param source_id: The name of the source ID (model) for which to find the file path.
   :type source_id: `str`
   :param data_dir: The absolute file path to the data directory.
                    The `esgpull` convention means this should end in `/data`.
                    Default is `/arctichoke_data/bergybits/data`.
   :type data_dir: `str`, optional
   :param project: The name of the project in which to search for available models.
                   Default is `CMIP6`.
   :type project: `str`, optional
   :param activity_id: The name of the activity ID in which to search for available models.
                       Default is `HighResMIP`.
   :type activity_id: `str`, optional

   :returns: **model_filepaths** -- A list of the file path(s) for the specified model.
   :rtype: List of `str`

   .. rubric:: Examples

   >>> from arctichoke.path.find_data import get_model_path
   >>> get_model_path(source_id='AWI-CM-1-1-HR')
   ['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/AWI/AWI-CM-1-1-HR']
   >>> get_model_path('HadGEM3-GC31-HM')
   ['/arctichoke_data/bergybits/data/CMIP6/HighResMIP/MOHC/HadGEM3-GC31-HM', '/arctichoke_data/bergybits/data/CMIP6/HighResMIP/NERC/HadGEM3-GC31-HM']