|
| 1 | +import pathlib |
| 2 | + |
| 3 | +from attrs import field, frozen |
| 4 | +from cattrs import Converter, transform_error |
| 5 | +from loguru import logger |
| 6 | +from ruamel.yaml import YAML |
| 7 | + |
| 8 | +from cmip_ref_core.exceptions import ResultValidationError |
| 9 | +from cmip_ref_core.pycmec.metric import CMECMetric |
| 10 | + |
| 11 | +yaml = YAML() |
| 12 | + |
| 13 | + |
| 14 | +@frozen |
| 15 | +class DimensionValue: |
| 16 | + """ |
| 17 | + An allowed value for a dimension |
| 18 | + """ |
| 19 | + |
| 20 | + name: str |
| 21 | + long_name: str |
| 22 | + description: str | None |
| 23 | + units: str |
| 24 | + |
| 25 | + |
| 26 | +@frozen |
| 27 | +class Dimension: |
| 28 | + """ |
| 29 | + Description of a dimension in a metric bundle |
| 30 | +
|
| 31 | + This information is also used by the frontend for presentation purposes. |
| 32 | + """ |
| 33 | + |
| 34 | + name: str |
| 35 | + """ |
| 36 | + A short idenfifier of the dimension. |
| 37 | +
|
| 38 | + This is used as a key in the metric bundle. |
| 39 | + """ |
| 40 | + long_name: str |
| 41 | + """ |
| 42 | + A longer name used for presentation |
| 43 | + """ |
| 44 | + description: str |
| 45 | + """ |
| 46 | + A short description of the dimension. |
| 47 | +
|
| 48 | + This is used for presentation |
| 49 | + """ |
| 50 | + allow_extra_values: bool |
| 51 | + """ |
| 52 | + If True, additional non-controlled values are allowed. |
| 53 | + This is used for dimensions where not all the values are known at run time,' |
| 54 | + for example, the model dimension. |
| 55 | + """ |
| 56 | + required: bool |
| 57 | + """ |
| 58 | + If True, this dimension is required to be specified in the results. |
| 59 | + """ |
| 60 | + values: list[DimensionValue] = field(factory=list) |
| 61 | + """ |
| 62 | + The list of controlled values for a given dimension. |
| 63 | +
|
| 64 | + If `allow_extra_values` is False, |
| 65 | + then only these values are valid for the dimension. |
| 66 | + """ |
| 67 | + |
| 68 | + |
| 69 | +@frozen |
| 70 | +class CV: |
| 71 | + """ |
| 72 | + A collection of controlled dimensions and values used to validate results. |
| 73 | +
|
| 74 | + A metric bundle does not have to specify all dimensions, |
| 75 | + but any dimensions not in the CV are not permitted. |
| 76 | + """ |
| 77 | + |
| 78 | + # TODO: There might be some additional fields in future if this CV is project-specific |
| 79 | + |
| 80 | + dimensions: list[Dimension] |
| 81 | + |
| 82 | + def get_dimension_by_name(self, name: str) -> Dimension: |
| 83 | + """ |
| 84 | + Get a dimension by name |
| 85 | +
|
| 86 | + Parameters |
| 87 | + ---------- |
| 88 | + name |
| 89 | + The name of the dimension |
| 90 | +
|
| 91 | + Returns |
| 92 | + ------- |
| 93 | + Dimension |
| 94 | + The dimension with the given name |
| 95 | +
|
| 96 | + Raises |
| 97 | + ------ |
| 98 | + KeyError |
| 99 | + If the dimension is not found |
| 100 | + """ |
| 101 | + for dim in self.dimensions: |
| 102 | + if dim.name == name: |
| 103 | + return dim |
| 104 | + raise KeyError(f"Dimension {name} not found") |
| 105 | + |
| 106 | + def validate_metrics(self, metric_bundle: CMECMetric) -> None: |
| 107 | + """ |
| 108 | + Validate a metric bundle against a CV |
| 109 | +
|
| 110 | + The CV describes the accepted dimensions and values within a bundle |
| 111 | +
|
| 112 | + Parameters |
| 113 | + ---------- |
| 114 | + metric_bundle |
| 115 | +
|
| 116 | + Raises |
| 117 | + ------ |
| 118 | + ResultValidationError |
| 119 | + If the validation of the dimensions or values fails |
| 120 | + """ |
| 121 | + for result in metric_bundle.iter_results(): |
| 122 | + for k, v in result.dimensions.items(): |
| 123 | + try: |
| 124 | + dimension = self.get_dimension_by_name(k) |
| 125 | + except KeyError: |
| 126 | + raise ResultValidationError(f"Unknown dimension: {k!r}") |
| 127 | + if not dimension.allow_extra_values: |
| 128 | + if v not in [dv.name for dv in dimension.values]: |
| 129 | + raise ResultValidationError(f"Unknown value {v!r} for dimension {k!r}") |
| 130 | + if not isinstance(result.value, float): # pragma: no cover |
| 131 | + # This may not be possible with the current CMECMetric implementation |
| 132 | + raise ResultValidationError(f"Unexpected value: {result.value!r}") |
| 133 | + |
| 134 | + @staticmethod |
| 135 | + def load_from_file(filename: pathlib.Path | str) -> "CV": |
| 136 | + """ |
| 137 | + Load a CV from disk |
| 138 | +
|
| 139 | + Returns |
| 140 | + ------- |
| 141 | + A new CV instance |
| 142 | +
|
| 143 | + """ |
| 144 | + convertor = Converter(forbid_extra_keys=True) |
| 145 | + contents = yaml.load(pathlib.Path(filename)) |
| 146 | + |
| 147 | + try: |
| 148 | + return convertor.structure(contents, CV) |
| 149 | + except Exception as exc: |
| 150 | + logger.error(f"Error loading CV from {filename}") |
| 151 | + for error in transform_error(exc): |
| 152 | + logger.error(error) |
| 153 | + raise |
0 commit comments