Skip to content

Commit 53cb4df

Browse files
lewisjaredlewisjared
committed
chore: udpates from feedback
1 parent 987d77a commit 53cb4df

1 file changed

Lines changed: 100 additions & 32 deletions

File tree

‎notebooks/01-ref-concepts.ipynb‎

Lines changed: 100 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -28,16 +28,29 @@
2828
"\n",
2929
"The public deployment currently evaluates CMIP6 dataset, but will include CMIP7 Assessment Fast Track data\n",
3030
"as they become available.\n",
31-
"Results are served from a website (<https://dashboard.climate-ref.org>) and a public API (<https://api.climate-ref.org>).\n",
3231
"\n",
33-
"Throughout these notebooks we talk to the API via an \"SDK\".\n",
34-
"This SDK allows us to make requests to the API without having to directly make HTTP requests.\n",
35-
"The `ref_tutorials` helper package (shipped with this repository) builds the API client for us."
32+
"The REF has a dashboard (<https://dashboard.climate-ref.org>) which offers a curated view of the results from the REF. \n",
33+
"This dashboard uses an API (<https://api.climate-ref.org>) to provide access to the results in a structured way.\n",
34+
"\n",
35+
"We can use this same API to make our own view of the data. As part of the API we also publish a [schema](https://api.climate-ref.org/docs) that describes the different endpoints that can be queried and the shape of the response"
36+
]
37+
},
38+
{
39+
"cell_type": "markdown",
40+
"id": "1df88e89",
41+
"metadata": {},
42+
"source": [
43+
"Throughout these notebooks we talk to the API via an \"SDK\" which is a small software package generated from the schema of the API.\n",
44+
"This SDK allows us to make requests to the API as function calls without having to directly make HTTP requests.\n",
45+
"\n",
46+
"A small script `scripts/generate_client.sh` shows how to built the SDK.\n",
47+
"\n",
48+
"> If you are runnning this on Binder, this has been pre-built for you."
3649
]
3750
},
3851
{
3952
"cell_type": "code",
40-
"execution_count": 2,
53+
"execution_count": 7,
4154
"id": "05ac27ad",
4255
"metadata": {},
4356
"outputs": [
@@ -47,7 +60,7 @@
4760
"Client(raise_on_unexpected_status=False, _base_url='https://api.climate-ref.org', _cookies={}, _headers={}, _timeout=None, _verify_ssl=True, _follow_redirects=False, _httpx_args={}, _client=None, _async_client=None)"
4861
]
4962
},
50-
"execution_count": 2,
63+
"execution_count": 7,
5164
"metadata": {},
5265
"output_type": "execute_result"
5366
}
@@ -59,6 +72,17 @@
5972
"client"
6073
]
6174
},
75+
{
76+
"cell_type": "markdown",
77+
"id": "871f914b",
78+
"metadata": {},
79+
"source": [
80+
"## Datasets\n",
81+
"\n",
82+
"Datasets containing CMORised climate model output, and the reference data it is compared to are a key input to the REF.\n",
83+
"The REF tracks which datasets are available and which diagnostics have already been run."
84+
]
85+
},
6286
{
6387
"cell_type": "markdown",
6488
"id": "19c3c017",
@@ -74,15 +98,15 @@
7498
},
7599
{
76100
"cell_type": "code",
77-
"execution_count": 3,
101+
"execution_count": 8,
78102
"id": "8196f36e",
79103
"metadata": {},
80104
"outputs": [
81105
{
82106
"name": "stdout",
83107
"output_type": "stream",
84108
"text": [
85-
"47 diagnostics available\n",
109+
"47 diagnostics available. Showing the first 10:\n",
86110
"\n",
87111
" annual-cycle Annual Cycle Analysis\n",
88112
" sea-ice-area-basic Arctic and Antarctic Sea Ice Area Seasonal Cycle\n",
@@ -101,7 +125,7 @@
101125
"from climate_ref_client.api.diagnostics import diagnostics_list\n",
102126
"\n",
103127
"diagnostics = diagnostics_list.sync(client=client).data\n",
104-
"print(f\"{len(diagnostics)} diagnostics available\\n\")\n",
128+
"print(f\"{len(diagnostics)} diagnostics available. Showing the first 10:\\n\")\n",
105129
"for diagnostic in sorted(diagnostics, key=lambda d: d.name)[:10]:\n",
106130
" print(f\" {diagnostic.slug:35s} {diagnostic.name}\")"
107131
]
@@ -117,7 +141,7 @@
117141
},
118142
{
119143
"cell_type": "code",
120-
"execution_count": 4,
144+
"execution_count": 9,
121145
"id": "3389ca04",
122146
"metadata": {},
123147
"outputs": [
@@ -161,7 +185,7 @@
161185
},
162186
{
163187
"cell_type": "code",
164-
"execution_count": 5,
188+
"execution_count": 10,
165189
"id": "45bfc188",
166190
"metadata": {},
167191
"outputs": [
@@ -184,53 +208,97 @@
184208
},
185209
{
186210
"cell_type": "markdown",
187-
"id": "871f914b",
211+
"id": "be0528dc",
188212
"metadata": {},
189213
"source": [
190-
"## Datasets\n",
214+
"## Execution groups and Executions\n",
215+
"\n",
216+
"An **execution** is one run of a diagnostic against one specific group of datasets.\n",
217+
"This execution has information about the datasets that were used to run it, the diagnostic and the outputs.\n",
191218
"\n",
192-
"A diagnostic needs **datasets** to run against: the climate model output under evaluation, and the reference data it is compared to.\n",
193-
"The REF tracks which datasets are available and which diagnostics have already been run.\n",
219+
"A single diagnostic is typically executed many times on different sets of data.\n",
220+
"This generally depends what is being calculated, but this is often once per model variant.\n",
221+
"Each of these subsets is an *execution group*.\n",
194222
"\n",
195-
"For the public API we do not handle raw CMIP6 datasets directly the evaluations have already\n",
196-
"been run. We will see locally fetched datasets in notebook 04."
223+
"Each execution group has a unique key that describes it.\n",
224+
"If any datasets in an execution group change, then a new execution is performed.\n",
225+
"\n",
226+
"We can list the execution groups available for the Global Warming Level diagnostic:"
197227
]
198228
},
199229
{
200-
"cell_type": "markdown",
201-
"id": "be0528dc",
230+
"cell_type": "code",
231+
"execution_count": 11,
232+
"id": "fda2000d",
202233
"metadata": {},
234+
"outputs": [
235+
{
236+
"name": "stdout",
237+
"output_type": "stream",
238+
"text": [
239+
"Diagnostic: Climate at Global Warming Levels\n",
240+
"Execution groups: 4\n",
241+
"Execution group keys: ['cmip6_ssp126', 'cmip6_ssp245', 'cmip6_ssp370', 'cmip6_ssp585']\n"
242+
]
243+
}
244+
],
203245
"source": [
204-
"## Executions\n",
246+
"from climate_ref_client.api.diagnostics import diagnostics_list_execution_groups\n",
205247
"\n",
206-
"An **execution** is one run of a diagnostic against one specific group of datasets.\n",
248+
"execution_groups = diagnostics_list_execution_groups.sync(\n",
249+
" client=client, provider_slug=example.provider.slug, diagnostic_slug=example.slug\n",
250+
").data\n",
207251
"\n",
208-
"A single diagnostic is typically executed many times. This generally depends what is being calculated, but this is often once per model variant.\n",
209-
"Each of these individual groups is an *execution group*.\n",
210-
"If any datasets in an execution group change, then a new execution is performed.\n",
252+
"first_execution_group = execution_groups[0]\n",
211253
"\n",
212-
"Here are the execution groups of one diagnostic:"
254+
"print(f\"Diagnostic: {example.name}\")\n",
255+
"print(f\"Execution groups: {len(execution_groups)}\")\n",
256+
"print(f\"Execution group keys: {[eg.key for eg in execution_groups]}\")"
257+
]
258+
},
259+
{
260+
"cell_type": "markdown",
261+
"id": "dce894b0",
262+
"metadata": {},
263+
"source": [
264+
"Within each execution group, there may be multiple executions.\n",
265+
"For this execution we can access the outputs that were generated as well as a URL for downloading them."
213266
]
214267
},
215268
{
216269
"cell_type": "code",
217-
"execution_count": 6,
218-
"id": "e06e64b8",
270+
"execution_count": 12,
271+
"id": "c0e32afa",
219272
"metadata": {},
220273
"outputs": [
221274
{
222275
"name": "stdout",
223276
"output_type": "stream",
224277
"text": [
225-
"Diagnostic: Climate at Global Warming Levels\n",
226-
"Execution groups: 4\n"
278+
" executions/recipe_20260305_234552/plots/gwl_mean_plots_pr/plot_gwl_stats/CMIP6_mm_mean_1.5.png https://api.climate-ref.org/api/v1/results/267670\n",
279+
" executions/recipe_20260305_234552/plots/gwl_mean_plots_pr/plot_gwl_stats/CMIP6_mm_mean_2.0.png https://api.climate-ref.org/api/v1/results/267671\n",
280+
" executions/recipe_20260305_234552/plots/gwl_mean_plots_pr/plot_gwl_stats/CMIP6_mm_stdev_1.5.png https://api.climate-ref.org/api/v1/results/267672\n",
281+
" executions/recipe_20260305_234552/plots/gwl_mean_plots_pr/plot_gwl_stats/CMIP6_mm_stdev_2.0.png https://api.climate-ref.org/api/v1/results/267673\n",
282+
" executions/recipe_20260305_234552/plots/gwl_mean_plots_tas/plot_gwl_stats/CMIP6_mm_mean_1.5.png https://api.climate-ref.org/api/v1/results/267674\n",
283+
" executions/recipe_20260305_234552/plots/gwl_mean_plots_tas/plot_gwl_stats/CMIP6_mm_mean_2.0.png https://api.climate-ref.org/api/v1/results/267675\n",
284+
" executions/recipe_20260305_234552/plots/gwl_mean_plots_tas/plot_gwl_stats/CMIP6_mm_stdev_1.5.png https://api.climate-ref.org/api/v1/results/267676\n",
285+
" executions/recipe_20260305_234552/plots/gwl_mean_plots_tas/plot_gwl_stats/CMIP6_mm_stdev_2.0.png https://api.climate-ref.org/api/v1/results/267677\n",
286+
" executions/recipe_20260305_234552/work/calculate_gwl_exceedance_years/gwl_exceedance_calculation/GWL_exceedance_years.csv https://api.climate-ref.org/api/v1/results/267678\n",
287+
" executions/recipe_20260305_234552/work/gwl_mean_plots_pr/plot_gwl_stats/CMIP6_mm_mean_1.5.nc https://api.climate-ref.org/api/v1/results/267679\n",
288+
" executions/recipe_20260305_234552/work/gwl_mean_plots_pr/plot_gwl_stats/CMIP6_mm_mean_2.0.nc https://api.climate-ref.org/api/v1/results/267680\n",
289+
" executions/recipe_20260305_234552/work/gwl_mean_plots_pr/plot_gwl_stats/CMIP6_mm_stdev_1.5.nc https://api.climate-ref.org/api/v1/results/267681\n",
290+
" executions/recipe_20260305_234552/work/gwl_mean_plots_pr/plot_gwl_stats/CMIP6_mm_stdev_2.0.nc https://api.climate-ref.org/api/v1/results/267682\n",
291+
" executions/recipe_20260305_234552/work/gwl_mean_plots_tas/plot_gwl_stats/CMIP6_mm_mean_1.5.nc https://api.climate-ref.org/api/v1/results/267683\n",
292+
" executions/recipe_20260305_234552/work/gwl_mean_plots_tas/plot_gwl_stats/CMIP6_mm_mean_2.0.nc https://api.climate-ref.org/api/v1/results/267684\n",
293+
" executions/recipe_20260305_234552/work/gwl_mean_plots_tas/plot_gwl_stats/CMIP6_mm_stdev_1.5.nc https://api.climate-ref.org/api/v1/results/267685\n",
294+
" executions/recipe_20260305_234552/work/gwl_mean_plots_tas/plot_gwl_stats/CMIP6_mm_stdev_2.0.nc https://api.climate-ref.org/api/v1/results/267686\n",
295+
" executions/recipe_20260305_234552/index.html https://api.climate-ref.org/api/v1/results/267687\n"
227296
]
228297
}
229298
],
230299
"source": [
231-
"with_executions = next(d for d in diagnostics if d.execution_groups)\n",
232-
"print(f\"Diagnostic: {with_executions.name}\")\n",
233-
"print(f\"Execution groups: {len(with_executions.execution_groups)}\")"
300+
"for o in first_execution_group.latest_execution.outputs:\n",
301+
" print(f\" {o.filename:20s} {o.url}\")"
234302
]
235303
},
236304
{

0 commit comments

Comments
 (0)