Coordinate Naming Convention about podpac HOT 8 CLOSED

I still think the coordinate definition interface is too flexible, making it harder to understand for new or casual users. I think we should make the definition process very self-explanatory, then add intermediate/extra interfaces to support more complicated coordinate systems.

This would require adding some classes, but generally I think the Coordinate class would become CoordinateSystem and we could make some other changes to support the new definition style. Any thoughts on this?

from podpac.

From @jmilloy

I do think that the Coord vs Coordinate class names are a bit confusing. My proposal was going to be to rename Coordinate to MultiCoordinate which is similar to your proposed name CoordinateSystem. I would keep the coordinate function named as it is, and I would be indifferent to whether we changed e.g. UniformCoord to UniformCoordinate.

But I don't really see much of a difference except that instead of using keyword arguments with underscores for stacked dimensions, you pass the values and dimensions labels in separately as lists/tuples, with exactly the same types/values accepted:

Coordinate([(, ), ], labels=[('lat', 'lon'), 'time])

vs

Coordinate(lat_lon=(, ), time=)

from podpac.

From @jmilloy

I'm curious if their was a User Guide that was presented in this order if the Coordinates would be easier to understand for a new user (and seem more constrained).

With or without the PR, if you want to be explicit, you can make Coord or UniformCoord objects and use those. This is a very similar to what you are proposing, and this is how I think the Coordinate User Guide should start (I've used the coordinate function from the !2):

lat = Coord(np.array([0, 1, 2, 3]))
lon = UniformCoord(start, stop, step)
unstacked = podpac.coordinate(lat=lat, lon=lon)
stacked = podpac.coordinate(lat_lon=[lat, lon])

And, like in your proposal, we accept some shortcuts, which I would show second in the User Guide. This is what you usually see throughout podpac tests:

lat = np.array([0, 1, 2, 3])
lon = (start, stop, step)
unstacked = podpac.coordinate(lat=lat, lon=lon)
stacked = podpac.coordinate(lat_lon=[lat, lon])

We accept an additional shortcut for stacked uniform coordinates, a useful case, third in the User Guide:

stacked = podpac.coordinate(lat_lon=((start, stop), (start, stop), N)

Finally, you can also use initialize a Coordinate object directly with a dictionary. This is advanced usage that can be useful when creating a new Coordinate object from an existing Coordinate object. You can use it directly like this:

lat = Coord(np.array([0, 1, 2, 3]))
lon = UniformCoord(start, stop, step)
unstacked = Coordinate({'lat':lat, 'lon'=lon})
stacked = Coordinate({'lat_lon'}=(lat, lon)})

from podpac.

Thanks for the explanation - this all makes a lot of sense. To some extent I am bringing up semantics here, so i appreciate the patience. I had the class inheritance backwards between Coordinate and Coord. Generally now all I am looking for is a little more semantic naming and organization of all these classes (and the docs you propose below).

One idea would be:

• BaseCoord -> BaseDimension
• Coord -> Dimension
• MonotonicCoord -> MonotonicDimension
• UniformCoord -> LinspaceDimension (not sure on this, but people from matlab and numpy know linspace intuitively)
• BaseCoordinate ->BaseCoordinates
• Coordinate -> Coordinates (Coordinates makes sense for 1D or ND)
• coordinate() -> define_coordinates() (this will make it easier to diff from Coordinates)

or alternatively

• "Coord" -> "Coordinate"
• "Coordinate" -> "Coordinates" (could be confusing) or "CoordinateSystem" (a little verbose)

I would propose to put each class in a separate file in the coordinate directory (except maybe coordinate_system() which could go in util?)

As for the labeling instead of splitting on "_", lets leave that aside, we can always address that later.

from podpac.

The names of the classes are important. A BaseCoord class holds the coordinates of one dimension. It is not a dimension, but the coordinates of a dimension, so I don't think "Dimension" is right. "System" has a specific and different meaning to me, too, so I don't think that's right either. But I don't know what is! MultiCoordinate or CoordinateSet or CoordinateSpace makes more sense to me than CoordinateSystem. The other ones don't matter as much, you can use them, and I would put them first in the User Guide, but in practice you don't really ever use them directly.

I agree, usually you want to create your uniform coordinate values as a linspace. In fact, there is a function coord_linspace that produces a UniformCoord, and since you usually just use the shortcuts, you don't think about it, you just type (0.0, 1.0, 20) and it behaves like a linspace. But I think there is a subtle reason that the step is the fundamental attribute that defines this type of coordinates though (instead of the size). If you have c = UniformCoord(1, 10, 0.5) and then you c.select([2, 8]), you want to preserve the step, not the size. Same if you change c.start = 2.0, you get the step and the new size that you expect. I think it could be implemented the other way, but this way holds the real facts about the coordinates it represents, and before the change there were heaps of hard to resolve edge-cases and unexpected behavior.

from podpac.

After discussion, we resolved to:

• Coord -> Coordinate1D in all classes (or lower case D? - this could still use adjusting)
  • i.e. MonotonicCoordinate1D - this does seem a bit verbose

We also talked about changing to plural coordinate - we can keep discussing if this makes sense:

• Coordinate -> Coordinates in all multi-coordinate classes
• coordinate() -> coordinates() helper function

from podpac.

• vote for capital D
• not worried about being verbose there. You can use the shortcuts, and most everyone has some sort of tab-completion in their code editor, right?
• I prefer a collective noun over a plural, like CoordinateSet or CoordinateSystem over Coordinates Either way is fine. I think we have coords as a variable all over the code, which says something :)

from podpac.

this will be closed by #84

from podpac.