UnboundLocalError when trying model.open_datatree(group=("z","u","v")) on HAMTIDE11

[andrew-longmore-tessella]

Hi, I'm just getting started on pyTMD and am trying to get current data (u,v) on the HAMTIDE11 database.
I can use

datatree = model.open_datatree(group=("z"))

and plot tidal displacements, a bit like https://pytmd.readthedocs.io/en/latest/notebooks/Plot-Tide-Forecasts.html, so I know most things are working.
However, if I try

datatree = model.open_datatree(group=("z","u","v"))

then that line gives me an error
UnboundLocalError: cannot access local variable 'mapping_amp' where it is not associated with a value.

Any suggestions on how to proceed? My python version is 3.14, and my libraries are h5py 3.15.1 and pytmd 3.0.1.
Googling suggests it's to do with the mapping_amp variable name being referenced incorrectly.

[tsutterley]

Right now group wants a tuple (or list) of strings. So use group=('z', 'u', 'v') in this case. Also! If you're wanting the whole datatree you don't need to specify the group (as it'll grab every possible group in the model).

But that's a good find! I can make it so it tries splitting the string up into an iterable (or at the very least providing a helpful error).

[andrew-longmore-tessella]

Sorry, that's an error in my question. Even with

datatree = model.open_datatree()

or

datatree = model.open_datatree(group=("z", "u", "v"))

I get the error UnboundLocalError: cannot access local variable 'mapping_amp' where it is not associated with a value.
I've corrected the question.

[tsutterley]

Ok! I see the problem in the io code. Yep it's a legit bug that stems from me trying to do something fancily.

    elif "AMPL" in tmp.variables:
        # HAMTIDE11 variable names
        mapping_coords = dict(LON="x", LAT="y")
        mapping_amp = dict(z="AMPL", u="UAMP", v="VAMP")
        mapping_ph = dict(z="PHAS", u="UPHA", v="VPHA")

When trying to autodetect the format (e.g. the HAMTIDE naming scheme) it searches for a variable name. But it only looked for the z amplitude name! So yes would totally break when fed a current file. I had written it differently in v2 (and earlier in v3).

I'll get it fixed! Thanks! 🙏🙏🙏

[tsutterley]

Thanks for finding this! Should (hopefully) be fixed in version 3.0.3!

[andrew-longmore-tessella]

If I call

datatree = model.open_datatree(group=("z", "u", "v"), use_default_units=False)

then I do not get an error! xarray is 2025.12.0, here is the full traceback:

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[3], [line 4](vscode-notebook-cell:?execution_count=3&line=4)
      1 # z: tidal elevations in meters
      2 # u: zonal tidal currents in centimetres per second
      3 # v: meridional tidal currents in centimetres per second
----> [4](vscode-notebook-cell:?execution_count=3&line=4) datatree = model.open_datatree(group=("z", "u", "v"))
      6 # convert to model grid coordinates
      7 x, y = datatree.tmd.transform_as(LON, LAT)  # tmd = Tide Model Driver

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pyTMD\io\model.py:866, in model.open_datatree(self, group, **kwargs)
    864         continue
    865     # open xarray Dataset
--> [866](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pyTMD/io/model.py:866)     ds[g] = self.open_dataset(group=g, **kwargs)
    867 # create xarray DataTree from dictionary
    868 dtree = xr.DataTree.from_dict(ds)

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pyTMD\io\model.py:845, in model.open_dataset(self, **kwargs)
    843 # convert to default units
    844 if kwargs["use_default_units"]:
--> [845](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pyTMD/io/model.py:845)     ds = ds.tmd.to_default_units()
    846 # return xarray dataset
    847 return ds

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pyTMD\io\dataset.py:769, in Dataset.to_default_units(self)
    767 # convert each constituent in the dataset
    768 for c in self.constituents:
--> [769](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pyTMD/io/dataset.py:769)     ds[c] = ds[c].tmd.to_default_units()
    770 # return the dataset
    771 return ds

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pyTMD\io\dataset.py:902, in DataArray.to_default_units(self, value)
    894 """Convert ``DataArray`` to default tide units
    895 
    896 Parameters
   (...)    899     scaling factor to apply
    900 """
    901 # convert to default units
--> [902](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pyTMD/io/dataset.py:902) default_units = _default_units.get(self.group, self.units)
    903 da = self.to_units(default_units, value=value)
    904 return da

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pyTMD\io\dataset.py:919, in DataArray.group(self)
    916 @property
    917 def group(self):
    918     """Variable group of the ``DataArray``"""
--> [919](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pyTMD/io/dataset.py:919)     if self.units.is_compatible_with("m"):
    920         return "elevation"
    921     elif self.units.is_compatible_with("m/s"):

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pyTMD\io\dataset.py:909, in DataArray.units(self)
    906 @property
    907 def units(self):
    908     """Units of the ``DataArray``"""
--> [909](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pyTMD/io/dataset.py:909)     return __ureg__.parse_units(self._da.attrs.get("units", ""))

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pint\facets\plain\registry.py:1276, in GenericPlainRegistry.parse_units(self, input_string, as_delta, case_sensitive)
   1248 def parse_units(
   1249     self,
   1250     input_string: str,
   1251     as_delta: bool | None = None,
   1252     case_sensitive: bool | None = None,
   1253 ) -> UnitT:
   1254     """Parse a units expression and returns a UnitContainer with
   1255     the canonical names.
   1256 
   (...)   1272 
   1273     """
   1275     return self.Unit(
-> [1276](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pint/facets/plain/registry.py:1276)         self.parse_units_as_container(input_string, as_delta, case_sensitive)
   1277     )

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pint\facets\nonmultiplicative\registry.py:69, in GenericNonMultiplicativeRegistry.parse_units_as_container(self, input_string, as_delta, case_sensitive)
     66 if as_delta is None:
     67     as_delta = self.default_as_delta
---> [69](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pint/facets/nonmultiplicative/registry.py:69) return super().parse_units_as_container(input_string, as_delta, case_sensitive)

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pint\facets\plain\registry.py:1291, in GenericPlainRegistry.parse_units_as_container(self, input_string, as_delta, case_sensitive)
   1285 as_delta = (
   1286     as_delta if as_delta is not None else True
   1287 )  # TODO This only exists in nonmultiplicative
   1288 case_sensitive = (
   1289     case_sensitive if case_sensitive is not None else self.case_sensitive
   1290 )
-> [1291](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pint/facets/plain/registry.py:1291) return self._parse_units_as_container(input_string, as_delta, case_sensitive)

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pint\facets\plain\registry.py:1319, in GenericPlainRegistry._parse_units_as_container(self, input_string, as_delta, case_sensitive)
   1316 # Sanitize input_string with whitespaces.
   1317 input_string = input_string.strip()
-> [1319](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pint/facets/plain/registry.py:1319) units = ParserHelper.from_string(input_string, self.non_int_type)
   1320 if units.scale != 1:
   1321     raise ValueError("Unit expression cannot have a scaling factor.")

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pint\util.py:768, in ParserHelper.from_string(cls, input_string, non_int_type)
    765     reps = False
    767 gen = pint_eval.tokenizer(input_string)
--> [768](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pint/util.py:768) ret = build_eval_tree(gen).evaluate(
    769     partial(cls.eval_token, non_int_type=non_int_type)
    770 )
    772 if isinstance(ret, Number):
    773     return cls(ret, non_int_type=non_int_type)

File c:\code\jupyter\scheduling-uncertainties\.venv\Lib\site-packages\pint\pint_eval.py:391, in EvalTreeNode.evaluate(self, define_op, bin_op, un_op)
    388     if op_text not in bin_op:
    389         raise DefinitionSyntaxError(f"missing binary operator '{op_text}'")
--> [391](file:///C:/code/jupyter/scheduling-uncertainties/.venv/Lib/site-packages/pint/pint_eval.py:391)     return bin_op[op_text](
    392         self.left.evaluate(define_op, bin_op, un_op),
    393         self.right.evaluate(define_op, bin_op, un_op),
    394     )
    395 elif self.operator:
    396     assert isinstance(self.left, EvalTreeNode), "self.left not EvalTreeNode (4)"

TypeError: unsupported operand type(s) for -: 'ParserHelper' and 'int'

[tsutterley]

Oh no. It's in pint (software for unit handling). I'll look into it!

[tsutterley]

Ok! I fired up one of my field laptops (that runs Windows) and downloaded the HAMTIDE11 files from scratch. I think things are starting to make more sense.

1. I originally had an old version of the HAMTIDE11 current files (before they fixed the units attributes) so I didn't run into the error this morning (or last Friday)
2. they fixed the units attributes in a way that pint doesn't like (using cm s-1 instead of cm s^-1 or similar)

I think the easiest fix will be for pyTMD to default to using the units stored in the tide model database since I have control of it (and the resulting fix won't be a kludge). I will also put the units parsing function in a try/except statement so that it can give less cryptic errors.

[tsutterley]

Should hopefully be fixed in main. Let me know if you want me to put together a release sooner rather than later. Thanks for the help!

[andrew-longmore-tessella]

Thanks Tyler, I'm glad you've gotten to the bottom of it. I think I can just use datatree = model.open_datatree(group=("z", "u", "v"), use_default_units=False) for the moment, so no need to put out a release just for me. Thank you for diving in and responding so quickly!