Change name vertical dimension argument (#144)

change the name of vertical-dimension-as-originally-producted to vertical-dimension-output

copernicusmarine/catalogue_parser/request_structure.py

@@ -15,9 +15,11 @@
     DEFAULT_BOUNDING_BOX_METHOD,
     DEFAULT_FILE_FORMAT,
     DEFAULT_SUBSET_METHOD,
+    DEFAULT_VERTICAL_DIMENSION_OUTPUT,
     BoundingBoxMethod,
     FileFormat,
     SubsetMethod,
+    VerticalDimensionOutput,
 )
 from copernicusmarine.core_functions.utils import datetime_parser
 from copernicusmarine.download_functions.subset_parameters import (
@@ -61,7 +63,9 @@ class SubsetRequest:
     maximum_latitude: Optional[float] = None
     minimum_depth: Optional[float] = None
     maximum_depth: Optional[float] = None
-    vertical_dimension_as_originally_produced: bool = True
+    vertical_dimension_output: VerticalDimensionOutput = (
+        DEFAULT_VERTICAL_DIMENSION_OUTPUT
+    )
     start_datetime: Optional[DateTime] = None
     end_datetime: Optional[DateTime] = None
     bounding_box_method: BoundingBoxMethod = DEFAULT_BOUNDING_BOX_METHOD

copernicusmarine/command_line_interface/group_subset.py

@@ -24,9 +24,12 @@
     DEFAULT_FILE_FORMATS,
     DEFAULT_SUBSET_METHOD,
     DEFAULT_SUBSET_METHODS,
+    DEFAULT_VERTICAL_DIMENSION_OUTPUT,
+    DEFAULT_VERTICAL_DIMENSION_OUTPUTS,
     BoundingBoxMethod,
     FileFormat,
     SubsetMethod,
+    VerticalDimensionOutput,
 )
 from copernicusmarine.core_functions.services_utils import CommandType
 from copernicusmarine.core_functions.subset import (
@@ -182,14 +185,15 @@ def cli_subset() -> None:
     help="Maximum depth for the subset. Requires a float within this range:",
 )
 @click.option(
-    "--vertical-dimension-as-originally-produced",
-    type=bool,
-    default=True,
-    show_default=True,
+    "--vertical-dimension-output",
+    "-V",
+    type=click.Choice(DEFAULT_VERTICAL_DIMENSION_OUTPUTS),
+    default=DEFAULT_VERTICAL_DIMENSION_OUTPUT,
     help=(
-        "Consolidate the vertical dimension (the z-axis) as it is in the "
-        "dataset originally produced, "
-        "named `depth` with descending positive values."
+        "Consolidate the vertical dimension (the z-axis) as requested:"
+        " `depth` with descending positive values."
+        " `elevation` with ascending positive values."
+        " Default is `depth`."
     ),
 )
 @click.option(
@@ -380,7 +384,7 @@ def subset(
     maximum_latitude: Optional[float],
     minimum_depth: Optional[float],
     maximum_depth: Optional[float],
-    vertical_dimension_as_originally_produced: bool,
+    vertical_dimension_output: VerticalDimensionOutput,
     start_datetime: Optional[str],
     end_datetime: Optional[str],
     bounding_box_method: BoundingBoxMethod,
@@ -432,7 +436,7 @@ def subset(
         maximum_latitude,
         minimum_depth,
         maximum_depth,
-        vertical_dimension_as_originally_produced,
+        vertical_dimension_output,
         datetime_parser(start_datetime) if start_datetime else None,
         datetime_parser(end_datetime) if end_datetime else None,
         bounding_box_method,

copernicusmarine/core_functions/models.py

@@ -19,6 +19,10 @@
 DEFAULT_BOUNDING_BOX_METHOD: BoundingBoxMethod = "inside"
 DEFAULT_BOUNDING_BOX_METHODS = list(get_args(BoundingBoxMethod))
 
+VerticalDimensionOutput = Literal["depth", "elevation"]
+DEFAULT_VERTICAL_DIMENSION_OUTPUT: VerticalDimensionOutput = "depth"
+DEFAULT_VERTICAL_DIMENSION_OUTPUTS = list(get_args(VerticalDimensionOutput))
+
 
 class FileGet(BaseModel):
     #: Full url of the location of the file server side.

copernicusmarine/core_functions/subset.py

@@ -20,6 +20,7 @@
     BoundingBoxMethod,
     ResponseSubset,
     SubsetMethod,
+    VerticalDimensionOutput,
 )
 from copernicusmarine.core_functions.services_utils import (
     CommandType,
@@ -55,7 +56,7 @@ def subset_function(
     maximum_latitude: Optional[float],
     minimum_depth: Optional[float],
     maximum_depth: Optional[float],
-    vertical_dimension_as_originally_produced: bool,
+    vertical_dimension_output: VerticalDimensionOutput,
     start_datetime: Optional[DateTime],
     end_datetime: Optional[DateTime],
     bounding_box_method: BoundingBoxMethod,
@@ -110,7 +111,7 @@ def subset_function(
         "maximum_latitude": maximum_latitude,
         "minimum_depth": minimum_depth,
         "maximum_depth": maximum_depth,
-        "vertical_dimension_as_originally_produced": vertical_dimension_as_originally_produced,  # noqa
+        "vertical_dimension_output": vertical_dimension_output,
         "start_datetime": start_datetime,
         "end_datetime": end_datetime,
         "bounding_box_method": bounding_box_method,

copernicusmarine/download_functions/download_arco_series.py

@@ -192,7 +192,7 @@ def download_zarr(
     depth_parameters = DepthParameters(
         minimum_depth=subset_request.minimum_depth,
         maximum_depth=subset_request.maximum_depth,
-        vertical_dimension_as_originally_produced=subset_request.vertical_dimension_as_originally_produced,  # noqa
+        vertical_dimension_output=subset_request.vertical_dimension_output,
     )
     dataset_url = str(subset_request.dataset_url)
     output_directory = (

copernicusmarine/download_functions/subset_parameters.py

@@ -3,6 +3,11 @@
 
 from pendulum import DateTime
 
+from copernicusmarine.core_functions.models import (
+    DEFAULT_VERTICAL_DIMENSION_OUTPUT,
+    VerticalDimensionOutput,
+)
+
 
 @dataclass
 class LatitudeParameters:
@@ -36,4 +41,6 @@ class TemporalParameters:
 class DepthParameters:
     minimum_depth: Optional[float] = None
     maximum_depth: Optional[float] = None
-    vertical_dimension_as_originally_produced: bool = True
+    vertical_dimension_output: VerticalDimensionOutput = (
+        DEFAULT_VERTICAL_DIMENSION_OUTPUT
+    )

copernicusmarine/download_functions/subset_xarray.py

@@ -384,7 +384,7 @@ def update_elevation_attributes(dataset: xarray.Dataset):
             dataset["elevation"].attrs = attrs
         return dataset
 
-    if depth_parameters.vertical_dimension_as_originally_produced:
+    if depth_parameters.vertical_dimension_output == "depth":
         dataset = convert_elevation_to_depth(dataset)
     else:
         dataset = update_elevation_attributes(dataset)

copernicusmarine/python_interface/open_dataset.py

@@ -15,8 +15,10 @@
 from copernicusmarine.core_functions.models import (
     DEFAULT_BOUNDING_BOX_METHOD,
     DEFAULT_SUBSET_METHOD,
+    DEFAULT_VERTICAL_DIMENSION_OUTPUT,
     BoundingBoxMethod,
     SubsetMethod,
+    VerticalDimensionOutput,
 )
 from copernicusmarine.download_functions.download_arco_series import (
     open_dataset_from_arco_series,
@@ -67,7 +69,7 @@ def open_dataset(
     maximum_latitude: Optional[float] = None,
     minimum_depth: Optional[float] = None,
     maximum_depth: Optional[float] = None,
-    vertical_dimension_as_originally_produced: bool = True,
+    vertical_dimension_output: VerticalDimensionOutput = DEFAULT_VERTICAL_DIMENSION_OUTPUT,  # noqa
     start_datetime: Optional[Union[datetime, str]] = None,
     end_datetime: Optional[Union[datetime, str]] = None,
     bounding_box_method: BoundingBoxMethod = DEFAULT_BOUNDING_BOX_METHOD,
@@ -114,8 +116,9 @@ def open_dataset(
     subset_method : str, optional
         The subset method ('nearest' or 'strict') when requesting the dataset. If strict, you can only request dimensions
         strictly inside the dataset.
-    vertical_dimension_as_originally_produced : bool, optional
-        If True, use the vertical dimension as originally produced.
+    vertical_dimension_output : str, optional
+        Consolidate the vertical dimension (the z-axis) as requested: 'depth' with descending positive values.
+        'elevation' with ascending positive values. Default is 'depth'.
     start_datetime : datetime, optional
         The start datetime for temporal subsetting.
     end_datetime : datetime, optional
@@ -159,7 +162,7 @@ def open_dataset(
         depth_parameters=DepthParameters(
             minimum_depth=minimum_depth,
             maximum_depth=maximum_depth,
-            vertical_dimension_as_originally_produced=vertical_dimension_as_originally_produced,  # noqa
+            vertical_dimension_output=vertical_dimension_output,
         ),
         bounding_box_method=bounding_box_method,
         subset_method=subset_method,

copernicusmarine/python_interface/read_dataframe.py

@@ -15,8 +15,10 @@
 from copernicusmarine.core_functions.models import (
     DEFAULT_BOUNDING_BOX_METHOD,
     DEFAULT_SUBSET_METHOD,
+    DEFAULT_VERTICAL_DIMENSION_OUTPUT,
     BoundingBoxMethod,
     SubsetMethod,
+    VerticalDimensionOutput,
 )
 from copernicusmarine.download_functions.download_arco_series import (
     read_dataframe_from_arco_series,
@@ -67,7 +69,7 @@ def read_dataframe(
     maximum_latitude: Optional[float] = None,
     minimum_depth: Optional[float] = None,
     maximum_depth: Optional[float] = None,
-    vertical_dimension_as_originally_produced: bool = True,
+    vertical_dimension_output: VerticalDimensionOutput = DEFAULT_VERTICAL_DIMENSION_OUTPUT,  # noqa
     start_datetime: Optional[Union[datetime, str]] = None,
     end_datetime: Optional[Union[datetime, str]] = None,
     bounding_box_method: BoundingBoxMethod = DEFAULT_BOUNDING_BOX_METHOD,
@@ -108,8 +110,9 @@ def read_dataframe(
         Minimum depth for vertical subset.
     maximum_depth : float, optional
         Maximum depth for vertical subset.
-    vertical_dimension_as_originally_produced : bool, optional
-        If True, use the vertical dimension as originally produced.
+    vertical_dimension_output : str, optional
+        Consolidate the vertical dimension (the z-axis) as requested: 'depth' with descending positive values.
+        'elevation' with ascending positive values. Default is 'depth'.
     start_datetime : datetime, optional
         Start datetime for temporal subset.
     end_datetime : datetime, optional
@@ -164,7 +167,7 @@ def read_dataframe(
         depth_parameters=DepthParameters(
             minimum_depth=minimum_depth,
             maximum_depth=maximum_depth,
-            vertical_dimension_as_originally_produced=vertical_dimension_as_originally_produced,  # noqa
+            vertical_dimension_output=vertical_dimension_output,
         ),
         bounding_box_method=bounding_box_method,
         force_service=force_service,

copernicusmarine/python_interface/subset.py

@@ -10,10 +10,12 @@
     DEFAULT_BOUNDING_BOX_METHOD,
     DEFAULT_FILE_FORMAT,
     DEFAULT_SUBSET_METHOD,
+    DEFAULT_VERTICAL_DIMENSION_OUTPUT,
     BoundingBoxMethod,
     FileFormat,
     ResponseSubset,
     SubsetMethod,
+    VerticalDimensionOutput,
 )
 from copernicusmarine.core_functions.subset import subset_function
 from copernicusmarine.python_interface.exception_handler import (
@@ -37,7 +39,7 @@ def subset(
     maximum_latitude: Optional[float] = None,
     minimum_depth: Optional[float] = None,
     maximum_depth: Optional[float] = None,
-    vertical_dimension_as_originally_produced: bool = True,
+    vertical_dimension_output: VerticalDimensionOutput = DEFAULT_VERTICAL_DIMENSION_OUTPUT,  # noqa
     start_datetime: Optional[Union[datetime, str]] = None,
     end_datetime: Optional[Union[datetime, str]] = None,
     bounding_box_method: BoundingBoxMethod = DEFAULT_BOUNDING_BOX_METHOD,
@@ -99,8 +101,9 @@ def subset(
         Minimum depth value for vertical subset.
     maximum_depth : float, optional
         Maximum depth value for vertical subset.
-    vertical_dimension_as_originally_produced : bool, optional
-        Use original vertical dimension.
+    vertical_dimension_output : str, optional
+        Consolidate the vertical dimension (the z-axis) as requested: 'depth' with descending positive values.
+        'elevation' with ascending positive values. Default is 'depth'.
     start_datetime : datetime, optional
         Start datetime for temporal subset.
     end_datetime : datetime, optional
@@ -158,7 +161,7 @@ def subset(
         maximum_latitude,
         minimum_depth,
         maximum_depth,
-        vertical_dimension_as_originally_produced,
+        vertical_dimension_output,
         start_datetime,
         end_datetime,
         bounding_box_method,

tests/__snapshots__/test_help_command_interface.ambr

@@ -267,11 +267,12 @@
     '  -Z, --maximum-depth, --maximal-depth FLOAT RANGE',
     '                                  Maximum depth for the subset. Requires a',
     '                                  float within this range:  [x>=0]',
-    '  --vertical-dimension-as-originally-produced BOOLEAN',
+    '  -V, --vertical-dimension-output [depth|elevation]',
     '                                  Consolidate the vertical dimension (the',
-    '                                  z-axis) as it is in the dataset originally',
-    '                                  produced, named `depth` with descending',
-    '                                  positive values.  [default: True]',
+    '                                  z-axis) as requested: `depth` with',
+    '                                  descending positive values. `elevation` with',
+    '                                  ascending positive values. Default is',
+    '                                  `depth`.',
     '  -t, --start-datetime TEXT       The start datetime of the temporal subset.',
     '                                  Caution: encapsulate date with " " to ensure',
     '                                  valid expression for format "%Y-%m-%d',

tests/test_command_line_interface.py

@@ -9,7 +9,7 @@
 from dataclasses import dataclass
 from json import loads
 from pathlib import Path
-from typing import List, Optional, Union
+from typing import List, Literal, Optional, Union
 
 import xarray
 
@@ -1048,7 +1048,9 @@ def then_I_got_a_clear_output_with_available_service_for_subset(self):
         ) in self.output.stderr
 
     def when_I_request_subset_dataset_with_zarr_service(
-        self, output_path, vertical_dimension_as_originally_produced
+        self,
+        output_path,
+        vertical_dimension_output: Literal["depth", "elevation"] = "depth",
     ):
         command = [
             "copernicusmarine",
@@ -1073,8 +1075,8 @@ def when_I_request_subset_dataset_with_zarr_service(
             "10",
             "-v",
             "thetao",
-            "--vertical-dimension-as-originally-produced",
-            f"{vertical_dimension_as_originally_produced}",
+            "--vertical-dimension-output",
+            f"{vertical_dimension_output}",
             "--service",
             "arco-time-series",
             "-o",
@@ -1109,14 +1111,16 @@ def then_I_have_correct_attribute_value(
         assert dataset[dimention_name].attrs["positive"] == attribute_value
 
     def test_conversion_between_elevation_and_depth(self, tmp_path):
-        self.when_I_request_subset_dataset_with_zarr_service(tmp_path, True)
+        self.when_I_request_subset_dataset_with_zarr_service(tmp_path, "depth")
         self.then_I_have_correct_sign_for_depth_coordinates_values(
             tmp_path, "positive"
         )
         self.then_I_have_correct_attribute_value(tmp_path, "depth", "down")
 
     def test_force_no_conversion_between_elevation_and_depth(self, tmp_path):
-        self.when_I_request_subset_dataset_with_zarr_service(tmp_path, False)
+        self.when_I_request_subset_dataset_with_zarr_service(
+            tmp_path, "elevation"
+        )
         self.then_I_have_correct_sign_for_depth_coordinates_values(
             tmp_path, "negative"
         )
@@ -1419,7 +1423,7 @@ def then_I_can_read_copernicusmarine_version_in_the_dataset_attributes(
     def test_copernicusmarine_version_in_dataset_attributes_with_arco(
         self, tmp_path
     ):
-        self.when_I_request_subset_dataset_with_zarr_service(tmp_path, True)
+        self.when_I_request_subset_dataset_with_zarr_service(tmp_path)
         self.then_I_can_read_copernicusmarine_version_in_the_dataset_attributes(
             tmp_path / "data.zarr"
         )
@@ -1588,7 +1592,7 @@ def then_I_can_read_dataset_size(self):
     def test_dataset_size_is_displayed_when_downloading_with_arco_service(
         self, tmp_path
     ):
-        self.when_I_request_subset_dataset_with_zarr_service(tmp_path, True)
+        self.when_I_request_subset_dataset_with_zarr_service(tmp_path)
         self.then_I_can_read_dataset_size()
 
     def test_dataset_has_always_every_dimensions(self, tmp_path):
@@ -2262,8 +2266,8 @@ def test_bounding_box_method_outside_w_elevation(self, tmp_path):
             f"{max_depth}",
             "--bounding-box-method",
             "outside",
-            "--vertical-dimension-as-originally-produced",
-            "False",
+            "--vertical-dimension-output",
+            "elevation",
             "-o",
             f"{tmp_path}",
             "-f",

tests/test_python_interface.py

@@ -174,7 +174,7 @@ def test_ISO8601_datetime_format_as_string(
             maximum_latitude=0.1,
             minimum_longitude=0.2,
             maximum_longitude=0.3,
-            vertical_dimension_as_originally_produced=False,
+            vertical_dimension_output="elevation",
         )
         assert dataset is not None
         assert (

tests/test_warnings_subset_bounds.py

@@ -200,8 +200,8 @@ def test_warn_elevation_out_of_dataset_bounds(self, tmp_path):
                 f"{min_depth}",
                 "--maximum-depth",
                 f"{max_depth}",
-                "--vertical-dimension-as-originally-produced",
-                "False",
+                "--vertical-dimension-output",
+                "elevation",
                 "-o",
                 f"{tmp_path}",
                 "-f",