Skip to content

chimere

Chimere Reader

ChimereReader

Bases: GriddedReader

Reader for Chimere model output files.

Source code in monetio/readers/chimere.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@register_reader("chimere")
class ChimereReader(GriddedReader):
    """
    Reader for Chimere model output files.
    """

    def open_dataset(
        self,
        files: str | list[str],
        var_list: list[str] | None = None,
        surf_only: bool = False,
        use_virtualizarr: bool = False,
        virtualizarr_file: str | None = None,
        virtualizarr_backend: str = "kerchunk",
        icechunk_repo: str | None = None,
        use_dask: bool = False,
        **kwargs: Any,
    ) -> xr.Dataset:
        """
        Reads Chimere netCDF files.

        Parameters
        ----------
        files : str or list of str
            File path, list of paths, or glob pattern.
        var_list : list of str, optional
            List of variable names meant to be kept for the analysis, by default None.
        surf_only : bool, optional
            Whether to only keep surface data (layer 0), by default False.
        use_virtualizarr : bool, optional
            Whether to use VirtualiZarr to create a virtual Zarr dataset, by default False.
        virtualizarr_file : str or None, optional
            Path to save/load the VirtualiZarr reference JSON file, by default None.
        virtualizarr_backend : str, optional
            Backend for VirtualiZarr references ("kerchunk" or "icechunk"), by default "kerchunk".
        icechunk_repo : str or None, optional
            Path to the Icechunk repository, by default None.
        use_dask : bool, optional
            Whether to use Dask for lazy loading, by default False.
        **kwargs : Any
            Additional arguments passed to the driver.

        Returns
        -------
        xr.Dataset
            The processed Chimere dataset.

        Examples
        --------
        >>> reader = ChimereReader()
        >>> ds = reader.open_dataset("chimere_output.nc")
        >>> ds_lazy = reader.open_dataset("chimere_output.nc", use_dask=True)
        """
        if "preprocess" not in kwargs:
            kwargs["preprocess"] = partial(
                chimere_preprocess,
                var_list=var_list,
                surf_only=surf_only,
            )

        if "combine" not in kwargs:
            kwargs["combine"] = "nested"
        if "concat_dim" not in kwargs:
            kwargs["concat_dim"] = "time"

        ds = self.driver.open(
            files,
            use_virtualizarr=use_virtualizarr,
            virtualizarr_file=virtualizarr_file,
            virtualizarr_backend=virtualizarr_backend,
            icechunk_repo=icechunk_repo,
            use_dask=use_dask,
            **kwargs,
        )

        ds = self.harmonize(ds)

        # Update history
        ds = update_history(ds, "Read Chimere data.")

        return ds

open_dataset(files, var_list=None, surf_only=False, use_virtualizarr=False, virtualizarr_file=None, virtualizarr_backend='kerchunk', icechunk_repo=None, use_dask=False, **kwargs)

Reads Chimere netCDF files.

Parameters:

Name Type Description Default
files str or list of str

File path, list of paths, or glob pattern.

 required
var_list list of str

List of variable names meant to be kept for the analysis, by default None.

 None
surf_only bool

Whether to only keep surface data (layer 0), by default False.

 False
use_virtualizarr bool

Whether to use VirtualiZarr to create a virtual Zarr dataset, by default False.

 False
virtualizarr_file str or None

Path to save/load the VirtualiZarr reference JSON file, by default None.

 None
virtualizarr_backend str

Backend for VirtualiZarr references ("kerchunk" or "icechunk"), by default "kerchunk".

 'kerchunk'
icechunk_repo str or None

Path to the Icechunk repository, by default None.

 None
use_dask bool

Whether to use Dask for lazy loading, by default False.

 False
**kwargs Any

Additional arguments passed to the driver.

 {}

Returns:

Type Description
Dataset

The processed Chimere dataset.

Examples:

>>> reader = ChimereReader()
>>> ds = reader.open_dataset("chimere_output.nc")
>>> ds_lazy = reader.open_dataset("chimere_output.nc", use_dask=True)
Source code in monetio/readers/chimere.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def open_dataset(
    self,
    files: str | list[str],
    var_list: list[str] | None = None,
    surf_only: bool = False,
    use_virtualizarr: bool = False,
    virtualizarr_file: str | None = None,
    virtualizarr_backend: str = "kerchunk",
    icechunk_repo: str | None = None,
    use_dask: bool = False,
    **kwargs: Any,
) -> xr.Dataset:
    """
    Reads Chimere netCDF files.

    Parameters
    ----------
    files : str or list of str
        File path, list of paths, or glob pattern.
    var_list : list of str, optional
        List of variable names meant to be kept for the analysis, by default None.
    surf_only : bool, optional
        Whether to only keep surface data (layer 0), by default False.
    use_virtualizarr : bool, optional
        Whether to use VirtualiZarr to create a virtual Zarr dataset, by default False.
    virtualizarr_file : str or None, optional
        Path to save/load the VirtualiZarr reference JSON file, by default None.
    virtualizarr_backend : str, optional
        Backend for VirtualiZarr references ("kerchunk" or "icechunk"), by default "kerchunk".
    icechunk_repo : str or None, optional
        Path to the Icechunk repository, by default None.
    use_dask : bool, optional
        Whether to use Dask for lazy loading, by default False.
    **kwargs : Any
        Additional arguments passed to the driver.

    Returns
    -------
    xr.Dataset
        The processed Chimere dataset.

    Examples
    --------
    >>> reader = ChimereReader()
    >>> ds = reader.open_dataset("chimere_output.nc")
    >>> ds_lazy = reader.open_dataset("chimere_output.nc", use_dask=True)
    """
    if "preprocess" not in kwargs:
        kwargs["preprocess"] = partial(
            chimere_preprocess,
            var_list=var_list,
            surf_only=surf_only,
        )

    if "combine" not in kwargs:
        kwargs["combine"] = "nested"
    if "concat_dim" not in kwargs:
        kwargs["concat_dim"] = "time"

    ds = self.driver.open(
        files,
        use_virtualizarr=use_virtualizarr,
        virtualizarr_file=virtualizarr_file,
        virtualizarr_backend=virtualizarr_backend,
        icechunk_repo=icechunk_repo,
        use_dask=use_dask,
        **kwargs,
    )

    ds = self.harmonize(ds)

    # Update history
    ds = update_history(ds, "Read Chimere data.")

    return ds

chimere_preprocess(ds, *, var_list=None, surf_only=False)

Preprocess function for a single Chimere file.

Parameters:

Name Type Description Default
ds Dataset

Input Chimere dataset.

 required
var_list list of str

List of variables to keep, by default None.

 None
surf_only bool

Whether to keep only surface data, by default False.

 False

Returns:

Type Description
Dataset

Processed dataset.

Examples:

>>> import xarray as xr
>>> ds = xr.Dataset({"O3": (("time_counter", "y", "x"), [[1, 2]])})
>>> ds_clean = chimere_preprocess(ds, var_list=["O3"])
Source code in monetio/readers/chimere.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def chimere_preprocess(
    ds: xr.Dataset, *, var_list: list[str] | None = None, surf_only: bool = False
) -> xr.Dataset:
    """
    Preprocess function for a single Chimere file.

    Parameters
    ----------
    ds : xr.Dataset
        Input Chimere dataset.
    var_list : list of str, optional
        List of variables to keep, by default None.
    surf_only : bool, optional
        Whether to keep only surface data, by default False.

    Returns
    -------
    xr.Dataset
        Processed dataset.

    Examples
    --------
    >>> import xarray as xr
    >>> ds = xr.Dataset({"O3": (("time_counter", "y", "x"), [[1, 2]])})
    >>> ds_clean = chimere_preprocess(ds, var_list=["O3"])
    """
    if var_list is not None:
        drop_vars = set(ds.data_vars) - set(var_list)
        ds = ds.drop_vars(drop_vars, errors="ignore")

    rename_dict = {
        "nav_lat": "latitude",
        "nav_lon": "longitude",
        "time_counter": "time",
        "bottom_top": "z",
    }
    # Only rename if they exist in variables or dims
    rename_dict = {k: v for k, v in rename_dict.items() if k in ds.variables or k in ds.dims}

    if rename_dict:
        ds = ds.rename(rename_dict)

    if surf_only and "z" in ds.dims:
        ds = ds.isel(z=[0])

    # Ensure lat/lon have standard attributes if they exist
    if "latitude" in ds.variables:
        ds["latitude"].attrs.update({"units": "degrees_north", "standard_name": "latitude"})
    if "longitude" in ds.variables:
        ds["longitude"].attrs.update({"units": "degrees_east", "standard_name": "longitude"})

    # Scientific Hygiene handles coordinate assignment (latitude, longitude, time)
    # and attribute cleaning while preserving history.
    ds = _scientific_hygiene(ds)

    # Transpose to standard order if dims exist
    dims = [d for d in ["time", "z", "y", "x"] if d in ds.dims]
    if dims:
        ds = ds.transpose(*dims)

    # Consolidate history update
    ds = update_history(ds, "Preprocessed Chimere data (renaming, subsetting, and hygiene).")

    return ds