ComparerCollection

The ComparerCollection is one of the main objects of the modelskill package. It is a collection of Comparer objects and created either by the match() method, by passing a list of Comparers to the ComparerCollection constructor, or by reading a config file using the from_config() function.

Main functionality:

• selecting/filtering data
  • __get_item__() - get a single Comparer, e.g., cc[0] or cc['obs1']
  • sel()
  • query()
• skill assessment
  • skill()
  • mean_skill()
  • gridded_skill() (for track observations)
• plotting
  • plot.scatter()
  • plot.kde()
  • plot.hist()
• load/save/export data
  • load()
  • save()

modelskill.ComparerCollection

Bases: Mapping, Scoreable

Collection of comparers, constructed by calling the modelskill.match method or by initializing with a list of comparers.

NOTE: In case of multiple model results with different time coverage, only the overlapping time period will be used! (intersection)

Examples:

>>> import modelskill as ms
>>> mr = ms.DfsuModelResult("Oresund2D.dfsu", item=0)
>>> o1 = ms.PointObservation("klagshamn.dfs0", item=0, x=366844, y=6154291, name="Klagshamn")
>>> o2 = ms.PointObservation("drogden.dfs0", item=0, x=355568.0, y=6156863.0)
>>> cmp1 = ms.match(o1, mr)  # Comparer
>>> cmp2 = ms.match(o2, mr)  # Comparer
>>> ccA = ms.ComparerCollection([cmp1, cmp2])
>>> ccB = ms.match(obs=[o1, o2], mod=mr)
>>> sk = ccB.skill()
>>> ccB["Klagshamn"].plot.timeseries()

Source code in modelskill/comparison/_collection.py

class ComparerCollection(Mapping, Scoreable):
    """
    Collection of comparers, constructed by calling the `modelskill.match`
    method or by initializing with a list of comparers.

    NOTE: In case of multiple model results with different time coverage,
    only the _overlapping_ time period will be used! (intersection)

    Examples
    --------
    >>> import modelskill as ms
    >>> mr = ms.DfsuModelResult("Oresund2D.dfsu", item=0)
    >>> o1 = ms.PointObservation("klagshamn.dfs0", item=0, x=366844, y=6154291, name="Klagshamn")
    >>> o2 = ms.PointObservation("drogden.dfs0", item=0, x=355568.0, y=6156863.0)
    >>> cmp1 = ms.match(o1, mr)  # Comparer
    >>> cmp2 = ms.match(o2, mr)  # Comparer
    >>> ccA = ms.ComparerCollection([cmp1, cmp2])
    >>> ccB = ms.match(obs=[o1, o2], mod=mr)
    >>> sk = ccB.skill()
    >>> ccB["Klagshamn"].plot.timeseries()
    """

    plotter = ComparerCollectionPlotter

    def __init__(self, comparers: Iterable[Comparer]) -> None:
        self._comparers: Dict[str, Comparer] = {}

        for cmp in comparers:
            if cmp.name in self._comparers:
                # comparer with this name already exists!
                # maybe the user is trying to add a new model
                # or a new time period
                self._comparers[cmp.name] += cmp
            else:
                self._comparers[cmp.name] = cmp

        self.plot = ComparerCollection.plotter(self)
        """Plot using the ComparerCollectionPlotter

        Examples
        --------
        >>> cc.plot.scatter()
        >>> cc.plot.kde()
        >>> cc.plot.taylor()
        >>> cc.plot.hist()
        """

    @property
    def _name(self) -> str:
        return "Observations"

    @property
    def _unit_text(self) -> str:
        # Picking the first one is arbitrary, but it should be the same for all
        # we could check that they are all the same, but let's assume that they are
        # for cmp in self:
        #     if cmp._unit_text != text:
        #         warnings.warn(f"Unit text is inconsistent: {text} vs {cmp._unit_text}")
        return self[0]._unit_text

    @property
    def n_comparers(self) -> int:
        warnings.warn(
            "cc.n_comparers is deprecated, use len(cc) instead",
            FutureWarning,
        )
        return len(self)

    @property
    def n_points(self) -> int:
        """number of compared points"""
        return sum([c.n_points for c in self._comparers.values()])

    @property
    def start(self) -> pd.Timestamp:
        warnings.warn(
            "start is deprecated, use start_time instead",
            FutureWarning,
        )
        return self.start_time

    @property
    def start_time(self) -> pd.Timestamp:
        """start timestamp of compared data"""
        starts = [pd.Timestamp.max]
        for cmp in self._comparers.values():
            starts.append(cmp.time[0])
        return min(starts)

    @property
    def end(self) -> pd.Timestamp:
        warnings.warn(
            "end is deprecated, use end_time instead",
            FutureWarning,
        )
        return self.end_time

    @property
    def end_time(self) -> pd.Timestamp:
        """end timestamp of compared data"""
        ends = [pd.Timestamp.min]
        for cmp in self._comparers.values():
            ends.append(cmp.time[-1])
        return max(ends)

    @property
    def obs_names(self) -> List[str]:
        """List of observation names"""
        return [c.name for c in self._comparers.values()]

    @property
    def n_observations(self) -> int:
        """Number of observations (same as len(cc))"""
        return len(self)

    @property
    def mod_names(self) -> List[str]:
        """List of unique model names"""
        all_names = [n for cmp in self for n in cmp.mod_names]
        # preserve order (instead of using set)
        return list(dict.fromkeys(all_names))

    @property
    def n_models(self) -> int:
        """Number of unique models"""
        return len(self.mod_names)

    @property
    def aux_names(self) -> List[str]:
        """List of unique auxiliary names"""
        all_names = [n for cmp in self for n in cmp.aux_names]
        # preserve order (instead of using set)
        return list(dict.fromkeys(all_names))

    @property
    def quantity_names(self) -> List[str]:
        """List of unique quantity names"""
        all_names = [cmp.quantity.name for cmp in self]
        # preserve order (instead of using set)
        return list(dict.fromkeys(all_names))

    @property
    def n_quantities(self) -> int:
        """Number of unique quantities"""
        return len(self.quantity_names)

    def __repr__(self) -> str:
        out = []
        out.append("<ComparerCollection>")
        out.append("Comparers:")
        for index, (key, value) in enumerate(self._comparers.items()):
            out.append(f"{index}: {key} - {value.quantity}")
        return str.join("\n", out)

    def rename(self, mapping: Dict[str, str]) -> "ComparerCollection":
        """Rename observation, model or auxiliary data variables

        Parameters
        ----------
        mapping : dict
            mapping of old names to new names

        Returns
        -------
        ComparerCollection

        Examples
        --------
        >>> cc = ms.match([o1, o2], [mr1, mr2])
        >>> cc.mod_names
        ['mr1', 'mr2']
        >>> cc2 = cc.rename({'mr1': 'model1'})
        >>> cc2.mod_names
        ['model1', 'mr2']
        """
        for k in mapping.keys():
            allowed_keys = self.obs_names + self.mod_names + self.aux_names
            if k not in allowed_keys:
                raise KeyError(f"Unknown key: {k}; must be one of {allowed_keys}")

        cmps = []
        for cmp in self._comparers.values():
            cmps.append(cmp.rename(mapping, errors="ignore"))
        return ComparerCollection(cmps)

    @overload
    def __getitem__(self, x: slice | Iterable[Hashable]) -> ComparerCollection: ...

    @overload
    def __getitem__(self, x: int | Hashable) -> Comparer: ...

    def __getitem__(
        self, x: int | Hashable | slice | Iterable[Hashable]
    ) -> Comparer | ComparerCollection:
        if isinstance(x, str):
            return self._comparers[x]

        if isinstance(x, slice):
            idxs = list(range(*x.indices(len(self))))
            return ComparerCollection([self[i] for i in idxs])

        if isinstance(x, int):
            name = _get_name(x, self.obs_names)
            return self._comparers[name]

        if isinstance(x, Iterable):
            cmps = [self[i] for i in x]
            return ComparerCollection(cmps)

        raise TypeError(f"Invalid type for __getitem__: {type(x)}")

    def __len__(self) -> int:
        return len(self._comparers)

    def __iter__(self) -> Iterator[Comparer]:
        return iter(self._comparers.values())

    def copy(self) -> "ComparerCollection":
        return deepcopy(self)

    def __add__(
        self, other: Union["Comparer", "ComparerCollection"]
    ) -> "ComparerCollection":
        if not isinstance(other, (Comparer, ComparerCollection)):
            raise TypeError(f"Cannot add {type(other)} to {type(self)}")

        if isinstance(other, Comparer):
            return ComparerCollection([*self, other])
        elif isinstance(other, ComparerCollection):
            return ComparerCollection([*self, *other])

    def sel(
        self,
        model: Optional[IdxOrNameTypes] = None,
        observation: Optional[IdxOrNameTypes] = None,
        quantity: Optional[IdxOrNameTypes] = None,
        start: Optional[TimeTypes] = None,
        end: Optional[TimeTypes] = None,
        time: Optional[TimeTypes] = None,
        area: Optional[List[float]] = None,
        variable: Optional[IdxOrNameTypes] = None,  # obsolete
        **kwargs: Any,
    ) -> "ComparerCollection":
        """Select data based on model, time and/or area.

        Parameters
        ----------
        model : str or int or list of str or list of int, optional
            Model name or index. If None, all models are selected.
        observation : str or int or list of str or list of int, optional
            Observation name or index. If None, all observations are selected.
        quantity : str or int or list of str or list of int, optional
            Quantity name or index. If None, all quantities are selected.
        start : str or datetime, optional
            Start time. If None, all times are selected.
        end : str or datetime, optional
            End time. If None, all times are selected.
        time : str or datetime, optional
            Time. If None, all times are selected.
        area : list of float, optional
            bbox: [x0, y0, x1, y1] or Polygon. If None, all areas are selected.
        **kwargs
            Filtering by comparer attrs similar to xarray.Dataset.filter_by_attrs
            e.g. `sel(gtype='track')` or `sel(obs_provider='CMEMS')` if at least
            one comparer has an entry `obs_provider` with value `CMEMS` in its
            attrs container. Multiple kwargs are combined with logical AND.

        Returns
        -------
        ComparerCollection
            New ComparerCollection with selected data.
        """
        if variable is not None:
            warnings.warn(
                "variable is deprecated, use quantity instead",
                FutureWarning,
            )
            quantity = variable
        # TODO is this really necessary to do both in ComparerCollection and Comparer?
        if model is not None:
            if isinstance(model, (str, int)):
                models = [model]
            else:
                models = list(model)
            mod_names: List[str] = [_get_name(m, self.mod_names) for m in models]
        if observation is None:
            observation = self.obs_names
        else:
            observation = [observation] if np.isscalar(observation) else observation  # type: ignore
            observation = [_get_name(o, self.obs_names) for o in observation]  # type: ignore

        if (quantity is not None) and (self.n_quantities > 1):
            quantity = [quantity] if np.isscalar(quantity) else quantity  # type: ignore
            quantity = [_get_name(v, self.quantity_names) for v in quantity]  # type: ignore
        else:
            quantity = self.quantity_names

        cmps = []
        for cmp in self._comparers.values():
            if cmp.name in observation and cmp.quantity.name in quantity:
                thismodel = (
                    [m for m in mod_names if m in cmp.mod_names] if model else None
                )
                if (thismodel is not None) and (len(thismodel) == 0):
                    continue
                cmpsel = cmp.sel(
                    model=thismodel,
                    start=start,
                    end=end,
                    time=time,
                    area=area,
                )
                if cmpsel is not None:
                    # TODO: check if cmpsel is empty
                    if cmpsel.n_points > 0:
                        cmps.append(cmpsel)
        cc = ComparerCollection(cmps)

        if kwargs:
            cc = cc.filter_by_attrs(**kwargs)

        return cc

    def filter_by_attrs(self, **kwargs: Any) -> "ComparerCollection":
        """Filter by comparer attrs similar to xarray.Dataset.filter_by_attrs

        Parameters
        ----------
        **kwargs
            Filtering by comparer attrs similar to xarray.Dataset.filter_by_attrs
            e.g. `sel(gtype='track')` or `sel(obs_provider='CMEMS')` if at least
            one comparer has an entry `obs_provider` with value `CMEMS` in its
            attrs container. Multiple kwargs are combined with logical AND.

        Returns
        -------
        ComparerCollection
            New ComparerCollection with selected data.

        Examples
        --------
        >>> cc = ms.match([HKNA, EPL, alti], mr)
        >>> cc.filter_by_attrs(gtype='track')
        <ComparerCollection>
        Comparer: alti
        """
        cmps = []
        for cmp in self._comparers.values():
            for k, v in kwargs.items():
                # TODO: should we also filter on cmp.data.Observation.attrs?
                if cmp.data.attrs.get(k) != v:
                    break
            else:
                cmps.append(cmp)
        return ComparerCollection(cmps)

    def query(self, query: str) -> "ComparerCollection":
        """Select data based on a query.

        Parameters
        ----------
        query : str
            Query string. See pandas.DataFrame.query() for details.

        Returns
        -------
        ComparerCollection
            New ComparerCollection with selected data.
        """
        q_cmps = [cmp.query(query) for cmp in self._comparers.values()]
        cmps_with_data = [cmp for cmp in q_cmps if cmp.n_points > 0]

        return ComparerCollection(cmps_with_data)

    def skill(
        self,
        by: str | Iterable[str] | None = None,
        metrics: Iterable[str] | Iterable[Callable] | str | Callable | None = None,
        observed: bool = False,
        **kwargs: Any,
    ) -> SkillTable:
        """Aggregated skill assessment of model(s)

        Parameters
        ----------
        by : str or List[str], optional
            group by, by default ["model", "observation"]

            - by column name
            - by temporal bin of the DateTimeIndex via the freq-argument
            (using pandas pd.Grouper(freq)), e.g.: 'freq:M' = monthly; 'freq:D' daily
            - by the dt accessor of the DateTimeIndex (e.g. 'dt.month') using the
            syntax 'dt:month'. The dt-argument is different from the freq-argument
            in that it gives month-of-year rather than month-of-data.
            - by attributes, stored in the cc.data.attrs container,
            e.g.: 'attrs:obs_provider' = group by observation provider or
            'attrs:gtype' = group by geometry type (track or point)
        metrics : list, optional
            list of modelskill.metrics (or str), by default modelskill.options.metrics.list
        observed: bool, optional
            This only applies if any of the groupers are Categoricals.

            - True: only show observed values for categorical groupers.
            - False: show all values for categorical groupers.

        Returns
        -------
        SkillTable
            skill assessment as a SkillTable object

        See also
        --------
        sel
            a method for filtering/selecting data

        Examples
        --------
        >>> import modelskill as ms
        >>> cc = ms.match([HKNA,EPL,c2], mr)
        >>> cc.skill().round(2)
                       n  bias  rmse  urmse   mae    cc    si    r2
        observation
        HKNA         385 -0.20  0.35   0.29  0.25  0.97  0.09  0.99
        EPL           66 -0.08  0.22   0.20  0.18  0.97  0.07  0.99
        c2           113 -0.00  0.35   0.35  0.29  0.97  0.12  0.99

        >>> cc.sel(observation='c2', start='2017-10-28').skill().round(2)
                       n  bias  rmse  urmse   mae    cc    si    r2
        observation
        c2            41  0.33  0.41   0.25  0.36  0.96  0.06  0.99

        >>> cc.skill(by='freq:D').round(2)
                      n  bias  rmse  urmse   mae    cc    si    r2
        2017-10-27  239 -0.15  0.25   0.21  0.20  0.72  0.10  0.98
        2017-10-28  162 -0.07  0.19   0.18  0.16  0.96  0.06  1.00
        2017-10-29  163 -0.21  0.52   0.47  0.42  0.79  0.11  0.99
        """

        # TODO remove in v1.1 ----------
        model, start, end, area = _get_deprecated_args(kwargs)  # type: ignore
        observation, variable = _get_deprecated_obs_var_args(kwargs)  # type: ignore
        assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

        cc = self.sel(
            model=model,
            observation=observation,
            quantity=variable,
            start=start,
            end=end,
            area=area,
        )
        if cc.n_points == 0:
            raise ValueError("Dataset is empty, no data to compare.")

        ## ---- end of deprecated code ----

        pmetrics = _parse_metric(metrics)

        agg_cols = _parse_groupby(by, n_mod=cc.n_models, n_qnt=cc.n_quantities)
        agg_cols, attrs_keys = self._attrs_keys_in_by(agg_cols)

        df = cc._to_long_dataframe(attrs_keys=attrs_keys, observed=observed)

        res = _groupby_df(df, by=agg_cols, metrics=pmetrics)
        mtr_cols = [m.__name__ for m in pmetrics]  # type: ignore
        res = res.dropna(subset=mtr_cols, how="all")  # TODO: ok to remove empty?
        res = self._append_xy_to_res(res, cc)
        res = cc._add_as_col_if_not_in_index(df, skilldf=res)  # type: ignore
        return SkillTable(res)

    def _to_long_dataframe(
        self, attrs_keys: Iterable[str] | None = None, observed: bool = False
    ) -> pd.DataFrame:
        """Return a copy of the data as a long-format pandas DataFrame (for groupby operations)"""
        frames = []
        for cmp in self:
            frame = cmp._to_long_dataframe(attrs_keys=attrs_keys)
            if self.n_quantities > 1:
                frame["quantity"] = cmp.quantity.name
            frames.append(frame)
        res = pd.concat(frames)

        cat_cols = res.select_dtypes(include=["object"]).columns
        res[cat_cols] = res[cat_cols].astype("category")

        if observed:
            res = res.loc[~(res == False).any(axis=1)]  # noqa
        return res

    @staticmethod
    def _attrs_keys_in_by(by: List[str | pd.Grouper]) -> Tuple[List[str], List[str]]:
        attrs_keys: List[str] = []
        agg_cols: List[str] = []
        for b in by:
            if isinstance(b, str) and b.startswith("attrs:"):
                key = b.split(":")[1]
                attrs_keys.append(key)
                agg_cols.append(key)
            else:
                agg_cols.append(b)
        return agg_cols, attrs_keys

    @staticmethod
    def _append_xy_to_res(res: pd.DataFrame, cc: ComparerCollection) -> pd.DataFrame:
        """skill() helper: Append x and y to res if possible"""
        res["x"] = np.nan
        res["y"] = np.nan

        # for MultiIndex in res find "observation" level and
        # insert x, y if gtype=point for that observation
        if "observation" in res.index.names:
            idx_names = res.index.names
            res = res.reset_index()
            for cmp in cc:
                if cmp.gtype == "point":
                    res.loc[res.observation == cmp.name, "x"] = cmp.x
                    res.loc[res.observation == cmp.name, "y"] = cmp.y
            res = res.set_index(idx_names)
        return res

    def _add_as_col_if_not_in_index(
        self,
        df: pd.DataFrame,
        skilldf: pd.DataFrame,
        fields: List[str] = ["model", "observation", "quantity"],
    ) -> pd.DataFrame:
        """skill() helper: Add a field to skilldf if unique in df"""
        for field in reversed(fields):
            if (field == "model") and (self.n_models <= 1):
                continue
            if (field == "quantity") and (self.n_quantities <= 1):
                continue
            if field not in skilldf.index.names:
                unames = df[field].unique()
                if len(unames) == 1:
                    skilldf.insert(loc=0, column=field, value=unames[0])
        return skilldf

    def gridded_skill(
        self,
        bins: int = 5,
        binsize: float | None = None,
        by: str | Iterable[str] | None = None,
        metrics: Iterable[str] | Iterable[Callable] | str | Callable | None = None,
        n_min: Optional[int] = None,
        **kwargs: Any,
    ) -> SkillGrid:
        """Skill assessment of model(s) on a regular spatial grid.

        Parameters
        ----------
        bins: int, list of scalars, or IntervalIndex, or tuple of, optional
            criteria to bin x and y by, argument bins to pd.cut(), default 5
            define different bins for x and y a tuple
            e.g.: bins = 5, bins = (5,[2,3,5])
        binsize : float, optional
            bin size for x and y dimension, overwrites bins
            creates bins with reference to round(mean(x)), round(mean(y))
        by : str, List[str], optional
            group by, by default ["model", "observation"]

            - by column name
            - by temporal bin of the DateTimeIndex via the freq-argument
            (using pandas pd.Grouper(freq)), e.g.: 'freq:M' = monthly; 'freq:D' daily
            - by the dt accessor of the DateTimeIndex (e.g. 'dt.month') using the
            syntax 'dt:month'. The dt-argument is different from the freq-argument
            in that it gives month-of-year rather than month-of-data.
        metrics : list, optional
            list of modelskill.metrics, by default modelskill.options.metrics.list
        n_min : int, optional
            minimum number of observations in a grid cell;
            cells with fewer observations get a score of `np.nan`

        Returns
        -------
        SkillGrid
            skill assessment as a SkillGrid object

        See also
        --------
        skill
            a method for aggregated skill assessment

        Examples
        --------
        >>> import modelskill as ms
        >>> cc = ms.match([HKNA,EPL,c2], mr)  # with satellite track measurements
        >>> gs = cc.gridded_skill(metrics='bias')
        >>> gs.data
        <xarray.Dataset>
        Dimensions:      (x: 5, y: 5)
        Coordinates:
            observation   'alti'
        * x            (x) float64 -0.436 1.543 3.517 5.492 7.466
        * y            (y) float64 50.6 51.66 52.7 53.75 54.8
        Data variables:
            n            (x, y) int32 3 0 0 14 37 17 50 36 72 ... 0 0 15 20 0 0 0 28 76
            bias         (x, y) float64 -0.02626 nan nan ... nan 0.06785 -0.1143

        >>> gs = cc.gridded_skill(binsize=0.5)
        >>> gs.data.coords
        Coordinates:
            observation   'alti'
        * x            (x) float64 -1.5 -0.5 0.5 1.5 2.5 3.5 4.5 5.5 6.5 7.5
        * y            (y) float64 51.5 52.5 53.5 54.5 55.5 56.5
        """

        model, start, end, area = _get_deprecated_args(kwargs)  # type: ignore
        observation, variable = _get_deprecated_obs_var_args(kwargs)  # type: ignore
        assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

        cmp = self.sel(
            model=model,
            observation=observation,
            quantity=variable,
            start=start,
            end=end,
            area=area,
        )

        if cmp.n_points == 0:
            raise ValueError("Dataset is empty, no data to compare.")

        ## ---- end of deprecated code ----

        metrics = _parse_metric(metrics)

        df = cmp._to_long_dataframe()
        df = _add_spatial_grid_to_df(df=df, bins=bins, binsize=binsize)

        agg_cols = _parse_groupby(by, n_mod=cmp.n_models, n_qnt=cmp.n_quantities)
        if "x" not in agg_cols:
            agg_cols.insert(0, "x")
        if "y" not in agg_cols:
            agg_cols.insert(0, "y")

        df = df.drop(columns=["x", "y"]).rename(columns=dict(xBin="x", yBin="y"))
        res = _groupby_df(df, by=agg_cols, metrics=metrics, n_min=n_min)
        ds = res.to_xarray().squeeze()

        # change categorial index to coordinates
        for dim in ("x", "y"):
            ds[dim] = ds[dim].astype(float)
        return SkillGrid(ds)

    def mean_skill(
        self,
        *,
        weights: Optional[Union[str, List[float], Dict[str, float]]] = None,
        metrics: Optional[list] = None,
        **kwargs: Any,
    ) -> SkillTable:
        """Weighted mean of skills

        First, the skill is calculated per observation,
        the weighted mean of the skills is then found.

        Warning: This method is NOT the mean skill of
        all observational points! (mean_skill_points)

        Parameters
        ----------
        weights : str or List(float) or Dict(str, float), optional
            weighting of observations, by default None

            - None: use observations weight attribute (if assigned, else "equal")
            - "equal": giving all observations equal weight,
            - "points": giving all points equal weight,
            - list of weights e.g. [0.3, 0.3, 0.4] per observation,
            - dictionary of observations with special weigths, others will be set to 1.0
        metrics : list, optional
            list of modelskill.metrics, by default modelskill.options.metrics.list

        Returns
        -------
        SkillTable
            mean skill assessment as a SkillTable object

        See also
        --------
        skill
            skill assessment per observation
        mean_skill_points
            skill assessment pooling all observation points together

        Examples
        --------
        >>> import modelskill as ms
        >>> cc = ms.match([HKNA,EPL,c2], mod=HKZN_local)
        >>> cc.mean_skill().round(2)
                      n  bias  rmse  urmse   mae    cc    si    r2
        HKZN_local  564 -0.09  0.31   0.28  0.24  0.97  0.09  0.99
        >>> sk = cc.mean_skill(weights="equal")
        >>> sk = cc.mean_skill(weights="points")
        >>> sk = cc.mean_skill(weights={"EPL": 2.0}) # more weight on EPL, others=1.0
        """

        # TODO remove in v1.1
        model, start, end, area = _get_deprecated_args(kwargs)  # type: ignore
        observation, variable = _get_deprecated_obs_var_args(kwargs)  # type: ignore
        assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

        # filter data
        cc = self.sel(
            model=model,  # deprecated
            observation=observation,  # deprecated
            quantity=variable,  # deprecated
            start=start,  # deprecated
            end=end,  # deprecated
            area=area,  # deprecated
        )
        if cc.n_points == 0:
            raise ValueError("Dataset is empty, no data to compare.")

        ## ---- end of deprecated code ----

        df = cc._to_long_dataframe()  # TODO: remove
        mod_names = cc.mod_names
        # obs_names = cmp.obs_names  # df.observation.unique()
        qnt_names = cc.quantity_names

        # skill assessment
        pmetrics = _parse_metric(metrics)
        sk = cc.skill(metrics=pmetrics)
        if sk is None:
            return None
        skilldf = sk.to_dataframe()

        # weights
        weights = cc._parse_weights(weights, sk.obs_names)
        skilldf["weights"] = (
            skilldf.n if weights is None else np.tile(weights, len(mod_names))  # type: ignore
        )

        def weighted_mean(x: Any) -> Any:
            return np.average(x, weights=skilldf.loc[x.index, "weights"])

        # group by
        by = cc._mean_skill_by(skilldf, mod_names, qnt_names)  # type: ignore
        agg = {"n": "sum"}
        for metric in pmetrics:  # type: ignore
            agg[metric.__name__] = weighted_mean  # type: ignore
        res = skilldf.groupby(by, observed=False).agg(agg)

        # TODO is this correct?
        res.index.name = "model"

        # output
        res = cc._add_as_col_if_not_in_index(df, res, fields=["model", "quantity"])  # type: ignore
        return SkillTable(res.astype({"n": int}))

    # def mean_skill_points(
    #     self,
    #     *,
    #     metrics: Optional[list] = None,
    #     **kwargs,
    # ) -> Optional[SkillTable]:  # TODO raise error if no data?
    #     """Mean skill of all observational points

    #     All data points are pooled (disregarding which observation they belong to),
    #     the skill is then found (for each model).

    #     .. note::
    #         No weighting can be applied with this method,
    #         use mean_skill() if you need to apply weighting

    #     .. warning::
    #         This method is NOT the mean of skills (mean_skill)

    #     Parameters
    #     ----------
    #     metrics : list, optional
    #         list of modelskill.metrics, by default modelskill.options.metrics.list

    #     Returns
    #     -------
    #     SkillTable
    #         mean skill assessment as a skill object

    #     See also
    #     --------
    #     skill
    #         skill assessment per observation
    #     mean_skill
    #         weighted mean of skills (not the same as this method)

    #     Examples
    #     --------
    #     >>> import modelskill as ms
    #     >>> cc = ms.match(obs, mod)
    #     >>> cc.mean_skill_points()
    #     """

    #     # TODO remove in v1.1
    #     model, start, end, area = _get_deprecated_args(kwargs)
    #     observation, variable = _get_deprecated_obs_var_args(kwargs)
    #     assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

    #     # filter data
    #     cmp = self.sel(
    #         model=model,
    #         observation=observation,
    #         variable=variable,
    #         start=start,
    #         end=end,
    #         area=area,
    #     )
    #     if cmp.n_points == 0:
    #         warnings.warn("No data!")
    #         return None

    #     dfall = cmp.to_dataframe()
    #     dfall["observation"] = "all"

    #     # TODO: no longer possible to do this way
    #     # return self.skill(df=dfall, metrics=metrics)
    #     return cmp.skill(metrics=metrics)  # NOT CORRECT - SEE ABOVE

    def _mean_skill_by(self, skilldf, mod_names, qnt_names):  # type: ignore
        by = []
        if len(mod_names) > 1:
            by.append("model")
        if len(qnt_names) > 1:
            by.append("quantity")
        if len(by) == 0:
            if (self.n_quantities > 1) and ("quantity" in skilldf):
                by.append("quantity")
            elif "model" in skilldf:
                by.append("model")
            else:
                by = [mod_names[0]] * len(skilldf)
        return by

    def _parse_weights(self, weights: Any, observations: Any) -> Any:
        if observations is None:
            observations = self.obs_names
        else:
            observations = [observations] if np.isscalar(observations) else observations
            observations = [_get_name(o, self.obs_names) for o in observations]
        n_obs = len(observations)

        if weights is None:
            # get weights from observation objects
            # default is equal weight to all
            weights = [self._comparers[o].weight for o in observations]
        else:
            if isinstance(weights, int):
                weights = np.ones(n_obs)  # equal weight to all
            elif isinstance(weights, dict):
                w_dict = weights
                weights = [w_dict.get(name, 1.0) for name in observations]

            elif isinstance(weights, str):
                if weights.lower() == "equal":
                    weights = np.ones(n_obs)  # equal weight to all
                elif "point" in weights.lower():
                    weights = None  # no weight => use n_points
                else:
                    raise ValueError(
                        "unknown weights argument (None, 'equal', 'points', or list of floats)"
                    )
            elif not np.isscalar(weights):
                if n_obs == 1:
                    if len(weights) > 1:
                        warnings.warn(
                            "Cannot apply multiple weights to one observation"
                        )
                    weights = [1.0]
                if not len(weights) == n_obs:
                    raise ValueError(
                        f"weights must have same length as observations: {observations}"
                    )
        if weights is not None:
            assert len(weights) == n_obs
        return weights

    def score(
        self,
        metric: str | Callable = mtr.rmse,
        **kwargs: Any,
    ) -> Dict[str, float]:
        """Weighted mean score of model(s) over all observations

        Wrapping mean_skill() with a single metric.

        NOTE: will take simple mean over different quantities!

        Parameters
        ----------
        weights : str or List(float) or Dict(str, float), optional
            weighting of observations, by default None

            - None: use observations weight attribute (if assigned, else "equal")
            - "equal": giving all observations equal weight,
            - "points": giving all points equal weight,
            - list of weights e.g. [0.3, 0.3, 0.4] per observation,
            - dictionary of observations with special weigths, others will be set to 1.0
        metric : list, optional
            a single metric from modelskill.metrics, by default rmse

        Returns
        -------
        Dict[str, float]
            mean of skills score as a single number (for each model)

        See also
        --------
        skill
            skill assessment per observation
        mean_skill
            weighted mean of skills assessment
        mean_skill_points
            skill assessment pooling all observation points together

        Examples
        --------
        >>> import modelskill as ms
        >>> cc = ms.match([o1, o2], mod)
        >>> cc.score()
        {'mod': 0.30681206}
        >>> cc.score(weights=[0.1,0.1,0.8])
        {'mod': 0.3383011631797379}

        >>> cc.score(weights='points', metric="mape")
        {'mod': 8.414442957854142}
        """

        weights = kwargs.pop("weights", None)

        metric = _parse_metric(metric)[0]

        if weights is None:
            weights = {c.name: c.weight for c in self._comparers.values()}

        if not (callable(metric) or isinstance(metric, str)):
            raise ValueError("metric must be a string or a function")

        model, start, end, area = _get_deprecated_args(kwargs)  # type: ignore
        observation, variable = _get_deprecated_obs_var_args(kwargs)  # type: ignore
        assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

        if model is None:
            models = self.mod_names
        else:
            # TODO: these two lines looks familiar, extract to function
            models = [model] if np.isscalar(model) else model  # type: ignore
            models = [_get_name(m, self.mod_names) for m in models]  # type: ignore

        cmp = self.sel(
            model=models,  # deprecated
            observation=observation,  # deprecated
            quantity=variable,  # deprecated
            start=start,  # deprecated
            end=end,  # deprecated
            area=area,  # deprecated
        )

        if cmp.n_points == 0:
            raise ValueError("Dataset is empty, no data to compare.")

        ## ---- end of deprecated code ----

        sk = cmp.mean_skill(weights=weights, metrics=[metric])
        df = sk.to_dataframe()

        metric_name = metric if isinstance(metric, str) else metric.__name__
        ser = df[metric_name]
        score = {str(col): float(value) for col, value in ser.items()}

        return score

    def save(self, filename: Union[str, Path]) -> None:
        """Save the ComparerCollection to a zip file.

        Each comparer is stored as a netcdf file in the zip file.

        Parameters
        ----------
        filename : str or Path
            Filename of the zip file.

        Examples
        --------
        >>> cc = ms.match(obs, mod)
        >>> cc.save("my_comparer_collection.msk")
        """

        files = []
        no = 0
        for name, cmp in self._comparers.items():
            cmp_fn = f"{no}_{name}.nc"
            cmp.save(cmp_fn)
            files.append(cmp_fn)
            no += 1

        with zipfile.ZipFile(filename, "w") as zip:
            for f in files:
                zip.write(f)
                os.remove(f)

    @staticmethod
    def load(filename: Union[str, Path]) -> "ComparerCollection":
        """Load a ComparerCollection from a zip file.

        Parameters
        ----------
        filename : str or Path
            Filename of the zip file.

        Returns
        -------
        ComparerCollection
            The loaded ComparerCollection.

        Examples
        --------
        >>> cc = ms.match(obs, mod)
        >>> cc.save("my_comparer_collection.msk")
        >>> cc2 = ms.ComparerCollection.load("my_comparer_collection.msk")
        """

        folder = tempfile.TemporaryDirectory().name

        with zipfile.ZipFile(filename, "r") as zip:
            for f in zip.namelist():
                if f.endswith(".nc"):
                    zip.extract(f, path=folder)

        comparers = [
            ComparerCollection._load_comparer(folder, f)
            for f in sorted(os.listdir(folder))
        ]
        return ComparerCollection(comparers)

    @staticmethod
    def _load_comparer(folder: str, f: str) -> Comparer:
        f = os.path.join(folder, f)
        cmp = Comparer.load(f)
        os.remove(f)
        return cmp

    # =============== Deprecated methods ===============

    def spatial_skill(
        self,
        bins=5,
        binsize=None,
        by=None,
        metrics=None,
        n_min=None,
        **kwargs,
    ):
        warnings.warn(
            "spatial_skill is deprecated, use gridded_skill instead", FutureWarning
        )
        return self.gridded_skill(
            bins=bins,
            binsize=binsize,
            by=by,
            metrics=metrics,
            n_min=n_min,
            **kwargs,
        )

    def scatter(
        self,
        *,
        bins=120,
        quantiles=None,
        fit_to_quantiles=False,
        show_points=None,
        show_hist=None,
        show_density=None,
        backend="matplotlib",
        figsize=(8, 8),
        xlim=None,
        ylim=None,
        reg_method="ols",
        title=None,
        xlabel=None,
        ylabel=None,
        skill_table=None,
        **kwargs,
    ):
        warnings.warn("scatter is deprecated, use plot.scatter instead", FutureWarning)

        # TODO remove in v1.1
        model, start, end, area = _get_deprecated_args(kwargs)
        observation, variable = _get_deprecated_obs_var_args(kwargs)

        # select model
        mod_idx = _get_idx(model, self.mod_names)
        mod_name = self.mod_names[mod_idx]

        # select variable
        qnt_idx = _get_idx(variable, self.quantity_names)
        qnt_name = self.quantity_names[qnt_idx]

        # filter data
        cmp = self.sel(
            model=mod_name,
            observation=observation,
            quantity=qnt_name,
            start=start,
            end=end,
            area=area,
        )

        return cmp.plot.scatter(
            bins=bins,
            quantiles=quantiles,
            fit_to_quantiles=fit_to_quantiles,
            show_points=show_points,
            show_hist=show_hist,
            show_density=show_density,
            backend=backend,
            figsize=figsize,
            xlim=xlim,
            ylim=ylim,
            reg_method=reg_method,
            title=title,
            xlabel=xlabel,
            ylabel=ylabel,
            skill_table=skill_table,
            **kwargs,
        )

    def taylor(
        self,
        normalize_std=False,
        aggregate_observations=True,
        figsize=(7, 7),
        marker="o",
        marker_size=6.0,
        title="Taylor diagram",
        **kwargs,
    ):
        warnings.warn("taylor is deprecated, use plot.taylor instead", FutureWarning)

        model, start, end, area = _get_deprecated_args(kwargs)
        observation, variable = _get_deprecated_obs_var_args(kwargs)
        assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

        cmp = self.sel(
            model=model,
            observation=observation,
            quantity=variable,
            start=start,
            end=end,
            area=area,
        )

        if cmp.n_points == 0:
            warnings.warn("No data!")
            return

        if (not aggregate_observations) and (not normalize_std):
            raise ValueError(
                "aggregate_observations=False is only possible if normalize_std=True!"
            )

        metrics = [mtr._std_obs, mtr._std_mod, mtr.cc]
        skill_func = cmp.mean_skill if aggregate_observations else cmp.skill
        sk = skill_func(metrics=metrics)

        df = sk.to_dataframe()
        ref_std = 1.0 if normalize_std else df.iloc[0]["_std_obs"]

        if isinstance(df.index, pd.MultiIndex):
            df.index = df.index.map("_".join)

        df = df[["_std_obs", "_std_mod", "cc"]].copy()
        df.columns = ["obs_std", "std", "cc"]
        pts = [
            TaylorPoint(
                r.Index, r.obs_std, r.std, r.cc, marker=marker, marker_size=marker_size
            )
            for r in df.itertuples()
        ]

        taylor_diagram(
            obs_std=ref_std,
            points=pts,
            figsize=figsize,
            normalize_std=normalize_std,
            title=title,
        )

    def kde(self, ax=None, **kwargs):
        warnings.warn("kde is deprecated, use plot.kde instead", FutureWarning)

        return self.plot.kde(ax=ax, **kwargs)

    def hist(
        self,
        model=None,
        bins=100,
        title=None,
        density=True,
        alpha=0.5,
        **kwargs,
    ):
        warnings.warn("hist is deprecated, use plot.hist instead", FutureWarning)

        return self.plot.hist(
            model=model, bins=bins, title=title, density=density, alpha=alpha, **kwargs
        )

aux_names property

aux_names

List of unique auxiliary names

end_time property

end_time

end timestamp of compared data

mod_names property

mod_names

List of unique model names

n_models property

n_models

Number of unique models

n_observations property

n_observations

Number of observations (same as len(cc))

n_points property

n_points

number of compared points

n_quantities property

n_quantities

Number of unique quantities

obs_names property

obs_names

List of observation names

plot instance-attribute

plot = plotter(self)

Plot using the ComparerCollectionPlotter

Examples:

>>> cc.plot.scatter()
>>> cc.plot.kde()
>>> cc.plot.taylor()
>>> cc.plot.hist()

quantity_names property

quantity_names

List of unique quantity names

start_time property

start_time

start timestamp of compared data

filter_by_attrs

filter_by_attrs(**kwargs)

Filter by comparer attrs similar to xarray.Dataset.filter_by_attrs

Parameters:

Name	Type	Description	Default
**kwargs	Any	Filtering by comparer attrs similar to xarray.Dataset.filter_by_attrs e.g. sel(gtype='track') or sel(obs_provider='CMEMS') if at least one comparer has an entry obs_provider with value CMEMS in its attrs container. Multiple kwargs are combined with logical AND.	{}

Returns:

Type	Description
ComparerCollection	New ComparerCollection with selected data.

Examples:

>>> cc = ms.match([HKNA, EPL, alti], mr)
>>> cc.filter_by_attrs(gtype='track')
<ComparerCollection>
Comparer: alti

Source code in modelskill/comparison/_collection.py

def filter_by_attrs(self, **kwargs: Any) -> "ComparerCollection":
    """Filter by comparer attrs similar to xarray.Dataset.filter_by_attrs

    Parameters
    ----------
    **kwargs
        Filtering by comparer attrs similar to xarray.Dataset.filter_by_attrs
        e.g. `sel(gtype='track')` or `sel(obs_provider='CMEMS')` if at least
        one comparer has an entry `obs_provider` with value `CMEMS` in its
        attrs container. Multiple kwargs are combined with logical AND.

    Returns
    -------
    ComparerCollection
        New ComparerCollection with selected data.

    Examples
    --------
    >>> cc = ms.match([HKNA, EPL, alti], mr)
    >>> cc.filter_by_attrs(gtype='track')
    <ComparerCollection>
    Comparer: alti
    """
    cmps = []
    for cmp in self._comparers.values():
        for k, v in kwargs.items():
            # TODO: should we also filter on cmp.data.Observation.attrs?
            if cmp.data.attrs.get(k) != v:
                break
        else:
            cmps.append(cmp)
    return ComparerCollection(cmps)

gridded_skill

gridded_skill(bins=5, binsize=None, by=None, metrics=None, n_min=None, **kwargs)

Skill assessment of model(s) on a regular spatial grid.

Parameters:

Name	Type	Description	Default
bins	int	criteria to bin x and y by, argument bins to pd.cut(), default 5 define different bins for x and y a tuple e.g.: bins = 5, bins = (5,[2,3,5])	5
binsize	float	bin size for x and y dimension, overwrites bins creates bins with reference to round(mean(x)), round(mean(y))	None
by	(str, List[str])	group by, by default ["model", "observation"] by column name by temporal bin of the DateTimeIndex via the freq-argument (using pandas pd.Grouper(freq)), e.g.: 'freq:M' = monthly; 'freq:D' daily by the dt accessor of the DateTimeIndex (e.g. 'dt.month') using the syntax 'dt:month'. The dt-argument is different from the freq-argument in that it gives month-of-year rather than month-of-data.	None
metrics	list	list of modelskill.metrics, by default modelskill.options.metrics.list	None
n_min	int	minimum number of observations in a grid cell; cells with fewer observations get a score of np.nan	None

Returns:

Type	Description
SkillGrid	skill assessment as a SkillGrid object

See also

skill a method for aggregated skill assessment

Examples:

>>> import modelskill as ms
>>> cc = ms.match([HKNA,EPL,c2], mr)  # with satellite track measurements
>>> gs = cc.gridded_skill(metrics='bias')
>>> gs.data
<xarray.Dataset>
Dimensions:      (x: 5, y: 5)
Coordinates:
    observation   'alti'
* x            (x) float64 -0.436 1.543 3.517 5.492 7.466
* y            (y) float64 50.6 51.66 52.7 53.75 54.8
Data variables:
    n            (x, y) int32 3 0 0 14 37 17 50 36 72 ... 0 0 15 20 0 0 0 28 76
    bias         (x, y) float64 -0.02626 nan nan ... nan 0.06785 -0.1143

>>> gs = cc.gridded_skill(binsize=0.5)
>>> gs.data.coords
Coordinates:
    observation   'alti'
* x            (x) float64 -1.5 -0.5 0.5 1.5 2.5 3.5 4.5 5.5 6.5 7.5
* y            (y) float64 51.5 52.5 53.5 54.5 55.5 56.5

Source code in modelskill/comparison/_collection.py

def gridded_skill(
    self,
    bins: int = 5,
    binsize: float | None = None,
    by: str | Iterable[str] | None = None,
    metrics: Iterable[str] | Iterable[Callable] | str | Callable | None = None,
    n_min: Optional[int] = None,
    **kwargs: Any,
) -> SkillGrid:
    """Skill assessment of model(s) on a regular spatial grid.

    Parameters
    ----------
    bins: int, list of scalars, or IntervalIndex, or tuple of, optional
        criteria to bin x and y by, argument bins to pd.cut(), default 5
        define different bins for x and y a tuple
        e.g.: bins = 5, bins = (5,[2,3,5])
    binsize : float, optional
        bin size for x and y dimension, overwrites bins
        creates bins with reference to round(mean(x)), round(mean(y))
    by : str, List[str], optional
        group by, by default ["model", "observation"]

        - by column name
        - by temporal bin of the DateTimeIndex via the freq-argument
        (using pandas pd.Grouper(freq)), e.g.: 'freq:M' = monthly; 'freq:D' daily
        - by the dt accessor of the DateTimeIndex (e.g. 'dt.month') using the
        syntax 'dt:month'. The dt-argument is different from the freq-argument
        in that it gives month-of-year rather than month-of-data.
    metrics : list, optional
        list of modelskill.metrics, by default modelskill.options.metrics.list
    n_min : int, optional
        minimum number of observations in a grid cell;
        cells with fewer observations get a score of `np.nan`

    Returns
    -------
    SkillGrid
        skill assessment as a SkillGrid object

    See also
    --------
    skill
        a method for aggregated skill assessment

    Examples
    --------
    >>> import modelskill as ms
    >>> cc = ms.match([HKNA,EPL,c2], mr)  # with satellite track measurements
    >>> gs = cc.gridded_skill(metrics='bias')
    >>> gs.data
    <xarray.Dataset>
    Dimensions:      (x: 5, y: 5)
    Coordinates:
        observation   'alti'
    * x            (x) float64 -0.436 1.543 3.517 5.492 7.466
    * y            (y) float64 50.6 51.66 52.7 53.75 54.8
    Data variables:
        n            (x, y) int32 3 0 0 14 37 17 50 36 72 ... 0 0 15 20 0 0 0 28 76
        bias         (x, y) float64 -0.02626 nan nan ... nan 0.06785 -0.1143

    >>> gs = cc.gridded_skill(binsize=0.5)
    >>> gs.data.coords
    Coordinates:
        observation   'alti'
    * x            (x) float64 -1.5 -0.5 0.5 1.5 2.5 3.5 4.5 5.5 6.5 7.5
    * y            (y) float64 51.5 52.5 53.5 54.5 55.5 56.5
    """

    model, start, end, area = _get_deprecated_args(kwargs)  # type: ignore
    observation, variable = _get_deprecated_obs_var_args(kwargs)  # type: ignore
    assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

    cmp = self.sel(
        model=model,
        observation=observation,
        quantity=variable,
        start=start,
        end=end,
        area=area,
    )

    if cmp.n_points == 0:
        raise ValueError("Dataset is empty, no data to compare.")

    ## ---- end of deprecated code ----

    metrics = _parse_metric(metrics)

    df = cmp._to_long_dataframe()
    df = _add_spatial_grid_to_df(df=df, bins=bins, binsize=binsize)

    agg_cols = _parse_groupby(by, n_mod=cmp.n_models, n_qnt=cmp.n_quantities)
    if "x" not in agg_cols:
        agg_cols.insert(0, "x")
    if "y" not in agg_cols:
        agg_cols.insert(0, "y")

    df = df.drop(columns=["x", "y"]).rename(columns=dict(xBin="x", yBin="y"))
    res = _groupby_df(df, by=agg_cols, metrics=metrics, n_min=n_min)
    ds = res.to_xarray().squeeze()

    # change categorial index to coordinates
    for dim in ("x", "y"):
        ds[dim] = ds[dim].astype(float)
    return SkillGrid(ds)

load staticmethod

load(filename)

Load a ComparerCollection from a zip file.

Parameters:

Name	Type	Description	Default
filename	str or Path	Filename of the zip file.	required

Returns:

Type	Description
ComparerCollection	The loaded ComparerCollection.

Examples:

>>> cc = ms.match(obs, mod)
>>> cc.save("my_comparer_collection.msk")
>>> cc2 = ms.ComparerCollection.load("my_comparer_collection.msk")

Source code in modelskill/comparison/_collection.py

@staticmethod
def load(filename: Union[str, Path]) -> "ComparerCollection":
    """Load a ComparerCollection from a zip file.

    Parameters
    ----------
    filename : str or Path
        Filename of the zip file.

    Returns
    -------
    ComparerCollection
        The loaded ComparerCollection.

    Examples
    --------
    >>> cc = ms.match(obs, mod)
    >>> cc.save("my_comparer_collection.msk")
    >>> cc2 = ms.ComparerCollection.load("my_comparer_collection.msk")
    """

    folder = tempfile.TemporaryDirectory().name

    with zipfile.ZipFile(filename, "r") as zip:
        for f in zip.namelist():
            if f.endswith(".nc"):
                zip.extract(f, path=folder)

    comparers = [
        ComparerCollection._load_comparer(folder, f)
        for f in sorted(os.listdir(folder))
    ]
    return ComparerCollection(comparers)

mean_skill

mean_skill(*, weights=None, metrics=None, **kwargs)

Weighted mean of skills

First, the skill is calculated per observation, the weighted mean of the skills is then found.

Warning: This method is NOT the mean skill of all observational points! (mean_skill_points)

Parameters:

Name	Type	Description	Default
weights	str or List(float) or Dict(str, float)	weighting of observations, by default None None: use observations weight attribute (if assigned, else "equal") "equal": giving all observations equal weight, "points": giving all points equal weight, list of weights e.g. [0.3, 0.3, 0.4] per observation, dictionary of observations with special weigths, others will be set to 1.0	None
metrics	list	list of modelskill.metrics, by default modelskill.options.metrics.list	None

Returns:

Type	Description
SkillTable	mean skill assessment as a SkillTable object

See also

skill skill assessment per observation mean_skill_points skill assessment pooling all observation points together

Examples:

>>> import modelskill as ms
>>> cc = ms.match([HKNA,EPL,c2], mod=HKZN_local)
>>> cc.mean_skill().round(2)
              n  bias  rmse  urmse   mae    cc    si    r2
HKZN_local  564 -0.09  0.31   0.28  0.24  0.97  0.09  0.99
>>> sk = cc.mean_skill(weights="equal")
>>> sk = cc.mean_skill(weights="points")
>>> sk = cc.mean_skill(weights={"EPL": 2.0}) # more weight on EPL, others=1.0

Source code in modelskill/comparison/_collection.py

def mean_skill(
    self,
    *,
    weights: Optional[Union[str, List[float], Dict[str, float]]] = None,
    metrics: Optional[list] = None,
    **kwargs: Any,
) -> SkillTable:
    """Weighted mean of skills

    First, the skill is calculated per observation,
    the weighted mean of the skills is then found.

    Warning: This method is NOT the mean skill of
    all observational points! (mean_skill_points)

    Parameters
    ----------
    weights : str or List(float) or Dict(str, float), optional
        weighting of observations, by default None

        - None: use observations weight attribute (if assigned, else "equal")
        - "equal": giving all observations equal weight,
        - "points": giving all points equal weight,
        - list of weights e.g. [0.3, 0.3, 0.4] per observation,
        - dictionary of observations with special weigths, others will be set to 1.0
    metrics : list, optional
        list of modelskill.metrics, by default modelskill.options.metrics.list

    Returns
    -------
    SkillTable
        mean skill assessment as a SkillTable object

    See also
    --------
    skill
        skill assessment per observation
    mean_skill_points
        skill assessment pooling all observation points together

    Examples
    --------
    >>> import modelskill as ms
    >>> cc = ms.match([HKNA,EPL,c2], mod=HKZN_local)
    >>> cc.mean_skill().round(2)
                  n  bias  rmse  urmse   mae    cc    si    r2
    HKZN_local  564 -0.09  0.31   0.28  0.24  0.97  0.09  0.99
    >>> sk = cc.mean_skill(weights="equal")
    >>> sk = cc.mean_skill(weights="points")
    >>> sk = cc.mean_skill(weights={"EPL": 2.0}) # more weight on EPL, others=1.0
    """

    # TODO remove in v1.1
    model, start, end, area = _get_deprecated_args(kwargs)  # type: ignore
    observation, variable = _get_deprecated_obs_var_args(kwargs)  # type: ignore
    assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

    # filter data
    cc = self.sel(
        model=model,  # deprecated
        observation=observation,  # deprecated
        quantity=variable,  # deprecated
        start=start,  # deprecated
        end=end,  # deprecated
        area=area,  # deprecated
    )
    if cc.n_points == 0:
        raise ValueError("Dataset is empty, no data to compare.")

    ## ---- end of deprecated code ----

    df = cc._to_long_dataframe()  # TODO: remove
    mod_names = cc.mod_names
    # obs_names = cmp.obs_names  # df.observation.unique()
    qnt_names = cc.quantity_names

    # skill assessment
    pmetrics = _parse_metric(metrics)
    sk = cc.skill(metrics=pmetrics)
    if sk is None:
        return None
    skilldf = sk.to_dataframe()

    # weights
    weights = cc._parse_weights(weights, sk.obs_names)
    skilldf["weights"] = (
        skilldf.n if weights is None else np.tile(weights, len(mod_names))  # type: ignore
    )

    def weighted_mean(x: Any) -> Any:
        return np.average(x, weights=skilldf.loc[x.index, "weights"])

    # group by
    by = cc._mean_skill_by(skilldf, mod_names, qnt_names)  # type: ignore
    agg = {"n": "sum"}
    for metric in pmetrics:  # type: ignore
        agg[metric.__name__] = weighted_mean  # type: ignore
    res = skilldf.groupby(by, observed=False).agg(agg)

    # TODO is this correct?
    res.index.name = "model"

    # output
    res = cc._add_as_col_if_not_in_index(df, res, fields=["model", "quantity"])  # type: ignore
    return SkillTable(res.astype({"n": int}))

query

query(query)

Select data based on a query.

Parameters:

Name	Type	Description	Default
query	str	Query string. See pandas.DataFrame.query() for details.	required

Returns:

Type	Description
ComparerCollection	New ComparerCollection with selected data.

Source code in modelskill/comparison/_collection.py

def query(self, query: str) -> "ComparerCollection":
    """Select data based on a query.

    Parameters
    ----------
    query : str
        Query string. See pandas.DataFrame.query() for details.

    Returns
    -------
    ComparerCollection
        New ComparerCollection with selected data.
    """
    q_cmps = [cmp.query(query) for cmp in self._comparers.values()]
    cmps_with_data = [cmp for cmp in q_cmps if cmp.n_points > 0]

    return ComparerCollection(cmps_with_data)

rename

rename(mapping)

Rename observation, model or auxiliary data variables

Parameters:

Name	Type	Description	Default
mapping	dict	mapping of old names to new names	required

Returns:

Type	Description
ComparerCollection

Examples:

>>> cc = ms.match([o1, o2], [mr1, mr2])
>>> cc.mod_names
['mr1', 'mr2']
>>> cc2 = cc.rename({'mr1': 'model1'})
>>> cc2.mod_names
['model1', 'mr2']

Source code in modelskill/comparison/_collection.py

def rename(self, mapping: Dict[str, str]) -> "ComparerCollection":
    """Rename observation, model or auxiliary data variables

    Parameters
    ----------
    mapping : dict
        mapping of old names to new names

    Returns
    -------
    ComparerCollection

    Examples
    --------
    >>> cc = ms.match([o1, o2], [mr1, mr2])
    >>> cc.mod_names
    ['mr1', 'mr2']
    >>> cc2 = cc.rename({'mr1': 'model1'})
    >>> cc2.mod_names
    ['model1', 'mr2']
    """
    for k in mapping.keys():
        allowed_keys = self.obs_names + self.mod_names + self.aux_names
        if k not in allowed_keys:
            raise KeyError(f"Unknown key: {k}; must be one of {allowed_keys}")

    cmps = []
    for cmp in self._comparers.values():
        cmps.append(cmp.rename(mapping, errors="ignore"))
    return ComparerCollection(cmps)

save

save(filename)

Save the ComparerCollection to a zip file.

Each comparer is stored as a netcdf file in the zip file.

Parameters:

Name	Type	Description	Default
filename	str or Path	Filename of the zip file.	required

Examples:

>>> cc = ms.match(obs, mod)
>>> cc.save("my_comparer_collection.msk")

Source code in modelskill/comparison/_collection.py

def save(self, filename: Union[str, Path]) -> None:
    """Save the ComparerCollection to a zip file.

    Each comparer is stored as a netcdf file in the zip file.

    Parameters
    ----------
    filename : str or Path
        Filename of the zip file.

    Examples
    --------
    >>> cc = ms.match(obs, mod)
    >>> cc.save("my_comparer_collection.msk")
    """

    files = []
    no = 0
    for name, cmp in self._comparers.items():
        cmp_fn = f"{no}_{name}.nc"
        cmp.save(cmp_fn)
        files.append(cmp_fn)
        no += 1

    with zipfile.ZipFile(filename, "w") as zip:
        for f in files:
            zip.write(f)
            os.remove(f)

score

score(metric=mtr.rmse, **kwargs)

Weighted mean score of model(s) over all observations

Wrapping mean_skill() with a single metric.

NOTE: will take simple mean over different quantities!

Parameters:

Name	Type	Description	Default
weights	str or List(float) or Dict(str, float)	weighting of observations, by default None None: use observations weight attribute (if assigned, else "equal") "equal": giving all observations equal weight, "points": giving all points equal weight, list of weights e.g. [0.3, 0.3, 0.4] per observation, dictionary of observations with special weigths, others will be set to 1.0	required
metric	list	a single metric from modelskill.metrics, by default rmse	rmse

Returns:

Type	Description
Dict[str, float]	mean of skills score as a single number (for each model)

See also

skill skill assessment per observation mean_skill weighted mean of skills assessment mean_skill_points skill assessment pooling all observation points together

Examples:

>>> import modelskill as ms
>>> cc = ms.match([o1, o2], mod)
>>> cc.score()
{'mod': 0.30681206}
>>> cc.score(weights=[0.1,0.1,0.8])
{'mod': 0.3383011631797379}

>>> cc.score(weights='points', metric="mape")
{'mod': 8.414442957854142}

Source code in modelskill/comparison/_collection.py

def score(
    self,
    metric: str | Callable = mtr.rmse,
    **kwargs: Any,
) -> Dict[str, float]:
    """Weighted mean score of model(s) over all observations

    Wrapping mean_skill() with a single metric.

    NOTE: will take simple mean over different quantities!

    Parameters
    ----------
    weights : str or List(float) or Dict(str, float), optional
        weighting of observations, by default None

        - None: use observations weight attribute (if assigned, else "equal")
        - "equal": giving all observations equal weight,
        - "points": giving all points equal weight,
        - list of weights e.g. [0.3, 0.3, 0.4] per observation,
        - dictionary of observations with special weigths, others will be set to 1.0
    metric : list, optional
        a single metric from modelskill.metrics, by default rmse

    Returns
    -------
    Dict[str, float]
        mean of skills score as a single number (for each model)

    See also
    --------
    skill
        skill assessment per observation
    mean_skill
        weighted mean of skills assessment
    mean_skill_points
        skill assessment pooling all observation points together

    Examples
    --------
    >>> import modelskill as ms
    >>> cc = ms.match([o1, o2], mod)
    >>> cc.score()
    {'mod': 0.30681206}
    >>> cc.score(weights=[0.1,0.1,0.8])
    {'mod': 0.3383011631797379}

    >>> cc.score(weights='points', metric="mape")
    {'mod': 8.414442957854142}
    """

    weights = kwargs.pop("weights", None)

    metric = _parse_metric(metric)[0]

    if weights is None:
        weights = {c.name: c.weight for c in self._comparers.values()}

    if not (callable(metric) or isinstance(metric, str)):
        raise ValueError("metric must be a string or a function")

    model, start, end, area = _get_deprecated_args(kwargs)  # type: ignore
    observation, variable = _get_deprecated_obs_var_args(kwargs)  # type: ignore
    assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

    if model is None:
        models = self.mod_names
    else:
        # TODO: these two lines looks familiar, extract to function
        models = [model] if np.isscalar(model) else model  # type: ignore
        models = [_get_name(m, self.mod_names) for m in models]  # type: ignore

    cmp = self.sel(
        model=models,  # deprecated
        observation=observation,  # deprecated
        quantity=variable,  # deprecated
        start=start,  # deprecated
        end=end,  # deprecated
        area=area,  # deprecated
    )

    if cmp.n_points == 0:
        raise ValueError("Dataset is empty, no data to compare.")

    ## ---- end of deprecated code ----

    sk = cmp.mean_skill(weights=weights, metrics=[metric])
    df = sk.to_dataframe()

    metric_name = metric if isinstance(metric, str) else metric.__name__
    ser = df[metric_name]
    score = {str(col): float(value) for col, value in ser.items()}

    return score

sel

sel(model=None, observation=None, quantity=None, start=None, end=None, time=None, area=None, variable=None, **kwargs)

Select data based on model, time and/or area.

Parameters:

Name	Type	Description	Default
model	str or int or list of str or list of int	Model name or index. If None, all models are selected.	None
observation	str or int or list of str or list of int	Observation name or index. If None, all observations are selected.	None
quantity	str or int or list of str or list of int	Quantity name or index. If None, all quantities are selected.	None
start	str or datetime	Start time. If None, all times are selected.	None
end	str or datetime	End time. If None, all times are selected.	None
time	str or datetime	Time. If None, all times are selected.	None
area	list of float	bbox: [x0, y0, x1, y1] or Polygon. If None, all areas are selected.	None
**kwargs	Any	Filtering by comparer attrs similar to xarray.Dataset.filter_by_attrs e.g. sel(gtype='track') or sel(obs_provider='CMEMS') if at least one comparer has an entry obs_provider with value CMEMS in its attrs container. Multiple kwargs are combined with logical AND.	{}

Returns:

Type	Description
ComparerCollection	New ComparerCollection with selected data.

Source code in modelskill/comparison/_collection.py

def sel(
    self,
    model: Optional[IdxOrNameTypes] = None,
    observation: Optional[IdxOrNameTypes] = None,
    quantity: Optional[IdxOrNameTypes] = None,
    start: Optional[TimeTypes] = None,
    end: Optional[TimeTypes] = None,
    time: Optional[TimeTypes] = None,
    area: Optional[List[float]] = None,
    variable: Optional[IdxOrNameTypes] = None,  # obsolete
    **kwargs: Any,
) -> "ComparerCollection":
    """Select data based on model, time and/or area.

    Parameters
    ----------
    model : str or int or list of str or list of int, optional
        Model name or index. If None, all models are selected.
    observation : str or int or list of str or list of int, optional
        Observation name or index. If None, all observations are selected.
    quantity : str or int or list of str or list of int, optional
        Quantity name or index. If None, all quantities are selected.
    start : str or datetime, optional
        Start time. If None, all times are selected.
    end : str or datetime, optional
        End time. If None, all times are selected.
    time : str or datetime, optional
        Time. If None, all times are selected.
    area : list of float, optional
        bbox: [x0, y0, x1, y1] or Polygon. If None, all areas are selected.
    **kwargs
        Filtering by comparer attrs similar to xarray.Dataset.filter_by_attrs
        e.g. `sel(gtype='track')` or `sel(obs_provider='CMEMS')` if at least
        one comparer has an entry `obs_provider` with value `CMEMS` in its
        attrs container. Multiple kwargs are combined with logical AND.

    Returns
    -------
    ComparerCollection
        New ComparerCollection with selected data.
    """
    if variable is not None:
        warnings.warn(
            "variable is deprecated, use quantity instead",
            FutureWarning,
        )
        quantity = variable
    # TODO is this really necessary to do both in ComparerCollection and Comparer?
    if model is not None:
        if isinstance(model, (str, int)):
            models = [model]
        else:
            models = list(model)
        mod_names: List[str] = [_get_name(m, self.mod_names) for m in models]
    if observation is None:
        observation = self.obs_names
    else:
        observation = [observation] if np.isscalar(observation) else observation  # type: ignore
        observation = [_get_name(o, self.obs_names) for o in observation]  # type: ignore

    if (quantity is not None) and (self.n_quantities > 1):
        quantity = [quantity] if np.isscalar(quantity) else quantity  # type: ignore
        quantity = [_get_name(v, self.quantity_names) for v in quantity]  # type: ignore
    else:
        quantity = self.quantity_names

    cmps = []
    for cmp in self._comparers.values():
        if cmp.name in observation and cmp.quantity.name in quantity:
            thismodel = (
                [m for m in mod_names if m in cmp.mod_names] if model else None
            )
            if (thismodel is not None) and (len(thismodel) == 0):
                continue
            cmpsel = cmp.sel(
                model=thismodel,
                start=start,
                end=end,
                time=time,
                area=area,
            )
            if cmpsel is not None:
                # TODO: check if cmpsel is empty
                if cmpsel.n_points > 0:
                    cmps.append(cmpsel)
    cc = ComparerCollection(cmps)

    if kwargs:
        cc = cc.filter_by_attrs(**kwargs)

    return cc

skill

skill(by=None, metrics=None, observed=False, **kwargs)

Aggregated skill assessment of model(s)

Parameters:

Name	Type	Description	Default
by	str or List[str]	group by, by default ["model", "observation"] by column name by temporal bin of the DateTimeIndex via the freq-argument (using pandas pd.Grouper(freq)), e.g.: 'freq:M' = monthly; 'freq:D' daily by the dt accessor of the DateTimeIndex (e.g. 'dt.month') using the syntax 'dt:month'. The dt-argument is different from the freq-argument in that it gives month-of-year rather than month-of-data. by attributes, stored in the cc.data.attrs container, e.g.: 'attrs:obs_provider' = group by observation provider or 'attrs:gtype' = group by geometry type (track or point)	None
metrics	list	list of modelskill.metrics (or str), by default modelskill.options.metrics.list	None
observed	bool	This only applies if any of the groupers are Categoricals. True: only show observed values for categorical groupers. False: show all values for categorical groupers.	False

Returns:

Type	Description
SkillTable	skill assessment as a SkillTable object

See also

sel a method for filtering/selecting data

Examples:

>>> import modelskill as ms
>>> cc = ms.match([HKNA,EPL,c2], mr)
>>> cc.skill().round(2)
               n  bias  rmse  urmse   mae    cc    si    r2
observation
HKNA         385 -0.20  0.35   0.29  0.25  0.97  0.09  0.99
EPL           66 -0.08  0.22   0.20  0.18  0.97  0.07  0.99
c2           113 -0.00  0.35   0.35  0.29  0.97  0.12  0.99

>>> cc.sel(observation='c2', start='2017-10-28').skill().round(2)
               n  bias  rmse  urmse   mae    cc    si    r2
observation
c2            41  0.33  0.41   0.25  0.36  0.96  0.06  0.99

>>> cc.skill(by='freq:D').round(2)
              n  bias  rmse  urmse   mae    cc    si    r2
2017-10-27  239 -0.15  0.25   0.21  0.20  0.72  0.10  0.98
2017-10-28  162 -0.07  0.19   0.18  0.16  0.96  0.06  1.00
2017-10-29  163 -0.21  0.52   0.47  0.42  0.79  0.11  0.99

Source code in modelskill/comparison/_collection.py

def skill(
    self,
    by: str | Iterable[str] | None = None,
    metrics: Iterable[str] | Iterable[Callable] | str | Callable | None = None,
    observed: bool = False,
    **kwargs: Any,
) -> SkillTable:
    """Aggregated skill assessment of model(s)

    Parameters
    ----------
    by : str or List[str], optional
        group by, by default ["model", "observation"]

        - by column name
        - by temporal bin of the DateTimeIndex via the freq-argument
        (using pandas pd.Grouper(freq)), e.g.: 'freq:M' = monthly; 'freq:D' daily
        - by the dt accessor of the DateTimeIndex (e.g. 'dt.month') using the
        syntax 'dt:month'. The dt-argument is different from the freq-argument
        in that it gives month-of-year rather than month-of-data.
        - by attributes, stored in the cc.data.attrs container,
        e.g.: 'attrs:obs_provider' = group by observation provider or
        'attrs:gtype' = group by geometry type (track or point)
    metrics : list, optional
        list of modelskill.metrics (or str), by default modelskill.options.metrics.list
    observed: bool, optional
        This only applies if any of the groupers are Categoricals.

        - True: only show observed values for categorical groupers.
        - False: show all values for categorical groupers.

    Returns
    -------
    SkillTable
        skill assessment as a SkillTable object

    See also
    --------
    sel
        a method for filtering/selecting data

    Examples
    --------
    >>> import modelskill as ms
    >>> cc = ms.match([HKNA,EPL,c2], mr)
    >>> cc.skill().round(2)
                   n  bias  rmse  urmse   mae    cc    si    r2
    observation
    HKNA         385 -0.20  0.35   0.29  0.25  0.97  0.09  0.99
    EPL           66 -0.08  0.22   0.20  0.18  0.97  0.07  0.99
    c2           113 -0.00  0.35   0.35  0.29  0.97  0.12  0.99

    >>> cc.sel(observation='c2', start='2017-10-28').skill().round(2)
                   n  bias  rmse  urmse   mae    cc    si    r2
    observation
    c2            41  0.33  0.41   0.25  0.36  0.96  0.06  0.99

    >>> cc.skill(by='freq:D').round(2)
                  n  bias  rmse  urmse   mae    cc    si    r2
    2017-10-27  239 -0.15  0.25   0.21  0.20  0.72  0.10  0.98
    2017-10-28  162 -0.07  0.19   0.18  0.16  0.96  0.06  1.00
    2017-10-29  163 -0.21  0.52   0.47  0.42  0.79  0.11  0.99
    """

    # TODO remove in v1.1 ----------
    model, start, end, area = _get_deprecated_args(kwargs)  # type: ignore
    observation, variable = _get_deprecated_obs_var_args(kwargs)  # type: ignore
    assert kwargs == {}, f"Unknown keyword arguments: {kwargs}"

    cc = self.sel(
        model=model,
        observation=observation,
        quantity=variable,
        start=start,
        end=end,
        area=area,
    )
    if cc.n_points == 0:
        raise ValueError("Dataset is empty, no data to compare.")

    ## ---- end of deprecated code ----

    pmetrics = _parse_metric(metrics)

    agg_cols = _parse_groupby(by, n_mod=cc.n_models, n_qnt=cc.n_quantities)
    agg_cols, attrs_keys = self._attrs_keys_in_by(agg_cols)

    df = cc._to_long_dataframe(attrs_keys=attrs_keys, observed=observed)

    res = _groupby_df(df, by=agg_cols, metrics=pmetrics)
    mtr_cols = [m.__name__ for m in pmetrics]  # type: ignore
    res = res.dropna(subset=mtr_cols, how="all")  # TODO: ok to remove empty?
    res = self._append_xy_to_res(res, cc)
    res = cc._add_as_col_if_not_in_index(df, skilldf=res)  # type: ignore
    return SkillTable(res)

modelskill.comparison._collection_plotter.ComparerCollectionPlotter

Plotter for ComparerCollection

Examples:

>>> cc.plot.scatter()
>>> cc.plot.hist()
>>> cc.plot.kde()
>>> cc.plot.taylor()
>>> cc.plot.box()

Source code in modelskill/comparison/_collection_plotter.py

class ComparerCollectionPlotter:
    """Plotter for ComparerCollection

    Examples
    --------
    >>> cc.plot.scatter()
    >>> cc.plot.hist()
    >>> cc.plot.kde()
    >>> cc.plot.taylor()
    >>> cc.plot.box()
    """

    def __init__(self, cc: ComparerCollection) -> None:
        self.cc = cc
        self.is_directional = False

    def __call__(self, *args: Any, **kwds: Any) -> Axes | list[Axes]:
        return self.scatter(*args, **kwds)

    def scatter(
        self,
        *,
        model=None,
        bins: int | float = 120,
        quantiles: int | Sequence[float] | None = None,
        fit_to_quantiles: bool = False,
        show_points: bool | int | float | None = None,
        show_hist: Optional[bool] = None,
        show_density: Optional[bool] = None,
        norm: Optional[colors.Normalize] = None,
        backend: Literal["matplotlib", "plotly"] = "matplotlib",
        figsize: Tuple[float, float] = (8, 8),
        xlim: Optional[Tuple[float, float]] = None,
        ylim: Optional[Tuple[float, float]] = None,
        reg_method: str | bool = "ols",
        title: Optional[str] = None,
        xlabel: Optional[str] = None,
        ylabel: Optional[str] = None,
        skill_table: Optional[Union[str, List[str], bool]] = None,
        ax: Optional[Axes] = None,
        **kwargs,
    ) -> Axes | list[Axes]:
        """Scatter plot showing compared data: observation vs modelled
        Optionally, with density histogram.

        Parameters
        ----------
        bins: (int, float, sequence), optional
            bins for the 2D histogram on the background. By default 20 bins.
            if int, represents the number of bins of 2D
            if float, represents the bin size
            if sequence (list of int or float), represents the bin edges
        quantiles: (int, sequence), optional
            number of quantiles for QQ-plot, by default None and will depend
            on the scatter data length (10, 100 or 1000); if int, this is
            the number of points; if sequence (list of floats), represents
            the desired quantiles (from 0 to 1)
        fit_to_quantiles: bool, optional, by default False
            by default the regression line is fitted to all data, if True,
            it is fitted to the quantiles which can be useful to represent
            the extremes of the distribution, by default False
        show_points : (bool, int, float), optional
            Should the scatter points be displayed? None means: show all
            points if fewer than 1e4, otherwise show 1e4 sample points,
            by default None. float: fraction of points to show on plot
            from 0 to 1. e.g. 0.5 shows 50% of the points. int: if 'n' (int)
            given, then 'n' points will be displayed, randomly selected
        show_hist : bool, optional
            show the data density as a a 2d histogram, by default None
        show_density: bool, optional
            show the data density as a colormap of the scatter, by default
            None. If both `show_density` and `show_hist` are None, then
            `show_density` is used by default. For binning the data, the
            kword `bins=Float` is used.
        norm : matplotlib.colors norm
            colormap normalization. If None, defaults to
            matplotlib.colors.PowerNorm(vmin=1, gamma=0.5)
        backend : str, optional
            use "plotly" (interactive) or "matplotlib" backend,
            by default "matplotlib"
        figsize : tuple, optional
            width and height of the figure, by default (8, 8)
        xlim : tuple, optional
            plot range for the observation (xmin, xmax), by default None
        ylim : tuple, optional
            plot range for the model (ymin, ymax), by default None
        reg_method : str or bool, optional
            method for determining the regression line
            "ols" : ordinary least squares regression
            "odr" : orthogonal distance regression,
            False : no regression line,
            by default "ols"
        title : str, optional
            plot title, by default None
        xlabel : str, optional
            x-label text on plot, by default None
        ylabel : str, optional
            y-label text on plot, by default None
        skill_table : str, List[str], bool, optional
            list of modelskill.metrics or boolean, if True then by default modelskill.options.metrics.list.
            This kword adds a box at the right of the scatter plot,
            by default False
        ax : matplotlib axes, optional
            axes to plot on, by default None
        **kwargs
            other keyword arguments to matplotlib.pyplot.scatter()

        Examples
        ------
        >>> cc.plot.scatter()
        >>> cc.plot.scatter(bins=0.2, backend='plotly')
        >>> cc.plot.scatter(show_points=False, title='no points')
        >>> cc.plot.scatter(xlabel='all observations', ylabel='my model')
        >>> cc.sel(model='HKZN_v2').plot.scatter(figsize=(10, 10))
        >>> cc.sel(observations=['c2','HKNA']).plot.scatter()
        """

        cc = self.cc
        if model is None:
            mod_names = cc.mod_names
        else:
            warnings.warn(
                "The 'model' keyword is deprecated! Instead, filter comparer before plotting cmp.sel(model=...).plot.scatter()",
                FutureWarning,
            )

            model_list = [model] if isinstance(model, (str, int)) else model
            mod_names = [
                self.cc.mod_names[_get_idx(m, self.cc.mod_names)] for m in model_list
            ]

        axes = []
        for mod_name in mod_names:
            ax_mod = self._scatter_one_model(
                mod_name=mod_name,
                bins=bins,
                quantiles=quantiles,
                fit_to_quantiles=fit_to_quantiles,
                show_points=show_points,
                show_hist=show_hist,
                show_density=show_density,
                norm=norm,
                backend=backend,
                figsize=figsize,
                xlim=xlim,
                ylim=ylim,
                reg_method=reg_method,
                title=title,
                xlabel=xlabel,
                ylabel=ylabel,
                skill_table=skill_table,
                ax=ax,
                **kwargs,
            )
            axes.append(ax_mod)
        return axes[0] if len(axes) == 1 else axes

    def _scatter_one_model(
        self,
        *,
        mod_name: str,
        bins: int | float,
        quantiles: int | Sequence[float] | None,
        fit_to_quantiles: bool,
        show_points: bool | int | float | None,
        show_hist: Optional[bool],
        show_density: Optional[bool],
        backend: Literal["matplotlib", "plotly"],
        figsize: Tuple[float, float],
        xlim: Optional[Tuple[float, float]],
        ylim: Optional[Tuple[float, float]],
        reg_method: str | bool,
        title: Optional[str],
        xlabel: Optional[str],
        ylabel: Optional[str],
        skill_table: Optional[Union[str, List[str], bool]],
        ax,
        **kwargs,
    ):
        assert (
            mod_name in self.cc.mod_names
        ), f"Model {mod_name} not found in collection {self.cc.mod_names}"

        cc_sel_mod = self.cc.sel(model=mod_name)

        if cc_sel_mod.n_points == 0:
            raise ValueError("No data found in selection")

        df = cc_sel_mod._to_long_dataframe()
        x = df.obs_val.values
        y = df.mod_val.values

        # TODO why the first?
        unit_text = self.cc[0]._unit_text

        xlabel = xlabel or f"Observation, {unit_text}"
        ylabel = ylabel or f"Model, {unit_text}"
        title = title or f"{mod_name} vs {cc_sel_mod._name}"

        skill = None
        skill_score_unit = None
        if skill_table:
            metrics = None if skill_table is True else skill_table

            # TODO why is this here?
            if isinstance(self, ComparerCollectionPlotter) and len(cc_sel_mod) == 1:
                skill = cc_sel_mod.skill(metrics=metrics)  # type: ignore
            else:
                skill = cc_sel_mod.mean_skill(metrics=metrics)  # type: ignore
            # TODO improve this
            try:
                skill_score_unit = unit_text.split("[")[1].split("]")[0]
            except IndexError:
                skill_score_unit = ""  # Dimensionless

        if self.is_directional:
            # hide quantiles and regression line
            quantiles = 0
            reg_method = False

        skill_scores = skill.iloc[0].to_dict() if skill is not None else None

        ax = scatter(
            x=x,
            y=y,
            bins=bins,
            quantiles=quantiles,
            fit_to_quantiles=fit_to_quantiles,
            show_points=show_points,
            show_hist=show_hist,
            show_density=show_density,
            backend=backend,
            figsize=figsize,
            xlim=xlim,
            ylim=ylim,
            reg_method=reg_method,
            title=title,
            xlabel=xlabel,
            ylabel=ylabel,
            skill_scores=skill_scores,
            skill_score_unit=skill_score_unit,
            ax=ax,
            **kwargs,
        )

        if backend == "matplotlib" and self.is_directional:
            _xtick_directional(ax, xlim)
            _ytick_directional(ax, ylim)

        return ax

    def kde(self, *, ax=None, figsize=None, title=None, **kwargs) -> Axes:
        """Plot kernel density estimate of observation and model data.

        Parameters
        ----------
        ax : Axes, optional
            matplotlib axes, by default None
        figsize : tuple, optional
            width and height of the figure, by default None
        title : str, optional
            plot title, by default None
        **kwargs
            passed to pandas.DataFrame.plot.kde()

        Returns
        -------
        Axes
            matplotlib axes

        Examples
        --------
        >>> cc.plot.kde()
        >>> cc.plot.kde(bw_method=0.5)
        >>> cc.plot.kde(bw_method='silverman')

        """
        _, ax = _get_fig_ax(ax, figsize)

        df = self.cc._to_long_dataframe()
        ax = df.obs_val.plot.kde(
            ax=ax, linestyle="dashed", label="Observation", **kwargs
        )

        for model in self.cc.mod_names:
            df_model = df[df.model == model]
            df_model.mod_val.plot.kde(ax=ax, label=model, **kwargs)

        ax.set_xlabel(f"{self.cc._unit_text}")

        title = (
            _default_univarate_title("Density plot", self.cc)
            if title is None
            else title
        )
        ax.set_title(title)
        ax.legend()

        # remove y-axis, ticks and label
        ax.yaxis.set_visible(False)
        ax.tick_params(axis="y", which="both", length=0)
        ax.set_ylabel("")

        # remove box around plot
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)
        ax.spines["left"].set_visible(False)

        if self.is_directional:
            _xtick_directional(ax)

        return ax

    def hist(
        self,
        bins: int | Sequence = 100,
        *,
        model: str | int | None = None,
        title: Optional[str] = None,
        density: bool = True,
        alpha: float = 0.5,
        ax=None,
        figsize: Optional[Tuple[float, float]] = None,
        **kwargs,
    ):
        """Plot histogram of specific model and all observations.

        Wraps pandas.DataFrame hist() method.

        Parameters
        ----------
        bins : int, optional
            number of bins, by default 100
        title : str, optional
            plot title, default: observation name
        density: bool, optional
            If True, draw and return a probability density, by default True
        alpha : float, optional
            alpha transparency fraction, by default 0.5
        ax : matplotlib axes, optional
            axes to plot on, by default None
        figsize : tuple, optional
            width and height of the figure, by default None
        **kwargs
            other keyword arguments to df.hist()

        Returns
        -------
        matplotlib axes

        Examples
        --------
        >>> cc.plot.hist()
        >>> cc.plot.hist(bins=100)

        See also
        --------
        pandas.Series.hist
        matplotlib.axes.Axes.hist
        """
        if model is None:
            mod_names = self.cc.mod_names
        else:
            warnings.warn(
                "The 'model' keyword is deprecated! Instead, filter comparer before plotting cmp.sel(model=...).plot.hist()",
                FutureWarning,
            )
            model_list = [model] if isinstance(model, (str, int)) else model
            mod_names = [
                self.cc.mod_names[_get_idx(m, self.cc.mod_names)] for m in model_list
            ]

        axes = []
        for mod_name in mod_names:
            ax_mod = self._hist_one_model(
                mod_name=mod_name,
                bins=bins,
                title=title,
                density=density,
                alpha=alpha,
                ax=ax,
                figsize=figsize,
                **kwargs,
            )
            axes.append(ax_mod)
        return axes[0] if len(axes) == 1 else axes

    def _hist_one_model(
        self,
        *,
        mod_name: str,
        bins: int | Sequence,
        title: Optional[str],
        density: bool,
        alpha: float,
        ax,
        figsize: Optional[Tuple[float, float]],
        **kwargs,
    ):
        from ._comparison import MOD_COLORS

        _, ax = _get_fig_ax(ax, figsize)

        assert (
            mod_name in self.cc.mod_names
        ), f"Model {mod_name} not found in collection"
        mod_idx = _get_idx(mod_name, self.cc.mod_names)

        title = (
            _default_univarate_title("Histogram", self.cc) if title is None else title
        )

        cmp = self.cc
        df = cmp._to_long_dataframe()
        kwargs["alpha"] = alpha
        kwargs["density"] = density
        df.mod_val.hist(bins=bins, color=MOD_COLORS[mod_idx], ax=ax, **kwargs)
        df.obs_val.hist(
            bins=bins,
            color=self.cc[0].data["Observation"].attrs["color"],
            ax=ax,
            **kwargs,
        )

        ax.legend([mod_name, "observations"])
        ax.set_title(title)
        ax.set_xlabel(f"{self.cc[df.observation.iloc[0]]._unit_text}")

        if density:
            ax.set_ylabel("density")
        else:
            ax.set_ylabel("count")

        if self.is_directional:
            _xtick_directional(ax)

        return ax

    def taylor(
        self,
        *,
        normalize_std: bool = False,
        aggregate_observations: bool = True,
        figsize: Tuple[float, float] = (7, 7),
        marker: str = "o",
        marker_size: float = 6.0,
        title: str = "Taylor diagram",
    ):
        """Taylor diagram showing model std and correlation to observation
        in a single-quadrant polar plot, with r=std and theta=arccos(cc).

        Parameters
        ----------
        normalize_std : bool, optional
            plot model std normalized with observation std, default False
        aggregate_observations : bool, optional
            should multiple observations be aggregated before plotting
            (or shown individually), default True
        figsize : tuple, optional
            width and height of the figure (should be square), by default (7, 7)
        marker : str, optional
            marker type e.g. "x", "*", by default "o"
        marker_size : float, optional
            size of the marker, by default 6
        title : str, optional
            title of the plot, by default "Taylor diagram"

        Returns
        -------
        matplotlib.figure.Figure

        Examples
        ------
        >>> cc.plot.taylor()
        >>> cc.plot.taylor(observation="c2")
        >>> cc.plot.taylor(start="2017-10-28", figsize=(5,5))

        References
        ----------
        Copin, Y. (2018). https://gist.github.com/ycopin/3342888, Yannick Copin <yannick.copin@laposte.net>
        """

        if (not aggregate_observations) and (not normalize_std):
            raise ValueError(
                "aggregate_observations=False is only possible if normalize_std=True!"
            )

        metrics = [mtr._std_obs, mtr._std_mod, mtr.cc]
        skill_func = self.cc.mean_skill if aggregate_observations else self.cc.skill
        sk = skill_func(
            metrics=metrics,  # type: ignore
        )
        if sk is None:
            return

        df = sk.to_dataframe()
        ref_std = 1.0 if normalize_std else df.iloc[0]["_std_obs"]

        if isinstance(df.index, pd.MultiIndex):
            df.index = df.index.map("_".join)

        df = df[["_std_obs", "_std_mod", "cc"]].copy()
        df.columns = ["obs_std", "std", "cc"]
        pts = [
            TaylorPoint(
                r.Index, r.obs_std, r.std, r.cc, marker=marker, marker_size=marker_size
            )
            for r in df.itertuples()
        ]

        return taylor_diagram(
            obs_std=ref_std,
            points=pts,
            figsize=figsize,
            normalize_std=normalize_std,
            title=title,
        )

    def box(self, *, ax=None, figsize=None, title=None, **kwargs) -> Axes:
        """Plot box plot of observations and model data.

        Parameters
        ----------
        ax : Axes, optional
            matplotlib axes, by default None
        figsize : tuple, optional
            width and height of the figure, by default None
        title : str, optional
            plot title, by default None
        **kwargs
            passed to pandas.DataFrame.plot.box()

        Returns
        -------
        Axes
            matplotlib axes

        Examples
        --------
        >>> cc.plot.box()
        >>> cc.plot.box(showmeans=True)
        >>> cc.plot.box(ax=ax, title="Box plot")
        """
        _, ax = _get_fig_ax(ax, figsize)

        df = self.cc._to_long_dataframe()

        unique_obs_cols = ["time", "x", "y", "observation"]
        df = df.set_index(unique_obs_cols)
        unique_obs_values = df[~df.duplicated()].obs_val.values

        data = {"Observation": unique_obs_values}
        for model in df.model.unique():
            df_model = df[df.model == model]
            data[model] = df_model.mod_val.values

        data = {k: pd.Series(v) for k, v in data.items()}
        df = pd.DataFrame(data)

        if "grid" not in kwargs:
            kwargs["grid"] = True

        ax = df.plot.box(ax=ax, **kwargs)

        ax.set_ylabel(f"{self.cc._unit_text}")

        title = (
            _default_univarate_title("Box plot", self.cc) if title is None else title
        )
        ax.set_title(title)

        if self.is_directional:
            _ytick_directional(ax)

        return ax

box

box(*, ax=None, figsize=None, title=None, **kwargs)

Plot box plot of observations and model data.

Parameters:

Name	Type	Description	Default
ax	Axes	matplotlib axes, by default None	None
figsize	tuple	width and height of the figure, by default None	None
title	str	plot title, by default None	None
**kwargs		passed to pandas.DataFrame.plot.box()	{}

Returns:

Type	Description
Axes	matplotlib axes

Examples:

>>> cc.plot.box()
>>> cc.plot.box(showmeans=True)
>>> cc.plot.box(ax=ax, title="Box plot")

Source code in modelskill/comparison/_collection_plotter.py

def box(self, *, ax=None, figsize=None, title=None, **kwargs) -> Axes:
    """Plot box plot of observations and model data.

    Parameters
    ----------
    ax : Axes, optional
        matplotlib axes, by default None
    figsize : tuple, optional
        width and height of the figure, by default None
    title : str, optional
        plot title, by default None
    **kwargs
        passed to pandas.DataFrame.plot.box()

    Returns
    -------
    Axes
        matplotlib axes

    Examples
    --------
    >>> cc.plot.box()
    >>> cc.plot.box(showmeans=True)
    >>> cc.plot.box(ax=ax, title="Box plot")
    """
    _, ax = _get_fig_ax(ax, figsize)

    df = self.cc._to_long_dataframe()

    unique_obs_cols = ["time", "x", "y", "observation"]
    df = df.set_index(unique_obs_cols)
    unique_obs_values = df[~df.duplicated()].obs_val.values

    data = {"Observation": unique_obs_values}
    for model in df.model.unique():
        df_model = df[df.model == model]
        data[model] = df_model.mod_val.values

    data = {k: pd.Series(v) for k, v in data.items()}
    df = pd.DataFrame(data)

    if "grid" not in kwargs:
        kwargs["grid"] = True

    ax = df.plot.box(ax=ax, **kwargs)

    ax.set_ylabel(f"{self.cc._unit_text}")

    title = (
        _default_univarate_title("Box plot", self.cc) if title is None else title
    )
    ax.set_title(title)

    if self.is_directional:
        _ytick_directional(ax)

    return ax

hist

hist(bins=100, *, model=None, title=None, density=True, alpha=0.5, ax=None, figsize=None, **kwargs)

Plot histogram of specific model and all observations.

Wraps pandas.DataFrame hist() method.

Parameters:

Name	Type	Description	Default
bins	int	number of bins, by default 100	100
title	str	plot title, default: observation name	None
density	bool	If True, draw and return a probability density, by default True	True
alpha	float	alpha transparency fraction, by default 0.5	0.5
ax	matplotlib axes	axes to plot on, by default None	None
figsize	tuple	width and height of the figure, by default None	None
**kwargs		other keyword arguments to df.hist()	{}

Returns:

Type	Description
matplotlib axes

Examples:

>>> cc.plot.hist()
>>> cc.plot.hist(bins=100)

See also

pandas.Series.hist matplotlib.axes.Axes.hist

Source code in modelskill/comparison/_collection_plotter.py

def hist(
    self,
    bins: int | Sequence = 100,
    *,
    model: str | int | None = None,
    title: Optional[str] = None,
    density: bool = True,
    alpha: float = 0.5,
    ax=None,
    figsize: Optional[Tuple[float, float]] = None,
    **kwargs,
):
    """Plot histogram of specific model and all observations.

    Wraps pandas.DataFrame hist() method.

    Parameters
    ----------
    bins : int, optional
        number of bins, by default 100
    title : str, optional
        plot title, default: observation name
    density: bool, optional
        If True, draw and return a probability density, by default True
    alpha : float, optional
        alpha transparency fraction, by default 0.5
    ax : matplotlib axes, optional
        axes to plot on, by default None
    figsize : tuple, optional
        width and height of the figure, by default None
    **kwargs
        other keyword arguments to df.hist()

    Returns
    -------
    matplotlib axes

    Examples
    --------
    >>> cc.plot.hist()
    >>> cc.plot.hist(bins=100)

    See also
    --------
    pandas.Series.hist
    matplotlib.axes.Axes.hist
    """
    if model is None:
        mod_names = self.cc.mod_names
    else:
        warnings.warn(
            "The 'model' keyword is deprecated! Instead, filter comparer before plotting cmp.sel(model=...).plot.hist()",
            FutureWarning,
        )
        model_list = [model] if isinstance(model, (str, int)) else model
        mod_names = [
            self.cc.mod_names[_get_idx(m, self.cc.mod_names)] for m in model_list
        ]

    axes = []
    for mod_name in mod_names:
        ax_mod = self._hist_one_model(
            mod_name=mod_name,
            bins=bins,
            title=title,
            density=density,
            alpha=alpha,
            ax=ax,
            figsize=figsize,
            **kwargs,
        )
        axes.append(ax_mod)
    return axes[0] if len(axes) == 1 else axes

kde

kde(*, ax=None, figsize=None, title=None, **kwargs)

Plot kernel density estimate of observation and model data.

Parameters:

Name	Type	Description	Default
ax	Axes	matplotlib axes, by default None	None
figsize	tuple	width and height of the figure, by default None	None
title	str	plot title, by default None	None
**kwargs		passed to pandas.DataFrame.plot.kde()	{}

Returns:

Type	Description
Axes	matplotlib axes

Examples:

>>> cc.plot.kde()
>>> cc.plot.kde(bw_method=0.5)
>>> cc.plot.kde(bw_method='silverman')

Source code in modelskill/comparison/_collection_plotter.py

def kde(self, *, ax=None, figsize=None, title=None, **kwargs) -> Axes:
    """Plot kernel density estimate of observation and model data.

    Parameters
    ----------
    ax : Axes, optional
        matplotlib axes, by default None
    figsize : tuple, optional
        width and height of the figure, by default None
    title : str, optional
        plot title, by default None
    **kwargs
        passed to pandas.DataFrame.plot.kde()

    Returns
    -------
    Axes
        matplotlib axes

    Examples
    --------
    >>> cc.plot.kde()
    >>> cc.plot.kde(bw_method=0.5)
    >>> cc.plot.kde(bw_method='silverman')

    """
    _, ax = _get_fig_ax(ax, figsize)

    df = self.cc._to_long_dataframe()
    ax = df.obs_val.plot.kde(
        ax=ax, linestyle="dashed", label="Observation", **kwargs
    )

    for model in self.cc.mod_names:
        df_model = df[df.model == model]
        df_model.mod_val.plot.kde(ax=ax, label=model, **kwargs)

    ax.set_xlabel(f"{self.cc._unit_text}")

    title = (
        _default_univarate_title("Density plot", self.cc)
        if title is None
        else title
    )
    ax.set_title(title)
    ax.legend()

    # remove y-axis, ticks and label
    ax.yaxis.set_visible(False)
    ax.tick_params(axis="y", which="both", length=0)
    ax.set_ylabel("")

    # remove box around plot
    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)
    ax.spines["left"].set_visible(False)

    if self.is_directional:
        _xtick_directional(ax)

    return ax

scatter

scatter(*, model=None, bins=120, quantiles=None, fit_to_quantiles=False, show_points=None, show_hist=None, show_density=None, norm=None, backend='matplotlib', figsize=(8, 8), xlim=None, ylim=None, reg_method='ols', title=None, xlabel=None, ylabel=None, skill_table=None, ax=None, **kwargs)

Scatter plot showing compared data: observation vs modelled Optionally, with density histogram.

Parameters:

Name	Type	Description	Default
bins	int | float	bins for the 2D histogram on the background. By default 20 bins. if int, represents the number of bins of 2D if float, represents the bin size if sequence (list of int or float), represents the bin edges	120
quantiles	int | Sequence[float] | None	number of quantiles for QQ-plot, by default None and will depend on the scatter data length (10, 100 or 1000); if int, this is the number of points; if sequence (list of floats), represents the desired quantiles (from 0 to 1)	None
fit_to_quantiles	bool	by default the regression line is fitted to all data, if True, it is fitted to the quantiles which can be useful to represent the extremes of the distribution, by default False	False
show_points	(bool, int, float)	Should the scatter points be displayed? None means: show all points if fewer than 1e4, otherwise show 1e4 sample points, by default None. float: fraction of points to show on plot from 0 to 1. e.g. 0.5 shows 50% of the points. int: if 'n' (int) given, then 'n' points will be displayed, randomly selected	None
show_hist	bool	show the data density as a a 2d histogram, by default None	None
show_density	Optional[bool]	show the data density as a colormap of the scatter, by default None. If both show_density and show_hist are None, then show_density is used by default. For binning the data, the kword bins=Float is used.	None
norm	matplotlib.colors norm	colormap normalization. If None, defaults to matplotlib.colors.PowerNorm(vmin=1, gamma=0.5)	None
backend	str	use "plotly" (interactive) or "matplotlib" backend, by default "matplotlib"	'matplotlib'
figsize	tuple	width and height of the figure, by default (8, 8)	(8, 8)
xlim	tuple	plot range for the observation (xmin, xmax), by default None	None
ylim	tuple	plot range for the model (ymin, ymax), by default None	None
reg_method	str or bool	method for determining the regression line "ols" : ordinary least squares regression "odr" : orthogonal distance regression, False : no regression line, by default "ols"	'ols'
title	str	plot title, by default None	None
xlabel	str	x-label text on plot, by default None	None
ylabel	str	y-label text on plot, by default None	None
skill_table	(str, List[str], bool)	list of modelskill.metrics or boolean, if True then by default modelskill.options.metrics.list. This kword adds a box at the right of the scatter plot, by default False	None
ax	matplotlib axes	axes to plot on, by default None	None
**kwargs		other keyword arguments to matplotlib.pyplot.scatter()	{}

Examples:

>>> cc.plot.scatter()
>>> cc.plot.scatter(bins=0.2, backend='plotly')
>>> cc.plot.scatter(show_points=False, title='no points')
>>> cc.plot.scatter(xlabel='all observations', ylabel='my model')
>>> cc.sel(model='HKZN_v2').plot.scatter(figsize=(10, 10))
>>> cc.sel(observations=['c2','HKNA']).plot.scatter()

Source code in modelskill/comparison/_collection_plotter.py

def scatter(
    self,
    *,
    model=None,
    bins: int | float = 120,
    quantiles: int | Sequence[float] | None = None,
    fit_to_quantiles: bool = False,
    show_points: bool | int | float | None = None,
    show_hist: Optional[bool] = None,
    show_density: Optional[bool] = None,
    norm: Optional[colors.Normalize] = None,
    backend: Literal["matplotlib", "plotly"] = "matplotlib",
    figsize: Tuple[float, float] = (8, 8),
    xlim: Optional[Tuple[float, float]] = None,
    ylim: Optional[Tuple[float, float]] = None,
    reg_method: str | bool = "ols",
    title: Optional[str] = None,
    xlabel: Optional[str] = None,
    ylabel: Optional[str] = None,
    skill_table: Optional[Union[str, List[str], bool]] = None,
    ax: Optional[Axes] = None,
    **kwargs,
) -> Axes | list[Axes]:
    """Scatter plot showing compared data: observation vs modelled
    Optionally, with density histogram.

    Parameters
    ----------
    bins: (int, float, sequence), optional
        bins for the 2D histogram on the background. By default 20 bins.
        if int, represents the number of bins of 2D
        if float, represents the bin size
        if sequence (list of int or float), represents the bin edges
    quantiles: (int, sequence), optional
        number of quantiles for QQ-plot, by default None and will depend
        on the scatter data length (10, 100 or 1000); if int, this is
        the number of points; if sequence (list of floats), represents
        the desired quantiles (from 0 to 1)
    fit_to_quantiles: bool, optional, by default False
        by default the regression line is fitted to all data, if True,
        it is fitted to the quantiles which can be useful to represent
        the extremes of the distribution, by default False
    show_points : (bool, int, float), optional
        Should the scatter points be displayed? None means: show all
        points if fewer than 1e4, otherwise show 1e4 sample points,
        by default None. float: fraction of points to show on plot
        from 0 to 1. e.g. 0.5 shows 50% of the points. int: if 'n' (int)
        given, then 'n' points will be displayed, randomly selected
    show_hist : bool, optional
        show the data density as a a 2d histogram, by default None
    show_density: bool, optional
        show the data density as a colormap of the scatter, by default
        None. If both `show_density` and `show_hist` are None, then
        `show_density` is used by default. For binning the data, the
        kword `bins=Float` is used.
    norm : matplotlib.colors norm
        colormap normalization. If None, defaults to
        matplotlib.colors.PowerNorm(vmin=1, gamma=0.5)
    backend : str, optional
        use "plotly" (interactive) or "matplotlib" backend,
        by default "matplotlib"
    figsize : tuple, optional
        width and height of the figure, by default (8, 8)
    xlim : tuple, optional
        plot range for the observation (xmin, xmax), by default None
    ylim : tuple, optional
        plot range for the model (ymin, ymax), by default None
    reg_method : str or bool, optional
        method for determining the regression line
        "ols" : ordinary least squares regression
        "odr" : orthogonal distance regression,
        False : no regression line,
        by default "ols"
    title : str, optional
        plot title, by default None
    xlabel : str, optional
        x-label text on plot, by default None
    ylabel : str, optional
        y-label text on plot, by default None
    skill_table : str, List[str], bool, optional
        list of modelskill.metrics or boolean, if True then by default modelskill.options.metrics.list.
        This kword adds a box at the right of the scatter plot,
        by default False
    ax : matplotlib axes, optional
        axes to plot on, by default None
    **kwargs
        other keyword arguments to matplotlib.pyplot.scatter()

    Examples
    ------
    >>> cc.plot.scatter()
    >>> cc.plot.scatter(bins=0.2, backend='plotly')
    >>> cc.plot.scatter(show_points=False, title='no points')
    >>> cc.plot.scatter(xlabel='all observations', ylabel='my model')
    >>> cc.sel(model='HKZN_v2').plot.scatter(figsize=(10, 10))
    >>> cc.sel(observations=['c2','HKNA']).plot.scatter()
    """

    cc = self.cc
    if model is None:
        mod_names = cc.mod_names
    else:
        warnings.warn(
            "The 'model' keyword is deprecated! Instead, filter comparer before plotting cmp.sel(model=...).plot.scatter()",
            FutureWarning,
        )

        model_list = [model] if isinstance(model, (str, int)) else model
        mod_names = [
            self.cc.mod_names[_get_idx(m, self.cc.mod_names)] for m in model_list
        ]

    axes = []
    for mod_name in mod_names:
        ax_mod = self._scatter_one_model(
            mod_name=mod_name,
            bins=bins,
            quantiles=quantiles,
            fit_to_quantiles=fit_to_quantiles,
            show_points=show_points,
            show_hist=show_hist,
            show_density=show_density,
            norm=norm,
            backend=backend,
            figsize=figsize,
            xlim=xlim,
            ylim=ylim,
            reg_method=reg_method,
            title=title,
            xlabel=xlabel,
            ylabel=ylabel,
            skill_table=skill_table,
            ax=ax,
            **kwargs,
        )
        axes.append(ax_mod)
    return axes[0] if len(axes) == 1 else axes

taylor

taylor(*, normalize_std=False, aggregate_observations=True, figsize=(7, 7), marker='o', marker_size=6.0, title='Taylor diagram')

Taylor diagram showing model std and correlation to observation in a single-quadrant polar plot, with r=std and theta=arccos(cc).

Parameters:

Name	Type	Description	Default
normalize_std	bool	plot model std normalized with observation std, default False	False
aggregate_observations	bool	should multiple observations be aggregated before plotting (or shown individually), default True	True
figsize	tuple	width and height of the figure (should be square), by default (7, 7)	(7, 7)
marker	str	marker type e.g. "x", "*", by default "o"	'o'
marker_size	float	size of the marker, by default 6	6.0
title	str	title of the plot, by default "Taylor diagram"	'Taylor diagram'

Returns:

Type	Description
Figure

Examples:

>>> cc.plot.taylor()
>>> cc.plot.taylor(observation="c2")
>>> cc.plot.taylor(start="2017-10-28", figsize=(5,5))

References

Copin, Y. (2018). https://gist.github.com/ycopin/3342888, Yannick Copin yannick.copin@laposte.net

Source code in modelskill/comparison/_collection_plotter.py

def taylor(
    self,
    *,
    normalize_std: bool = False,
    aggregate_observations: bool = True,
    figsize: Tuple[float, float] = (7, 7),
    marker: str = "o",
    marker_size: float = 6.0,
    title: str = "Taylor diagram",
):
    """Taylor diagram showing model std and correlation to observation
    in a single-quadrant polar plot, with r=std and theta=arccos(cc).

    Parameters
    ----------
    normalize_std : bool, optional
        plot model std normalized with observation std, default False
    aggregate_observations : bool, optional
        should multiple observations be aggregated before plotting
        (or shown individually), default True
    figsize : tuple, optional
        width and height of the figure (should be square), by default (7, 7)
    marker : str, optional
        marker type e.g. "x", "*", by default "o"
    marker_size : float, optional
        size of the marker, by default 6
    title : str, optional
        title of the plot, by default "Taylor diagram"

    Returns
    -------
    matplotlib.figure.Figure

    Examples
    ------
    >>> cc.plot.taylor()
    >>> cc.plot.taylor(observation="c2")
    >>> cc.plot.taylor(start="2017-10-28", figsize=(5,5))

    References
    ----------
    Copin, Y. (2018). https://gist.github.com/ycopin/3342888, Yannick Copin <yannick.copin@laposte.net>
    """

    if (not aggregate_observations) and (not normalize_std):
        raise ValueError(
            "aggregate_observations=False is only possible if normalize_std=True!"
        )

    metrics = [mtr._std_obs, mtr._std_mod, mtr.cc]
    skill_func = self.cc.mean_skill if aggregate_observations else self.cc.skill
    sk = skill_func(
        metrics=metrics,  # type: ignore
    )
    if sk is None:
        return

    df = sk.to_dataframe()
    ref_std = 1.0 if normalize_std else df.iloc[0]["_std_obs"]

    if isinstance(df.index, pd.MultiIndex):
        df.index = df.index.map("_".join)

    df = df[["_std_obs", "_std_mod", "cc"]].copy()
    df.columns = ["obs_std", "std", "cc"]
    pts = [
        TaylorPoint(
            r.Index, r.obs_std, r.std, r.cc, marker=marker, marker_size=marker_size
        )
        for r in df.itertuples()
    ]

    return taylor_diagram(
        obs_std=ref_std,
        points=pts,
        figsize=figsize,
        normalize_std=normalize_std,
        title=title,
    )