From 52bd84d0a95c772b3f208a9f52933ff572e8a5d0 Mon Sep 17 00:00:00 2001 From: juliettelavoie Date: Fri, 29 Sep 2023 12:21:32 -0400 Subject: [PATCH 1/4] add doc --- HISTORY.rst | 3 ++- xscen/extract.py | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/HISTORY.rst b/HISTORY.rst index 56c6c41b..c23cba17 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -4,7 +4,7 @@ History v0.8.0 (unreleased) ------------------- -Contributors to this version: Gabriel Rondeau-Genesse (:user:`RondeauG`), Pascal Bourgault (:user:`aulemahal`). +Contributors to this version: Gabriel Rondeau-Genesse (:user:`RondeauG`), Pascal Bourgault (:user:`aulemahal`), Juliette Lavoie (:user:`juliettelavoie`). Announcements ^^^^^^^^^^^^^ @@ -15,6 +15,7 @@ New features and enhancements * Added the ability to search for simulations that reach a given warming level. (:pull:`251`). * ``xs.spatial_mean`` now accepts the ``region="global"`` keyword to perform a global average (:issue:`94`, :pull:`260`). * ``xs.spatial_mean`` with ``method='xESMF'`` will also automatically segmentize polygons (down to a 1° resolution) to ensure a correct average (:pull:`260`). +* Added documentation for `require_all_on` in `search_data_catalogs`. (:pull:`263`). Breaking changes ^^^^^^^^^^^^^^^^ diff --git a/xscen/extract.py b/xscen/extract.py index c0eb00a6..21b48308 100644 --- a/xscen/extract.py +++ b/xscen/extract.py @@ -524,6 +524,8 @@ def search_data_catalogs( Variables and freqs to search for, following a 'variable: xr-freq-compatible-str' format. A list of strings can also be provided. other_search_criteria : dict, optional Other criteria to search for in the catalogs' columns, following a 'column_name: list(subset)' format. + You can also pass 'require_all_on: list(columns_name)' in order to only return results that respond to all other criteria across the listed columns. + More details available at https://intake-esm.readthedocs.io/en/stable/how-to/enforce-search-query-criteria-via-require-all-on.html . exclusions : dict, optional Same as other_search_criteria, but for eliminating results. match_hist_and_fut: bool, optional From ba05ff98e864199bb0cec528673e16bdac82abc8 Mon Sep 17 00:00:00 2001 From: juliettelavoie Date: Fri, 29 Sep 2023 12:42:22 -0400 Subject: [PATCH 2/4] add to catalog notebook --- docs/notebooks/1_catalog.ipynb | 57 +++++++++++++++++++++++++++++++--- 1 file changed, 53 insertions(+), 4 deletions(-) diff --git a/docs/notebooks/1_catalog.ipynb b/docs/notebooks/1_catalog.ipynb index 063b89ee..0aa00111 100644 --- a/docs/notebooks/1_catalog.ipynb +++ b/docs/notebooks/1_catalog.ipynb @@ -209,6 +209,55 @@ "print(DC.search(source=\"NorESM2.*\").unique(\"source\"))" ] }, + { + "cell_type": "markdown", + "id": "e2aad0d8", + "metadata": {}, + "source": [ + "Notice that the search fontion returns everything available that matchs some of the criteria." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a8fa0138", + "metadata": {}, + "outputs": [], + "source": [ + "# r1i1p1f1 sftlf is not available\n", + "DC.search(\n", + " source=\"NorESM2-MM\",\n", + " experiment=\"historical\",\n", + " member=[\"r1i1p1f1\", \"r2i1p1f1\"],\n", + " variable=[\"sftlf\", \"pr\"],\n", + ").df" + ] + }, + { + "cell_type": "markdown", + "id": "df89ced3", + "metadata": {}, + "source": [ + "You can restrict your search to only keep entries that matches all the criteria across a list of columns." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d1a36b29", + "metadata": {}, + "outputs": [], + "source": [ + "# Only returns variable that have all members, source and experiment asked for. In this case, pr, but not sftlf.\n", + "DC.search(\n", + " source=\"NorESM2-MM\",\n", + " experiment=\"historical\",\n", + " member=[\"r1i1p1f1\", \"r2i1p1f1\"],\n", + " variable=[\"sftlf\", \"pr\"],\n", + " require_all_on=[\"variable\"],\n", + ").df" + ] + }, { "cell_type": "markdown", "id": "7f27214c-2524-4fb7-9b95-4a384ed13a53", @@ -246,7 +295,7 @@ "Due to how different reference datasets are from climate simulations, this function might have to be called multiple times and the results concatenated into a single dictionary. The main arguments are:\n", "\n", "- `variables_and_freqs` is used to indicate which variable and which frequency is required. NOTE: With the exception of fixed fields, where *'fx'* should be used, frequencies here use the `pandas` nomenclature ('D', 'H', '6H', 'MS', etc.).\n", - "- `other_search_criteria` is used to search for specific entries in other columns of the catalog, such as *activity*.\n", + "- `other_search_criteria` is used to search for specific entries in other columns of the catalog, such as *activity*. `require_all_on` can also be passed here.\n", "- `exclusions` is used to exclude certain simulations or keywords from the results.\n", "- `match_hist_and_fut` is used to indicate that RCP/SSP simulations should be matched with their *historical* counterparts.\n", "- `periods` is used to search for specific time periods.\n", @@ -1088,9 +1137,9 @@ "lastKernelId": null }, "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "xscen-dev", "language": "python", - "name": "python3" + "name": "xscen-dev" }, "language_info": { "codemirror_mode": { @@ -1102,7 +1151,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.11.5" } }, "nbformat": 4, From 8f4bfa8c5e64c04b94af984b3ed5211e635c159f Mon Sep 17 00:00:00 2001 From: juliettelavoie Date: Fri, 29 Sep 2023 13:06:27 -0400 Subject: [PATCH 3/4] fix kernel --- docs/notebooks/1_catalog.ipynb | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/notebooks/1_catalog.ipynb b/docs/notebooks/1_catalog.ipynb index 0aa00111..e8974225 100644 --- a/docs/notebooks/1_catalog.ipynb +++ b/docs/notebooks/1_catalog.ipynb @@ -211,7 +211,7 @@ }, { "cell_type": "markdown", - "id": "e2aad0d8", + "id": "5d8b7995", "metadata": {}, "source": [ "Notice that the search fontion returns everything available that matchs some of the criteria." @@ -220,7 +220,7 @@ { "cell_type": "code", "execution_count": null, - "id": "a8fa0138", + "id": "29bd4010", "metadata": {}, "outputs": [], "source": [ @@ -235,7 +235,7 @@ }, { "cell_type": "markdown", - "id": "df89ced3", + "id": "8abaa553", "metadata": {}, "source": [ "You can restrict your search to only keep entries that matches all the criteria across a list of columns." @@ -244,7 +244,7 @@ { "cell_type": "code", "execution_count": null, - "id": "d1a36b29", + "id": "253d4868", "metadata": {}, "outputs": [], "source": [ @@ -1137,9 +1137,9 @@ "lastKernelId": null }, "kernelspec": { - "display_name": "xscen-dev", + "display_name": "Python 3 (ipykernel)", "language": "python", - "name": "xscen-dev" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -1151,7 +1151,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.5" + "version": "3.9.16" } }, "nbformat": 4, From 2a2b969c00a85a16f9778bf0a7b05ff160ccf390 Mon Sep 17 00:00:00 2001 From: juliettelavoie Date: Mon, 2 Oct 2023 09:13:33 -0400 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: RondeauG <38501935+RondeauG@users.noreply.github.com> --- docs/notebooks/1_catalog.ipynb | 4 ++-- xscen/extract.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/notebooks/1_catalog.ipynb b/docs/notebooks/1_catalog.ipynb index e8974225..e7b6ee39 100644 --- a/docs/notebooks/1_catalog.ipynb +++ b/docs/notebooks/1_catalog.ipynb @@ -214,7 +214,7 @@ "id": "5d8b7995", "metadata": {}, "source": [ - "Notice that the search fontion returns everything available that matchs some of the criteria." + "Notice that the search function returns everything available that matches some of the criteria." ] }, { @@ -248,7 +248,7 @@ "metadata": {}, "outputs": [], "source": [ - "# Only returns variable that have all members, source and experiment asked for. In this case, pr, but not sftlf.\n", + "# Only returns variables that have all members, source and experiment asked for. In this case, pr, but not sftlf.\n", "DC.search(\n", " source=\"NorESM2-MM\",\n", " experiment=\"historical\",\n", diff --git a/xscen/extract.py b/xscen/extract.py index 21b48308..7575a526 100644 --- a/xscen/extract.py +++ b/xscen/extract.py @@ -524,7 +524,7 @@ def search_data_catalogs( Variables and freqs to search for, following a 'variable: xr-freq-compatible-str' format. A list of strings can also be provided. other_search_criteria : dict, optional Other criteria to search for in the catalogs' columns, following a 'column_name: list(subset)' format. - You can also pass 'require_all_on: list(columns_name)' in order to only return results that respond to all other criteria across the listed columns. + You can also pass 'require_all_on: list(columns_name)' in order to only return results that correspond to all other criteria across the listed columns. More details available at https://intake-esm.readthedocs.io/en/stable/how-to/enforce-search-query-criteria-via-require-all-on.html . exclusions : dict, optional Same as other_search_criteria, but for eliminating results.