From 50079928d664e84ad718da0a670f68b6c1c594dd Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Wed, 3 Jul 2024 11:50:14 +0200 Subject: [PATCH 1/9] docs: add clarification regarding write_crs and set_crs There is some confusion around when to use write_crs versus set_crs. This adds a small note to generally prefer write_crs when CRS persistence is needed. Fixes #743 --- docs/getting_started/crs_management.ipynb | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/getting_started/crs_management.ipynb b/docs/getting_started/crs_management.ipynb index d6f94bde..6276b73a 100644 --- a/docs/getting_started/crs_management.ipynb +++ b/docs/getting_started/crs_management.ipynb @@ -527,7 +527,9 @@ "This modifies the `xarray.Dataset` or `xarray.DataArray` and sets the CRS in a CF compliant manner.\n", "\n", "- [rio.write_crs()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.write_crs)\n", - "- [rio.crs](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.crs)" + "- [rio.crs](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.crs)\n", + "\n", + "**Note:** It is generally recommended to use `rio.write_crs()` over `rio.set_crs()` if you want the CRS to persist on the Dataset/DataArray. Writing a Dataset/DataArray after calling only `rio.set_crs()` will not write the CRS information in a CF compliant manner." ] }, { @@ -1098,7 +1100,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.4" + "version": "3.12.4" } }, "nbformat": 4, From f32515517c403ac977d94e8204b57c345c324b4f Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Wed, 3 Jul 2024 23:22:44 +0200 Subject: [PATCH 2/9] docs: add note recommending usage of write_crs over set_crs --- rioxarray/rioxarray.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/rioxarray/rioxarray.py b/rioxarray/rioxarray.py index 64e60841..342b9eff 100644 --- a/rioxarray/rioxarray.py +++ b/rioxarray/rioxarray.py @@ -360,6 +360,9 @@ def set_crs( Set the CRS value for the Dataset/DataArray without modifying the dataset/data array. + DeprecationWarning: It is recommended to use `rio.write_crs()` instead. This + method will likely be removed in a future release. + Parameters ---------- input_crs: object From cd6ed2032fdcc3ac94d97dca7bb071fb5d616f0d Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Wed, 3 Jul 2024 23:49:38 +0200 Subject: [PATCH 3/9] MNT: warn when using rio.set_crs() that deprecation is possible and to use rio.write_crs() instead --- rioxarray/rioxarray.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/rioxarray/rioxarray.py b/rioxarray/rioxarray.py index 342b9eff..3d80557b 100644 --- a/rioxarray/rioxarray.py +++ b/rioxarray/rioxarray.py @@ -2,6 +2,7 @@ This module is an extension for xarray to provide rasterio capabilities to xarray datasets/dataarrays. """ + # pylint: disable=too-many-lines import json import math @@ -375,6 +376,13 @@ def set_crs( :obj:`xarray.Dataset` | :obj:`xarray.DataArray`: Dataset with crs attribute. """ + warnings.warn( + "It is recommended to use `rio.write_crs()` instead. `rio.set_crs() will likely" + "be removed in a future release.", + DeprecationWarning, + stacklevel=2, + ) + crs = crs_from_user_input(input_crs) obj = self._get_obj(inplace=inplace) obj.rio._crs = crs From 0e2c974f993fa0a8b2be07ed2ca73a8968bffa58 Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Sat, 6 Jul 2024 22:46:26 +0200 Subject: [PATCH 4/9] DOC: use deprecated instead of DeprecationWarning for set_crs Co-authored-by: Alan D. Snow --- rioxarray/rioxarray.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rioxarray/rioxarray.py b/rioxarray/rioxarray.py index 3d80557b..7eed2bff 100644 --- a/rioxarray/rioxarray.py +++ b/rioxarray/rioxarray.py @@ -361,7 +361,8 @@ def set_crs( Set the CRS value for the Dataset/DataArray without modifying the dataset/data array. - DeprecationWarning: It is recommended to use `rio.write_crs()` instead. This + .. deprecated:: 0.15.8 + It is recommended to use `rio.write_crs()` instead. This method will likely be removed in a future release. Parameters From 9c9d9ca89d8d70a6a74e06065dba5a9d5fbd48f0 Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Sat, 6 Jul 2024 22:47:33 +0200 Subject: [PATCH 5/9] DOC: clarify set_crs vs. write_crs usage note Co-authored-by: Alan D. Snow --- docs/getting_started/crs_management.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started/crs_management.ipynb b/docs/getting_started/crs_management.ipynb index 6276b73a..54511d46 100644 --- a/docs/getting_started/crs_management.ipynb +++ b/docs/getting_started/crs_management.ipynb @@ -529,7 +529,7 @@ "- [rio.write_crs()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.write_crs)\n", "- [rio.crs](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.crs)\n", "\n", - "**Note:** It is generally recommended to use `rio.write_crs()` over `rio.set_crs()` if you want the CRS to persist on the Dataset/DataArray. Writing a Dataset/DataArray after calling only `rio.set_crs()` will not write the CRS information in a CF compliant manner." + "**Note:** It is recommended to use `rio.write_crs()` if you want the CRS to persist on the Dataset/DataArray and to write the CRS CF compliant metadata. Calling only `rio.set_crs()` CRS storage method is lossy and will not modify the Dataset/DataArray metadata." ] }, { From 8610c7794130ffad6bfcd69c757bc1fcac59db07 Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Sat, 6 Jul 2024 22:48:26 +0200 Subject: [PATCH 6/9] MNT: raise FutureWarning instead of DeprecationWarning for set_crs Co-authored-by: Alan D. Snow --- rioxarray/rioxarray.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rioxarray/rioxarray.py b/rioxarray/rioxarray.py index 7eed2bff..a767efbe 100644 --- a/rioxarray/rioxarray.py +++ b/rioxarray/rioxarray.py @@ -380,7 +380,7 @@ def set_crs( warnings.warn( "It is recommended to use `rio.write_crs()` instead. `rio.set_crs() will likely" "be removed in a future release.", - DeprecationWarning, + FutureWarning, stacklevel=2, ) From 778f60d01c323c8bcb348254e9deab2c39f01180 Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Sat, 6 Jul 2024 23:10:32 +0200 Subject: [PATCH 7/9] REF: use _set_crs internally and raise FutureWarning when using public set_crs --- rioxarray/rioxarray.py | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/rioxarray/rioxarray.py b/rioxarray/rioxarray.py index a767efbe..d118b784 100644 --- a/rioxarray/rioxarray.py +++ b/rioxarray/rioxarray.py @@ -306,7 +306,7 @@ def crs(self) -> Optional[rasterio.crs.CRS]: # pyproj CRS if possible for performance for crs_attr in ("spatial_ref", "crs_wkt"): try: - self.set_crs( + self._set_crs( self._obj.coords[self.grid_mapping].attrs[crs_attr], inplace=True, ) @@ -316,14 +316,14 @@ def crs(self) -> Optional[rasterio.crs.CRS]: # look in grid_mapping try: - self.set_crs( + self._set_crs( pyproj.CRS.from_cf(self._obj.coords[self.grid_mapping].attrs), inplace=True, ) except (KeyError, pyproj.exceptions.CRSError): try: # look in attrs for 'crs' - self.set_crs(self._obj.attrs["crs"], inplace=True) + self._set_crs(self._obj.attrs["crs"], inplace=True) except KeyError: self._crs = False return None @@ -374,7 +374,7 @@ def set_crs( Returns ------- - :obj:`xarray.Dataset` | :obj:`xarray.DataArray`: + :obj:`xarray.Dataset` | :obj:`xarray.DataArray` Dataset with crs attribute. """ warnings.warn( @@ -384,6 +384,27 @@ def set_crs( stacklevel=2, ) + return self._set_crs(input_crs, inplace=inplace) + + def _set_crs( + self, input_crs: Any, inplace: bool = True + ) -> Union[xarray.Dataset, xarray.DataArray]: + """ + Set the CRS value for the Dataset/DataArray without modifying + the dataset/data array. + + Parameters + ---------- + input_crs: object + Anything accepted by `rasterio.crs.CRS.from_user_input`. + inplace: bool, optional + If True, it will write to the existing dataset. Default is False. + + Returns + ------- + :obj:`xarray.Dataset` | :obj:`xarray.DataArray`: + Dataset with crs attribute. + """ crs = crs_from_user_input(input_crs) obj = self._get_obj(inplace=inplace) obj.rio._crs = crs @@ -495,7 +516,7 @@ def write_crs( >>> raster = raster.rio.write_crs("epsg:4326") """ if input_crs is not None: - data_obj = self.set_crs(input_crs, inplace=inplace) + data_obj = self._set_crs(input_crs, inplace=inplace) else: data_obj = self._get_obj(inplace=inplace) From 70c6f6095c4f4a240c1649a2ffad806995d80399 Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Sat, 6 Jul 2024 23:16:55 +0200 Subject: [PATCH 8/9] DOC: remove sphinx notation from private _set_crs method --- rioxarray/rioxarray.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rioxarray/rioxarray.py b/rioxarray/rioxarray.py index d118b784..ad044176 100644 --- a/rioxarray/rioxarray.py +++ b/rioxarray/rioxarray.py @@ -374,7 +374,7 @@ def set_crs( Returns ------- - :obj:`xarray.Dataset` | :obj:`xarray.DataArray` + :obj:`xarray.Dataset` | :obj:`xarray.DataArray`: Dataset with crs attribute. """ warnings.warn( @@ -402,7 +402,7 @@ def _set_crs( Returns ------- - :obj:`xarray.Dataset` | :obj:`xarray.DataArray`: + xarray.Dataset | xarray.DataArray Dataset with crs attribute. """ crs = crs_from_user_input(input_crs) From 62457557292bc16c7cd9275590b0f4f9c5d5d848 Mon Sep 17 00:00:00 2001 From: Daniel Lusk Date: Mon, 8 Jul 2024 18:18:48 +0200 Subject: [PATCH 9/9] MNT: use single quotes over backticks in set_crs warning text Co-authored-by: Alan D. Snow --- rioxarray/rioxarray.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rioxarray/rioxarray.py b/rioxarray/rioxarray.py index ad044176..4a418bf8 100644 --- a/rioxarray/rioxarray.py +++ b/rioxarray/rioxarray.py @@ -378,7 +378,7 @@ def set_crs( Dataset with crs attribute. """ warnings.warn( - "It is recommended to use `rio.write_crs()` instead. `rio.set_crs() will likely" + "It is recommended to use 'rio.write_crs()' instead. 'rio.set_crs()' will likely" "be removed in a future release.", FutureWarning, stacklevel=2,