Feedback on the CRS repr

More feedback / questions … 😃

_{(as some context for this and the other issues I am opening: I am considering to use the pyproj CRS class as the actual public user end-point for working with CRSs in GeoPandas, so I am exploring their usage and usability)}

---

When having a CRS object, as a user I am mainly interested in the following questions: what is the epsg number? What is its name? In what unit is it expressed? (degrees or meters) Is this a projected or geographic CRS? What is the area of use? What is the projection being used? What is the Datum of this CRS? …

Of course, there are APIs to get all this information. And the repr should also try to be an unambiguous representation of the object and its content (from a programmer’s perspective). But it is also one of the first encounters of the end user with the object, so it would be nice to make it as user-friendly / informative as possible (which is subjective of course!).

Let’s first show an example of the current repr (for a projected CRS constructed from WKT):

>>> crs = pyproj.CRS.from_string(pyproj.CRS.from_epsg(3857).to_wkt())
>>> crs
<CRS: PROJCRS["WGS 84 / Pseudo-Mercator", BASEGEOGCRS["W ...>
Name: WGS 84 / Pseudo-Mercator
Ellipsoid:
- semi_major_metre: 6378137.00
- semi_minor_metre: 6356752.31
- inverse_flattening: 298.26
Area of Use:
- name: World - 85°S to 85°N
- bounds: (-180.0, -85.06, 180.0, 85.06)
Prime Meridian:
- longitude: 0.0000
- unit_name: degree
- unit_conversion_factor: 0.01745329
Axis Info:
- Easting[E] (east) EPSG:9001 (metre)
- Northing[N] (north) EPSG:9001 (metre)

>>> crs = pyproj.CRS.from_string(pyproj.CRS.from_epsg(31370).to_wkt())
>>> crs 
<CRS: PROJCRS["Belge 1972 / Belgian Lambert 72",BASEGEOG ...>
Name: Belge 1972 / Belgian Lambert 72
Ellipsoid:
- semi_major_metre: 6378388.00
- semi_minor_metre: 6356911.95
- inverse_flattening: 297.00
Area of Use:
- name: Belgium - onshore
- bounds: (2.5, 49.5, 6.4, 51.51)
Prime Meridian:
- longitude: 0.0000
- unit_name: degree
- unit_conversion_factor: 0.01745329
Axis Info:
- Easting[X] (east) : (metre)
- Northing[Y] (north) : (metre)

Some things I noticed during my explorations:

• It does not give me the EPSG code of the overall CRS (which can be known in this case), but it does show EPSGs for the axis info (which is less interesting IMO)
• It shows me the ellipsoid and prime meridian parameters, but not the name of the Datum (which might be more informative for a quick overview. For example for the above, I might want to know that the Pseudo-Mercator is based on the WGS84 datum, and the Belgian Lambert not) (note this is already addressed a bit in https://github.com/pyproj4/pyproj/pull/263)
• It does give me the ellipsoid and prime meridian parameters, but not the actual projection parameters (in case of a projected CRS). For example, it would be interesting to know the projection method. (this is also related to the discussion in https://github.com/pyproj4/pyproj/issues/262, eg if we would add a CoordinateOperation)
• I typically want to know the unit in which the coordinates are expressed. This is shown in the axis info, but the prime meridian also prominently shows a (different) unit. Initially this confused me, because my eye first catched the “wrong” unit.

Initially, my first thought was actually that I found the repr a bit long, but maybe it is rather that is not focusing on the information that I typically would want to check as an end-user. For example, if you look at the “Attributes” section at https://epsg.io/31370, it gives an overview of just the names of the unit, datum, ellipsoid, area of use, coordinate system, …

(To be clear, I don’t possess the truth! I just wanted to give some feedback on this, as I think this deserves some thought. And thanks for all the work on the recent changes in pyproj!)

[jorisvandenbossche]

With some further thinking, and based on what you started in the PR, some ideas.

What in the PR:

>>> pyproj.CRS.from_epsg(31370)
<CRS: epsg:31370>
Name: Belge 1972 / Belgian Lambert 72
Axis Info:
- east: Easting [EPSG:9001] (metre)
- north: Northing [EPSG:9001] (metre)
Area of Use:
- name: Belgium - onshore
- bounds: (2.5, 49.5, 6.4, 51.51)
Coordinate System:
- cartesian
Coordinate Operation:
- Belgian Lambert 72
Datum:
- Reseau National Belge 1972
Ellipsoid:
- International 1924
Prime Meridian:
- Greenwich

Further ideas:

>>> pyproj.CRS.from_epsg(31370)
<Projected CRS: epsg:31370>
Name: Belge 1972 / Belgian Lambert 72
Datum: Reseau National Belge 1972
- Ellipsoid: International 1924
- Prime Meridian: Greenwhich
Projection: Lambert Conformal Conic 2SP
Area of Use:
- name: Belgium - onshore
- bounds: (2.5, 49.5, 6.4, 51.51)
Axis Info [cartesian]:
- Easting[X] (east) (metre)
- Northing[Y] (north) (metre)

Some explanation:

• I tried to reduce somewhat the vertical space by trying to use more horizontal space (as currently it is quite long, and for quickly checking it in a terminal, or for printing in docs or tutorial, it quickly fills your screen): eg don’t use ‘-’ bullet list if there is actually not a list of items, but just a name. And added ellipsoid / prime meridian under Datum.
• I think adding the “type” of geometry somewhere in the repr would be very useful. In the example above I added in the first <> field, although it is typically the class name one puts there …
• Combined Coordinate System and Axis info (also reduces vertical space)
• I removed the EPSG for the axis info, as this is the only place where we actually add it for a subcomponent (and not the most useful one to add I think).

Further, I think it would also be nice to tweak the repr a bit depending on the type of CRS. Eg:

• For non-projected CRS (eg pyproj.CRS.from_epsg(4326)), I don’t think we should add a “undefined” Coordinate Operation, as they have none by definition
• For a Compound CRS (eg pyproj.CRS.from_epsg(3901)), it would be nice to combine the Axis info of the horizontal and vertical sub-CRS, instead of giving “undefined”.
• For CompoundCRS and BoundCRS, we might also want to more explicitly list the sub-CRSses.

Geodetic CRS is on epsg.io, thoughts on adding this to the repr as well?

Ah, maybe, specifically for projected CRS then? Although it is maybe a bit duplicative with the Datum (as the geodetic CRS is typically just a geographic CRS based on that Datum?)

---

BTW, as I said on the other PR as well. I don’t think you necessarily need to update the repr there as well (but of course, if you want, just do 😃). We can first further discuss, and afterwards do a separate PR, as I think when changing the repr in that PR you need to make quite some code changes in the tests and docs.

[snowman2]

I believe this is addressed now. If not, feel free to reopen and continue the discussion. Thanks for the ideas!