diff --git a/.cruft.json b/.cruft.json
index e2cee77e..5ac4ee79 100644
--- a/.cruft.json
+++ b/.cruft.json
@@ -11,7 +11,7 @@
"project_slug": "xscen",
"project_short_description": "A climate change scenario-building analysis framework, built with xclim/xarray.",
"pypi_username": "RondeauG",
- "version": "0.7.9-beta",
+ "version": "0.7.10-beta",
"use_pytest": "y",
"use_black": "y",
"add_pyup_badge": "n",
diff --git a/HISTORY.rst b/HISTORY.rst
index 24b8f090..67515d77 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`).
* ``xs.save_to_table`` and ``xs.io.to_table`` to transform datasets and arrays to DataFrames, but with support for multi-columns, multi-sheets and localized table of content generation.
Breaking changes
diff --git a/docs/notebooks/1_catalog.ipynb b/docs/notebooks/1_catalog.ipynb
index 063b89ee..e7b6ee39 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": "5d8b7995",
+ "metadata": {},
+ "source": [
+ "Notice that the search function returns everything available that matches some of the criteria."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "29bd4010",
+ "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": "8abaa553",
+ "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": "253d4868",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# 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",
+ " 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",
@@ -1102,7 +1151,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.10.12"
+ "version": "3.9.16"
}
},
"nbformat": 4,
diff --git a/setup.cfg b/setup.cfg
index 8c9fb711..9fa11c2f 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,5 +1,5 @@
[bumpversion]
-current_version = 0.7.9-beta
+current_version = 0.7.10-beta
commit = True
tag = False
parse = (?P\d+)\.(?P\d+).(?P\d+)(\-(?P[a-z]+))?
diff --git a/setup.py b/setup.py
index 851875f2..8e48b7bb 100644
--- a/setup.py
+++ b/setup.py
@@ -102,6 +102,6 @@ def run(self):
test_suite="tests",
extras_require={"dev": dev_requirements},
url="https://github.com/Ouranosinc/xscen",
- version="0.7.9-beta",
+ version="0.7.10-beta",
zip_safe=False,
)
diff --git a/tests/test_xscen.py b/tests/test_xscen.py
index ee57f047..973d7797 100644
--- a/tests/test_xscen.py
+++ b/tests/test_xscen.py
@@ -28,4 +28,4 @@ def test_package_metadata(self):
contents = f.read()
assert """Gabriel Rondeau-Genesse""" in contents
assert '__email__ = "rondeau-genesse.gabriel@ouranos.ca"' in contents
- assert '__version__ = "0.7.9-beta"' in contents
+ assert '__version__ = "0.7.10-beta"' in contents
diff --git a/xscen/__init__.py b/xscen/__init__.py
index 002f2a61..8b2e4053 100644
--- a/xscen/__init__.py
+++ b/xscen/__init__.py
@@ -52,7 +52,7 @@
__author__ = """Gabriel Rondeau-Genesse"""
__email__ = "rondeau-genesse.gabriel@ouranos.ca"
-__version__ = "0.7.9-beta"
+__version__ = "0.7.10-beta"
# monkeypatch so that warnings.warn() doesn't mention itself
diff --git a/xscen/extract.py b/xscen/extract.py
index c0eb00a6..7575a526 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 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.
match_hist_and_fut: bool, optional