# esmvalcore.io.intake_esgf

Access data using [intake-esgf](https://intake-esgf.readthedocs.io).

#### NOTE
It is highly recommended that you take a moment to
[configure intake-esgf](https://intake-esgf.readthedocs.io/en/stable/configure) before using it
with ESMValCore. Make sure to set `local_cache` to a path where
it can store downloaded files and if (some) ESGF data is already
available on your system, point `esg_dataroot` to it. If you are
missing certain search results, you may want to choose a different
index node for searching the ESGF.

Run the command `esmvaltool config copy data-intake-esgf.yml` to update
your [configuration](../quickstart/configure.html.md#config-data-sources) to use this module. This will
create a file with the following content in your configuration directory:

```yaml
# Read CMIP and obs4MIPs data from ESGF using intake-esgf.
projects:
  CMIP7:
    data:
      intake-esgf:
        type: esmvalcore.io.intake_esgf.IntakeESGFDataSource
        facets:
          activity: "activity_id"
          branding_suffix: "variable_branding_suffix"
          dataset: "source_id"
          ensemble: "variant_label"
          exp: "experiment_id"
          frequency: "frequency"
          grid: "grid_label"
          institute: "institution_id"
          project: "project"
          region: "region"
          short_name: "variable_id"
  CMIP6:
    data:
      intake-esgf:
        type: esmvalcore.io.intake_esgf.IntakeESGFDataSource
        facets:
          activity: "activity_id"
          dataset: "source_id"
          ensemble: "member_id"
          exp: "experiment_id"
          grid: "grid_label"
          institute: "institution_id"
          mip: "table_id"
          project: "project"
          short_name: "variable_id"
  CMIP6Plus:
    data:
      intake-esgf:
        type: esmvalcore.io.intake_esgf.IntakeESGFDataSource
        facets:
          activity: "activity_id"
          dataset: "source_id"
          ensemble: "member_id"
          exp: "experiment_id"
          grid: "grid_label"
          institute: "institution_id"
          mip: "table_id"
          project: "project"
          short_name: "variable_id"
  CMIP5:
    data:
      intake-esgf:
        type: esmvalcore.io.intake_esgf.IntakeESGFDataSource
        facets:
          dataset: "model"
          ensemble: "ensemble"
          exp: "experiment"
          frequency: "time_frequency"
          institute: "institute"
          mip: "cmor_table"
          product: "product"
          project: "project"
          short_name: "variable"
        values:
          dataset:
            "ACCESS1-0": "ACCESS1.0"
            "ACCESS1-3": "ACCESS1.3"
            "bcc-csm1-1": "BCC-CSM1.1"
            "bcc-csm1-1-m": "BCC-CSM1.1(m)"
            "CESM1-BGC": "CESM1(BGC)"
            "CESM1-CAM5": "CESM1(CAM5)"
            "CESM1-CAM5-1-FV2": "CESM1(CAM5.1,FV2)"
            "CESM1-FASTCHEM": "CESM1(FASTCHEM)"
            "CESM1-WACCM": "CESM1(WACCM)"
            "CSIRO-Mk3-6-0": "CSIRO-Mk3.6.0"
            "fio-esm": "FIO-ESM"
            "GFDL-CM2p1": "GFDL-CM2.1"
            "inmcm4": "INM-CM4"
            "MRI-AGCM3-2H": "MRI-AGCM3.2H"
            "MRI-AGCM3-2S": "MRI-AGCM3.2S"
  CMIP3:
    data:
      intake-esgf:
        type: esmvalcore.io.intake_esgf.IntakeESGFDataSource
        facets:
          dataset: "model"
          ensemble: "ensemble"
          exp: "experiment"
          frequency: "time_frequency"
          project: "project"
          short_name: "variable"
  CORDEX-CMIP6:
    data:
      intake-esgf:
        type: esmvalcore.io.intake_esgf.IntakeESGFDataSource
        facets:
          activity: "activity_id"
          dataset: "source_id"
          domain: "domain_id"
          driver: "driving_source_id"
          ensemble: "driving_variant_label"
          exp: "driving_experiment_id"
          frequency: "frequency"
          institute: "institution_id"
          project: "project"
          rcm_version: "version_realization"
          short_name: "variable_id"
  obs4MIPs:
    data:
      intake-esgf-v2:
        type: esmvalcore.io.intake_esgf.IntakeESGFDataSource
        facets:
          dataset: "source_id"
          frequency: "frequency"
          grid: "grid_label"
          institute: "institution_id"
          project: "project"
          short_name: "variable_id"
      # TODO: Add support for older ODS V1.0 obs4MIPs (CMIP5 style) data to intake-esgf
      # intake-esgf-v1:
      #   type: esmvalcore.io.intake_esgf.IntakeESGFDataSource
      #   facets:
      #     dataset: "source_id"
      #     frequency: "time_frequency"
      #     institute: "institute"
      #     project: "project"
      #     short_name: "variable"
```

**Classes:**

| [`IntakeESGFDataSource`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource)(name, project, ...)   | Data source that can be used to find data using intake-esgf.                                           |
|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| [`IntakeESGFDataset`](#esmvalcore.io.intake_esgf.IntakeESGFDataset)(name, facets, catalog)   | A dataset that can be used to load data found using [intake-esgf](https://intake-esgf.readthedocs.io). |

### *class* esmvalcore.io.intake_esgf.IntakeESGFDataSource(name: str, project: str, priority: int, facets: dict[str, str], values: dict[str, dict[str, str]] = <factory>)

Bases: [`DataSource`](esmvalcore.io.protocol.html.md#esmvalcore.io.protocol.DataSource)

Data source that can be used to find data using intake-esgf.

**Attributes:**

| [`catalog`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource.catalog)    | The intake-esgf catalog used to find data.                   |
|-------------------------------------------------------------|--------------------------------------------------------------|
| [`debug_info`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource.debug_info) | A string containing debug information when no data is found. |
| [`facets`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource.facets)     | Mapping between the ESMValCore and ESGF facet names.         |
| [`name`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource.name)       | A name identifying the data source.                          |
| [`priority`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource.priority)   | The priority of the data source.                             |
| [`project`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource.project)    | The project that the data source provides data for.          |
| [`values`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource.values)     | Mapping between the ESMValCore and ESGF facet values.        |

**Methods:**

| [`find_data`](#esmvalcore.io.intake_esgf.IntakeESGFDataSource.find_data)(\*\*facets)   | Find data.   |
|--------------------------------------------------------------------------|--------------|
* **Parameters:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str))
  * **project** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str))
  * **priority** ([*int*](https://docs.python.org/3/builtins/functions.html#int))
  * **facets** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *]*)
  * **values** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* [*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *]* *]*)

#### catalog *: ESGFCatalog*

The intake-esgf catalog used to find data.

#### debug_info *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= ''*

A string containing debug information when no data is found.

#### facets *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]*

Mapping between the ESMValCore and ESGF facet names.

#### find_data(\*\*facets: FacetValue) → [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[IntakeESGFDataset](#esmvalcore.io.intake_esgf.IntakeESGFDataset)]

Find data.

* **Parameters:**
  **\*\*facets** (*FacetValue*) – Find data matching these facets.
* **Returns:**
  A list of data elements that have been found.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[IntakeESGFDataset](#esmvalcore.io.intake_esgf.IntakeESGFDataset)]

#### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

A name identifying the data source.

#### priority *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The priority of the data source. Lower values have priority.

#### project *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The project that the data source provides data for.

#### values *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]]*

Mapping between the ESMValCore and ESGF facet values.

### *class* esmvalcore.io.intake_esgf.IntakeESGFDataset(name: [str](https://docs.python.org/3/builtins/stdtypes.html#str), facets: Facets, catalog: intake_esgf.ESGFCatalog)

Bases: [`DataElement`](esmvalcore.io.protocol.html.md#esmvalcore.io.protocol.DataElement)

A dataset that can be used to load data found using [intake-esgf](https://intake-esgf.readthedocs.io).

**Attributes:**

| [`attributes`](#esmvalcore.io.intake_esgf.IntakeESGFDataset.attributes)   | Attributes are key-value pairs describing the data.          |
|---------------------------------------------------------------|--------------------------------------------------------------|
| [`catalog`](#esmvalcore.io.intake_esgf.IntakeESGFDataset.catalog)      | The intake-esgf catalog describing this data.                |
| [`facets`](#esmvalcore.io.intake_esgf.IntakeESGFDataset.facets)       | Facets are key-value pairs that were used to find this data. |
| [`name`](#esmvalcore.io.intake_esgf.IntakeESGFDataset.name)         | A unique name identifying the data.                          |

**Methods:**

| [`prepare`](#esmvalcore.io.intake_esgf.IntakeESGFDataset.prepare)()   | Prepare the data for access.   |
|--------------------------------------------------------------|--------------------------------|
| [`to_iris`](#esmvalcore.io.intake_esgf.IntakeESGFDataset.to_iris)()   | Load the data as Iris cubes.   |
* **Parameters:**
  * **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str))
  * **facets** (*Facets*)
  * **catalog** (*intake_esgf.ESGFCatalog*)

#### *property* attributes *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]*

Attributes are key-value pairs describing the data.

#### catalog *: intake_esgf.ESGFCatalog*

The intake-esgf catalog describing this data.

#### facets *: Facets*

Facets are key-value pairs that were used to find this data.

#### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

A unique name identifying the data.

#### prepare() → [None](https://docs.python.org/3/builtins/constants.html#None)

Prepare the data for access.

* **Return type:**
  None

#### to_iris() → [iris.cube.CubeList](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList)

Load the data as Iris cubes.

* **Returns:**
  The loaded data.
* **Return type:**
  [iris.cube.CubeList](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList)