Skip to content

Initiate a Space-Time Matrix

We implemented STM in Python as an Xarray.Dataset object. An STM instance can be initiated as an Xarray.Dataset in different ways.

STMTools provides a reader to perform lazy loading from a csv file. However, we recommend to store STM in zarr format, and directly load them as an Xarray object by xarray.open_zarr.

Manually initiate an STM

When represented by xarray.Dataset, an STM is a Dataset object with "space" and "time" dimension. It can be initiated manually, e.g.:

# Define dimension sizes
nspace = 10
ntime = 5

# Initialte STM as Dataset
stm = xr.Dataset(
    data_vars=dict(
        space_time_data=(
            ["space", "time"],
            np.arange(nspace * ntime).reshape((nspace, ntime)),
        ),
        space_data=(["space"], np.arange(nspace)),
        time_data=(["time"], np.arange(ntime)),
    ),
    coords=dict(
        x_coords=(["space"], np.arange(nspace)),
        y_coords=(["space"], np.arange(nspace)),
        time=(["time"], np.arange(ntime)),
    ),
)

stm

<xarray.Dataset>
Dimensions:          (space: 10, time: 5)
Coordinates:
    x_coords         (space) int64 0 1 2 3 4 5 6 7 8 9
    y_coords         (space) int64 0 1 2 3 4 5 6 7 8 9
  * time             (time) int64 0 1 2 3 4
Dimensions without coordinates: space
Data variables:
    space_time_data  (space, time) int64 0 1 2 3 4 5 6 ... 43 44 45 46 47 48 49
    space_data       (space) int64 0 1 2 3 4 5 6 7 8 9
    time_data        (time) int64 0 1 2 3 4

From a Zarr storage

If an STM is stored in .zarr format, it can be read by the xarray.open_zarr funtcion:

stm = xr.open_zarr('./stm.zarr')

From csv file

STM can also be intiated from a csv file. During this process, the following assumptions are made to the column names of the csv file:

  1. All columns with space-only attributes share the same Regular Expression (RE) pattern in the column names. E.g. Latitude, Longitude and height columns are named as "pnt_lat", "pnt_lon" and "pnt_height", sharing the same RE pattern "^pnt_";
  2. Per space-time attribute, a common RE pattern is shared by all columns. E.g. for the time-series of amplitude data, the column names are "amp_20100101", "amp_20100110", "amp_20100119" ..., where "^amp_" is the common RE pattern;
  3. There is no temporal-only (i.e. 1-row attribute) attribute present in the csv file.

Consider the example csv data. It can be loaded by from_csv:

import stmtools
stm = stmtools.from_csv('example.csv')

<xarray.Dataset>
Dimensions:                (space: 2500, time: 11)
Coordinates:
  * space                  (space) int64 0 1 2 3 4 ... 2495 2496 2497 2498 2499
  * time                   (time) datetime64[ns] 2016-03-27 ... 2016-07-15
    lat                    (space) float64 dask.array<chunksize=(2500,), meta=np.ndarray>
    lon                    (space) float64 dask.array<chunksize=(2500,), meta=np.ndarray>
Data variables: (12/13)
    pnt_id                 (space) <U1 dask.array<chunksize=(2500,), meta=np.ndarray>
    pnt_flags              (space) int64 dask.array<chunksize=(2500,), meta=np.ndarray>
    pnt_line               (space) int64 dask.array<chunksize=(2500,), meta=np.ndarray>
    pnt_pixel              (space) int64 dask.array<chunksize=(2500,), meta=np.ndarray>
    pnt_height             (space) float64 dask.array<chunksize=(2500,), meta=np.ndarray>
    pnt_demheight          (space) float64 dask.array<chunksize=(2500,), meta=np.ndarray>
    ...                     ...
    pnt_enscoh             (space) float64 dask.array<chunksize=(2500,), meta=np.ndarray>
    pnt_ampconsist         (space) float64 dask.array<chunksize=(2500,), meta=np.ndarray>
    pnt_linear             (space) float64 dask.array<chunksize=(2500,), meta=np.ndarray>
    deformation            (space, time) float64 dask.array<chunksize=(2500, 11), meta=np.ndarray>
    amplitude              (space, time) float64 dask.array<chunksize=(2500, 11), meta=np.ndarray>
    h2ph                   (space, time) float64 dask.array<chunksize=(2500, 11), meta=np.ndarray>

By pixel selection from an image stack

An STM can also be generated by selecting pixels from an SLC stack or interferogram stack. An example of the selection is the point_selection implementation of sarxarray.