diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index 27ddd7eb..bb8364d9 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -63,6 +63,8 @@ source priorities and matching algorithms. csg.StrategyUnableToProcess csg.SubstitutionStrategy csg.compose + csg.create_composite_source + csg.set_priority_coords .. currentmodule:: xarray @@ -96,6 +98,7 @@ Methods DataArray.pr.add_aggregates_coordinates DataArray.pr.any DataArray.pr.combine_first + DataArray.pr.convert DataArray.pr.convert_to_gwp DataArray.pr.convert_to_gwp_like DataArray.pr.convert_to_mass diff --git a/docs/source/usage/csg.md b/docs/source/usage/csg.md index e101c504..f38206c0 100644 --- a/docs/source/usage/csg.md +++ b/docs/source/usage/csg.md @@ -30,6 +30,8 @@ When no missing information is left in the result timeseries, the algorithm term It also terminates if all source timeseries are used, even if missing information is left. +## The `compose` function + The core function to use is the {py:func}`primap2.csg.compose` function. It needs the following input: @@ -111,8 +113,7 @@ priority_definition = primap2.csg.PriorityDefinition( ``` ```{code-cell} ipython3 -# Currently, there is only one strategy implemented, so we use -# the empty selector {}, which matches everything, to configure +# We use the empty selector {}, which matches everything, to configure # to use the substitution strategy for all timeseries. strategy_definition = primap2.csg.StrategyDefinition( strategies=[({}, primap2.csg.SubstitutionStrategy())] @@ -125,6 +126,7 @@ result_ds = primap2.csg.compose( priority_definition=priority_definition, strategy_definition=strategy_definition, progress_bar=None, # The animated progress bar is useless in the generated documentation + ) result_ds @@ -162,3 +164,62 @@ category 1 "lowpop" was preferred. For category 0, the initial timeseries did not contain NaNs, so no filling was needed. For category 1, there was information missing in the initial timeseries, so the lower-priority timeseries was used to fill the holes. + +## The `create_composite_source` wrapper function + +The {py:func}`primap2.csg.compose` function creates a composite time series according to +the given priorities and strategies, but it does not take care of pre- and postprocessing +of the data. It will carry along unnecessary data and the resulting dataset will miss the +priority coordinates. The {py:func}`primap2.csg.create_composite_source` function takes acre +of these steps and prepares the input data and completes the output data to a primap2 dataset +with all desired dimensions and metadata. + +The function takes the same inputs as {py:func}`primap2.csg.compose` with additional input to +define pre- and postprocessing: + +* **result_prio_coords** Defines the vales for the priority coordinates in the output dataset. As the +priority coordinates differ for all input sources there is no canonical vale +for the result and it has to be explicitly defined +* **metadata** Set metadata values such as title and references + +```{code-cell} ipython3 +result_prio_coords = result_prio_coords = { + "source": {"value": "PRIMAP-test"}, + "scenario": {"value": "HISTORY", "terminology": "PRIMAP"}, + } +metadata = {"references": "test-data", "contact": "test@example.xx"} + +``` + +* **limit_coords** Optional parameter to remove data for coordinate vales not needed for the +composition from the input data. The time coordinate is treated separately. +* **time_range** Optional parameter to limit the time coverage of the input data. Currently +only (year_from, year_to) is supported + + +```{code-cell} ipython3 +limit_coords = {'area (ISO3)': ['COL', 'ARG', 'MEX']} +time_range = ("2000", "2010") + +``` + +```{code-cell} ipython3 +complete_result_ds = primap2.csg.create_composite_source( + input_ds, + priority_definition=priority_definition, + strategy_definition=strategy_definition, + result_prio_coords=result_prio_coords, + limit_coords=limit_coords, + time_range=time_range, + metadata=metadata, + progress_bar=None, +) + +complete_result_ds +``` + + +## Filling strategies +Currently the following filling strategies are implemented +* Global least square matching: {py:func}`primap2.csg.GlobalLSStrategy` +* Straight substitution: {py:func}`primap2.csg.SubstitutionStrategy` diff --git a/primap2/csg/_wrapper.py b/primap2/csg/_wrapper.py index aebcc9c8..da6d4ce4 100644 --- a/primap2/csg/_wrapper.py +++ b/primap2/csg/_wrapper.py @@ -83,7 +83,7 @@ def create_composite_source( Optional parameter to limit the time coverage of the input data. Currently only (year_from, year_to) is supported metadata - Set metadata values such as author and references + Set metadata values such as title and references progress_bar By default, show progress bars using the tqdm package during the operation. If None, don't show any progress bars. You can supply a class