Document the return-tuple order of `Points.reconstruct(time, return_array=True)`

[dietmarmuller]

Points.reconstruct(time, return_array=True) returns a tuple of two arrays — but which one is longitudes and which is latitudes is not obvious from the current docstring. Both unpackings compile, and at most one is correct; the other silently swaps the coordinates and mis-plots reconstructed points into the wrong hemisphere with no exception.

In our tutorial suite, two notebooks happen to disagree:

# T05 — unpacks longitudes first
plon, plat = pt.reconstruct(time=t, return_array=True)

# T06 — unpacks latitudes first
end_lats, end_lons = ENDS.reconstruct(time=T, return_array=True)

Once the canonical order is confirmed we will fix whichever of T05 / T06 is wrong.

Request

1. Document the order explicitly in the Points.reconstruct docstring. Something as short as "Returns: (lats, lons) when return_array=True" (or (lons, lats) — whichever it is) would do it. The pygplates convention is generally (lat, lon); if Points.reconstruct follows a different convention, that's especially worth flagging.

2. (Optional, longer-term) Consider returning a structured object (a NamedTuple or small dataclass with .lats and .lons attributes) when return_array=True. That makes the order self-documenting at call sites and removes the silent failure mode entirely.

Happy to send a docstring PR once the canonical order is confirmed.

[jcannon-gplates]

That is odd. Both notebooks appear to initialise a Points objects in pretty much the same way, and call Points.reconstruct the same. So I can't see what could be causing the difference.

Also the docs do note that longitudes are first, then latitudes. But yes, it could be clearer as to what arrays/objects are in the return tuple based on function arguments return_array and return_point_indices. Essentially a tuple is always returned unless both those arguments are False (in which case just a Points object is returned). Then what goes into that return tuple (if one is returned), and in what order, is already documented. Eg, rlons, rlats, point_indices is returned if both those arguments are True. So that could be made clearer.

And the NamedTuple is good idea. Athough it's not backward compatible. GPlately returns (lons, lats) ordering across all functions as a general rule. So as long as that's clearly documented it should be fine. PyGPlates returns the opposite order (lat, lon) for each individual point (tuple). That's an unfortunate legacy of GPlates ordering it that way. But GPlately follows the GMT convention (lon, lat).

[jcannon-gplates]

Once the canonical order is confirmed we will fix whichever of T05 / T06 is wrong.

Oh I see. You need to know which Notebook is doing the right thing. That would be T05. So T06 needs fixing.

[dietmarmuller]

Yes, it looks like T06 needs fixing. Thanks for the followup.