XScape DataArray format

XScape relies on special Xarray DataArray objects with a very specific format. These objects can be created rather simply by using the xscp.create_xscp_da function, which will output arrays with the format described below.

Dimensions

An XScape DataArray has three dimensions: seascape_idx, ss_lon and ss_lat (and optionally ss_time and depth).

The former gives a unique index to each seascape, while the latter two index each pixel in a given seascape. Additionally, ss_lon and ss_lat will always have an odd length. This is to guarantee that there will always be a single “center pixel” in the seascape (more on this below).

When constructing a seascape with a time dimension, the same logic applies to ss_time as does to ss_lon and ss_lat.

Lastly, depth always corresponds to the full vertical dimension in the original background field from which the seascapes were taken.

Coordinates

There are six coordinates, divided into three groups:

• Center point coordinates: c_lat and c_lon, which are indexed only by seascape_idx and contain the geographical coordinates of the center pixel of the seascape.

• Relative lat/lon: ss_rlat and ss_rlon, which locate each pixel in a relative lat/lon grid where the center pixel (i.e. (c_lat°N, c_lon°W)) corresponds to (0,0).

• Absolute lat/lon: ss_lat and ss_lon, which provide the real-world location of each pixel in a seascape.

The same idea applies to the time dimension if it exists: an absolute ss_time coordinate with timestamps for each spatial field in the seascape, and a relative ss_rtime showing the time delta between each timestamp and the one closest to the point’s time.

When creating an XScape DataArray with xscp.create_xscp_da, each point in points is mapped to its closest pixel in var_da’s grid. If many points are mapped to the same pixel, XScape won’t waste resources making multiple copies of the corresponding seascape. That is why you may find that the seascape_idx dimension has a smaller length than the number of points. During the creation process no checks are made to verify that every point is actually in var_da’s grid.

When selecting a specific seascape using the xscp.ss_sel(point) method on a DataArray, XScape finds the seascape whose center pixel is the shortest distance from the specified point, and verifies that it is indeed inside the center pixel. If a point is not inside the closest seascape’s center pixel, then it means that said point does not correspond to any seascape in the DataArray, and so XScape will raise a ValueError.

Kilometric grids

Since version 0.3, there is the possibility of converting a seascape from its original lat/lon grid into a kilometric one using the xscp.to_km_grid method.

This method automatically interpolates each seascape to a grid centered on the position of the center pixel, and modifies the coordinates accordingly. Thus, the ss_lon and ss_lat coordinates are replaced by ss_x and ss_y, which point directly east and north from the point defined by c_lat and c_lon. The relative coordinates are eliminated since the kilometric grid is already relative.

The change in coordinates is also reflected in the dimension names, with ss_lon and ss_lat becoming ss_x and ss_y.