Introduction to Xarray

Before we get started, you may choose to run this notebook on LEAP-Pangeo hub or Binder!

Xarray is an open source Python package designed to work with lablled multidimensional arrays in an efficient manner. By multidimensional data (also often called N-dimensional), we mean data with many independent dimensions or axes. For example, we might represent Earth’s surface temperature \(T\) as a three dimensional variable:

\[\begin{equation*} T(x,y,t) \end{equation*}\]

where \(x\) and \(y\) are spatial dimensions and \(t\) is time. By labeled, we mean data that has metadata associated with it describing the names and relationships between the variables.

Example of multidimensional data processing using Xarray:

!wget -O ./dataset.nc https://github.com/pangeo-data/tutorial-data/raw/master/sst/NOAA_NCDC_ERSST_v3b_SST-1960.nc

--2024-11-14 15:13:32--  https://github.com/pangeo-data/tutorial-data/raw/master/sst/NOAA_NCDC_ERSST_v3b_SST-1960.nc
Resolving github.com (github.com)... 140.82.113.3
Connecting to github.com (github.com)|140.82.113.3|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://raw.githubusercontent.com/pangeo-data/tutorial-data/master/sst/NOAA_NCDC_ERSST_v3b_SST-1960.nc [following]
--2024-11-14 15:13:33--  https://raw.githubusercontent.com/pangeo-data/tutorial-data/master/sst/NOAA_NCDC_ERSST_v3b_SST-1960.nc
Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 185.199.109.133, 185.199.111.133, 185.199.110.133, ...
Connecting to raw.githubusercontent.com (raw.githubusercontent.com)|185.199.109.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 785127 (767K) [application/octet-stream]
Saving to: ‘./dataset.nc’

./dataset.nc        100%[===================>] 766.73K  --.-KB/s    in 0.008s  

2024-11-14 15:13:33 (98.4 MB/s) - ‘./dataset.nc’ saved [785127/785127]

import xarray as xr

ds = xr.open_dataset("dataset.nc")
ds

<xarray.Dataset>
Dimensions:  (lat: 89, lon: 180, time: 12)
Coordinates:
  * lat      (lat) float32 -88.0 -86.0 -84.0 -82.0 -80.0 ... 82.0 84.0 86.0 88.0
  * lon      (lon) float32 0.0 2.0 4.0 6.0 8.0 ... 350.0 352.0 354.0 356.0 358.0
  * time     (time) datetime64[ns] 1960-01-15 1960-02-15 ... 1960-12-15
Data variables:
    sst      (time, lat, lon) float32 ...
Attributes:
    Conventions:  IRIDL
    source:       https://iridl.ldeo.columbia.edu/SOURCES/.NOAA/.NCDC/.ERSST/...
    history:      extracted and cleaned by Ryan Abernathey for Research Compu...

xarray.Dataset

• Dimensions:
  • lat: 89
  • lon: 180
  • time: 12
• Coordinates: (3)
  • lat
    (lat)
    float32
    -88.0 -86.0 -84.0 ... 86.0 88.0

    standard_name :

    latitude

    pointwidth :

    2.0

    gridtype :

    0

    units :

    degree_north

    array([-88., -86., -84., -82., -80., -78., -76., -74., -72., -70., -68., -66.,
           -64., -62., -60., -58., -56., -54., -52., -50., -48., -46., -44., -42.,
           -40., -38., -36., -34., -32., -30., -28., -26., -24., -22., -20., -18.,
           -16., -14., -12., -10.,  -8.,  -6.,  -4.,  -2.,   0.,   2.,   4.,   6.,
             8.,  10.,  12.,  14.,  16.,  18.,  20.,  22.,  24.,  26.,  28.,  30.,
            32.,  34.,  36.,  38.,  40.,  42.,  44.,  46.,  48.,  50.,  52.,  54.,
            56.,  58.,  60.,  62.,  64.,  66.,  68.,  70.,  72.,  74.,  76.,  78.,
            80.,  82.,  84.,  86.,  88.], dtype=float32)

  • lon
    (lon)
    float32
    0.0 2.0 4.0 ... 354.0 356.0 358.0

    standard_name :

    longitude

    pointwidth :

    2.0

    gridtype :

    1

    units :

    degree_east

    array([  0.,   2.,   4.,   6.,   8.,  10.,  12.,  14.,  16.,  18.,  20.,  22.,
            24.,  26.,  28.,  30.,  32.,  34.,  36.,  38.,  40.,  42.,  44.,  46.,
            48.,  50.,  52.,  54.,  56.,  58.,  60.,  62.,  64.,  66.,  68.,  70.,
            72.,  74.,  76.,  78.,  80.,  82.,  84.,  86.,  88.,  90.,  92.,  94.,
            96.,  98., 100., 102., 104., 106., 108., 110., 112., 114., 116., 118.,
           120., 122., 124., 126., 128., 130., 132., 134., 136., 138., 140., 142.,
           144., 146., 148., 150., 152., 154., 156., 158., 160., 162., 164., 166.,
           168., 170., 172., 174., 176., 178., 180., 182., 184., 186., 188., 190.,
           192., 194., 196., 198., 200., 202., 204., 206., 208., 210., 212., 214.,
           216., 218., 220., 222., 224., 226., 228., 230., 232., 234., 236., 238.,
           240., 242., 244., 246., 248., 250., 252., 254., 256., 258., 260., 262.,
           264., 266., 268., 270., 272., 274., 276., 278., 280., 282., 284., 286.,
           288., 290., 292., 294., 296., 298., 300., 302., 304., 306., 308., 310.,
           312., 314., 316., 318., 320., 322., 324., 326., 328., 330., 332., 334.,
           336., 338., 340., 342., 344., 346., 348., 350., 352., 354., 356., 358.],
          dtype=float32)

  • time
    (time)
    datetime64[ns]
    1960-01-15 ... 1960-12-15

    array(['1960-01-15T00:00:00.000000000', '1960-02-15T00:00:00.000000000',
           '1960-03-15T00:00:00.000000000', '1960-04-15T00:00:00.000000000',
           '1960-05-15T00:00:00.000000000', '1960-06-15T00:00:00.000000000',
           '1960-07-15T00:00:00.000000000', '1960-08-15T00:00:00.000000000',
           '1960-09-15T00:00:00.000000000', '1960-10-15T00:00:00.000000000',
           '1960-11-15T00:00:00.000000000', '1960-12-15T00:00:00.000000000'],
          dtype='datetime64[ns]')

• Data variables: (1)
  • sst
    (time, lat, lon)
    float32
    ...

    pointwidth :

    1.0

    valid_min :

    -3.0

    valid_max :

    45.0

    units :

    degree_Celsius

    long_name :

    Extended reconstructed sea surface temperature

    standard_name :

    sea_surface_temperature

    iridl:hasSemantics :

    iridl:SeaSurfaceTemperature

    [192240 values with dtype=float32]

• Indexes: (3)
  • lat
    PandasIndex

    PandasIndex(Index([-88.0, -86.0, -84.0, -82.0, -80.0, -78.0, -76.0, -74.0, -72.0, -70.0,
           -68.0, -66.0, -64.0, -62.0, -60.0, -58.0, -56.0, -54.0, -52.0, -50.0,
           -48.0, -46.0, -44.0, -42.0, -40.0, -38.0, -36.0, -34.0, -32.0, -30.0,
           -28.0, -26.0, -24.0, -22.0, -20.0, -18.0, -16.0, -14.0, -12.0, -10.0,
            -8.0,  -6.0,  -4.0,  -2.0,   0.0,   2.0,   4.0,   6.0,   8.0,  10.0,
            12.0,  14.0,  16.0,  18.0,  20.0,  22.0,  24.0,  26.0,  28.0,  30.0,
            32.0,  34.0,  36.0,  38.0,  40.0,  42.0,  44.0,  46.0,  48.0,  50.0,
            52.0,  54.0,  56.0,  58.0,  60.0,  62.0,  64.0,  66.0,  68.0,  70.0,
            72.0,  74.0,  76.0,  78.0,  80.0,  82.0,  84.0,  86.0,  88.0],
          dtype='float32', name='lat'))

  • lon
    PandasIndex

    PandasIndex(Index([  0.0,   2.0,   4.0,   6.0,   8.0,  10.0,  12.0,  14.0,  16.0,  18.0,
           ...
           340.0, 342.0, 344.0, 346.0, 348.0, 350.0, 352.0, 354.0, 356.0, 358.0],
          dtype='float32', name='lon', length=180))

  • time
    PandasIndex

    PandasIndex(DatetimeIndex(['1960-01-15', '1960-02-15', '1960-03-15', '1960-04-15',
                   '1960-05-15', '1960-06-15', '1960-07-15', '1960-08-15',
                   '1960-09-15', '1960-10-15', '1960-11-15', '1960-12-15'],
                  dtype='datetime64[ns]', name='time', freq=None))

• Attributes: (3)

  Conventions :

  IRIDL

  source :

  https://iridl.ldeo.columbia.edu/SOURCES/.NOAA/.NCDC/.ERSST/.version3b/.sst/

  history :

  extracted and cleaned by Ryan Abernathey for Research Computing in Earth Science

Data Structures

Like Pandas, xarray has two fundamental data structures: a DataArray, which holds a single multi-dimensional variable and its coordinates a Dataset, which holds multiple variables that potentially share the same coordinates

A DataArray has four essential attributes: * values: a numpy.ndarray holding the array’s values dims: dimension names for each axis (e.g., ('x', 'y', 'z')), coords: a dict-like container of arrays (coordinates) that label each point (e.g., 1-dimensional arrays of numbers, datetime objects or strings) attrs: an OrderedDict to hold arbitrary metadata (attributes)

A dataset is simply an object containing multiple DataArrays indexed by variable name.

xr.set_options(display_style="html")
ds

<xarray.Dataset>
Dimensions:  (lat: 89, lon: 180, time: 12)
Coordinates:
  * lat      (lat) float32 -88.0 -86.0 -84.0 -82.0 -80.0 ... 82.0 84.0 86.0 88.0
  * lon      (lon) float32 0.0 2.0 4.0 6.0 8.0 ... 350.0 352.0 354.0 356.0 358.0
  * time     (time) datetime64[ns] 1960-01-15 1960-02-15 ... 1960-12-15
Data variables:
    sst      (time, lat, lon) float32 ...
Attributes:
    Conventions:  IRIDL
    source:       https://iridl.ldeo.columbia.edu/SOURCES/.NOAA/.NCDC/.ERSST/...
    history:      extracted and cleaned by Ryan Abernathey for Research Compu...

xarray.Dataset

• Dimensions:
  • lat: 89
  • lon: 180
  • time: 12
• Coordinates: (3)
  • lat
    (lat)
    float32
    -88.0 -86.0 -84.0 ... 86.0 88.0

    standard_name :

    latitude

    pointwidth :

    2.0

    gridtype :

    0

    units :

    degree_north

    array([-88., -86., -84., -82., -80., -78., -76., -74., -72., -70., -68., -66.,
           -64., -62., -60., -58., -56., -54., -52., -50., -48., -46., -44., -42.,
           -40., -38., -36., -34., -32., -30., -28., -26., -24., -22., -20., -18.,
           -16., -14., -12., -10.,  -8.,  -6.,  -4.,  -2.,   0.,   2.,   4.,   6.,
             8.,  10.,  12.,  14.,  16.,  18.,  20.,  22.,  24.,  26.,  28.,  30.,
            32.,  34.,  36.,  38.,  40.,  42.,  44.,  46.,  48.,  50.,  52.,  54.,
            56.,  58.,  60.,  62.,  64.,  66.,  68.,  70.,  72.,  74.,  76.,  78.,
            80.,  82.,  84.,  86.,  88.], dtype=float32)

  • lon
    (lon)
    float32
    0.0 2.0 4.0 ... 354.0 356.0 358.0

    standard_name :

    longitude

    pointwidth :

    2.0

    gridtype :

    1

    units :

    degree_east

    array([  0.,   2.,   4.,   6.,   8.,  10.,  12.,  14.,  16.,  18.,  20.,  22.,
            24.,  26.,  28.,  30.,  32.,  34.,  36.,  38.,  40.,  42.,  44.,  46.,
            48.,  50.,  52.,  54.,  56.,  58.,  60.,  62.,  64.,  66.,  68.,  70.,
            72.,  74.,  76.,  78.,  80.,  82.,  84.,  86.,  88.,  90.,  92.,  94.,
            96.,  98., 100., 102., 104., 106., 108., 110., 112., 114., 116., 118.,
           120., 122., 124., 126., 128., 130., 132., 134., 136., 138., 140., 142.,
           144., 146., 148., 150., 152., 154., 156., 158., 160., 162., 164., 166.,
           168., 170., 172., 174., 176., 178., 180., 182., 184., 186., 188., 190.,
           192., 194., 196., 198., 200., 202., 204., 206., 208., 210., 212., 214.,
           216., 218., 220., 222., 224., 226., 228., 230., 232., 234., 236., 238.,
           240., 242., 244., 246., 248., 250., 252., 254., 256., 258., 260., 262.,
           264., 266., 268., 270., 272., 274., 276., 278., 280., 282., 284., 286.,
           288., 290., 292., 294., 296., 298., 300., 302., 304., 306., 308., 310.,
           312., 314., 316., 318., 320., 322., 324., 326., 328., 330., 332., 334.,
           336., 338., 340., 342., 344., 346., 348., 350., 352., 354., 356., 358.],
          dtype=float32)

  • time
    (time)
    datetime64[ns]
    1960-01-15 ... 1960-12-15

    array(['1960-01-15T00:00:00.000000000', '1960-02-15T00:00:00.000000000',
           '1960-03-15T00:00:00.000000000', '1960-04-15T00:00:00.000000000',
           '1960-05-15T00:00:00.000000000', '1960-06-15T00:00:00.000000000',
           '1960-07-15T00:00:00.000000000', '1960-08-15T00:00:00.000000000',
           '1960-09-15T00:00:00.000000000', '1960-10-15T00:00:00.000000000',
           '1960-11-15T00:00:00.000000000', '1960-12-15T00:00:00.000000000'],
          dtype='datetime64[ns]')

• Data variables: (1)
  • sst
    (time, lat, lon)
    float32
    ...

    pointwidth :

    1.0

    valid_min :

    -3.0

    valid_max :

    45.0

    units :

    degree_Celsius

    long_name :

    Extended reconstructed sea surface temperature

    standard_name :

    sea_surface_temperature

    iridl:hasSemantics :

    iridl:SeaSurfaceTemperature

    [192240 values with dtype=float32]

• Indexes: (3)
  • lat
    PandasIndex

    PandasIndex(Index([-88.0, -86.0, -84.0, -82.0, -80.0, -78.0, -76.0, -74.0, -72.0, -70.0,
           -68.0, -66.0, -64.0, -62.0, -60.0, -58.0, -56.0, -54.0, -52.0, -50.0,
           -48.0, -46.0, -44.0, -42.0, -40.0, -38.0, -36.0, -34.0, -32.0, -30.0,
           -28.0, -26.0, -24.0, -22.0, -20.0, -18.0, -16.0, -14.0, -12.0, -10.0,
            -8.0,  -6.0,  -4.0,  -2.0,   0.0,   2.0,   4.0,   6.0,   8.0,  10.0,
            12.0,  14.0,  16.0,  18.0,  20.0,  22.0,  24.0,  26.0,  28.0,  30.0,
            32.0,  34.0,  36.0,  38.0,  40.0,  42.0,  44.0,  46.0,  48.0,  50.0,
            52.0,  54.0,  56.0,  58.0,  60.0,  62.0,  64.0,  66.0,  68.0,  70.0,
            72.0,  74.0,  76.0,  78.0,  80.0,  82.0,  84.0,  86.0,  88.0],
          dtype='float32', name='lat'))

  • lon
    PandasIndex

    PandasIndex(Index([  0.0,   2.0,   4.0,   6.0,   8.0,  10.0,  12.0,  14.0,  16.0,  18.0,
           ...
           340.0, 342.0, 344.0, 346.0, 348.0, 350.0, 352.0, 354.0, 356.0, 358.0],
          dtype='float32', name='lon', length=180))

  • time
    PandasIndex

    PandasIndex(DatetimeIndex(['1960-01-15', '1960-02-15', '1960-03-15', '1960-04-15',
                   '1960-05-15', '1960-06-15', '1960-07-15', '1960-08-15',
                   '1960-09-15', '1960-10-15', '1960-11-15', '1960-12-15'],
                  dtype='datetime64[ns]', name='time', freq=None))

• Attributes: (3)

  Conventions :

  IRIDL

  source :

  https://iridl.ldeo.columbia.edu/SOURCES/.NOAA/.NCDC/.ERSST/.version3b/.sst/

  history :

  extracted and cleaned by Ryan Abernathey for Research Computing in Earth Science

# attribute syntax
sst = ds.sst  # or sst = ds['sst']

sst

<xarray.DataArray 'sst' (time: 12, lat: 89, lon: 180)>
[192240 values with dtype=float32]
Coordinates:
  * lat      (lat) float32 -88.0 -86.0 -84.0 -82.0 -80.0 ... 82.0 84.0 86.0 88.0
  * lon      (lon) float32 0.0 2.0 4.0 6.0 8.0 ... 350.0 352.0 354.0 356.0 358.0
  * time     (time) datetime64[ns] 1960-01-15 1960-02-15 ... 1960-12-15
Attributes:
    pointwidth:          1.0
    valid_min:           -3.0
    valid_max:           45.0
    units:               degree_Celsius
    long_name:           Extended reconstructed sea surface temperature
    standard_name:       sea_surface_temperature
    iridl:hasSemantics:  iridl:SeaSurfaceTemperature

xarray.DataArray

'sst'

• time: 12
• lat: 89
• lon: 180

• ...

  [192240 values with dtype=float32]

• Coordinates: (3)
  • lat
    (lat)
    float32
    -88.0 -86.0 -84.0 ... 86.0 88.0

    standard_name :

    latitude

    pointwidth :

    2.0

    gridtype :

    0

    units :

    degree_north

    array([-88., -86., -84., -82., -80., -78., -76., -74., -72., -70., -68., -66.,
           -64., -62., -60., -58., -56., -54., -52., -50., -48., -46., -44., -42.,
           -40., -38., -36., -34., -32., -30., -28., -26., -24., -22., -20., -18.,
           -16., -14., -12., -10.,  -8.,  -6.,  -4.,  -2.,   0.,   2.,   4.,   6.,
             8.,  10.,  12.,  14.,  16.,  18.,  20.,  22.,  24.,  26.,  28.,  30.,
            32.,  34.,  36.,  38.,  40.,  42.,  44.,  46.,  48.,  50.,  52.,  54.,
            56.,  58.,  60.,  62.,  64.,  66.,  68.,  70.,  72.,  74.,  76.,  78.,
            80.,  82.,  84.,  86.,  88.], dtype=float32)

  • lon
    (lon)
    float32
    0.0 2.0 4.0 ... 354.0 356.0 358.0

    standard_name :

    longitude

    pointwidth :

    2.0

    gridtype :

    1

    units :

    degree_east

    array([  0.,   2.,   4.,   6.,   8.,  10.,  12.,  14.,  16.,  18.,  20.,  22.,
            24.,  26.,  28.,  30.,  32.,  34.,  36.,  38.,  40.,  42.,  44.,  46.,
            48.,  50.,  52.,  54.,  56.,  58.,  60.,  62.,  64.,  66.,  68.,  70.,
            72.,  74.,  76.,  78.,  80.,  82.,  84.,  86.,  88.,  90.,  92.,  94.,
            96.,  98., 100., 102., 104., 106., 108., 110., 112., 114., 116., 118.,
           120., 122., 124., 126., 128., 130., 132., 134., 136., 138., 140., 142.,
           144., 146., 148., 150., 152., 154., 156., 158., 160., 162., 164., 166.,
           168., 170., 172., 174., 176., 178., 180., 182., 184., 186., 188., 190.,
           192., 194., 196., 198., 200., 202., 204., 206., 208., 210., 212., 214.,
           216., 218., 220., 222., 224., 226., 228., 230., 232., 234., 236., 238.,
           240., 242., 244., 246., 248., 250., 252., 254., 256., 258., 260., 262.,
           264., 266., 268., 270., 272., 274., 276., 278., 280., 282., 284., 286.,
           288., 290., 292., 294., 296., 298., 300., 302., 304., 306., 308., 310.,
           312., 314., 316., 318., 320., 322., 324., 326., 328., 330., 332., 334.,
           336., 338., 340., 342., 344., 346., 348., 350., 352., 354., 356., 358.],
          dtype=float32)

  • time
    (time)
    datetime64[ns]
    1960-01-15 ... 1960-12-15

    array(['1960-01-15T00:00:00.000000000', '1960-02-15T00:00:00.000000000',
           '1960-03-15T00:00:00.000000000', '1960-04-15T00:00:00.000000000',
           '1960-05-15T00:00:00.000000000', '1960-06-15T00:00:00.000000000',
           '1960-07-15T00:00:00.000000000', '1960-08-15T00:00:00.000000000',
           '1960-09-15T00:00:00.000000000', '1960-10-15T00:00:00.000000000',
           '1960-11-15T00:00:00.000000000', '1960-12-15T00:00:00.000000000'],
          dtype='datetime64[ns]')

• Indexes: (3)
  • lat
    PandasIndex

    PandasIndex(Index([-88.0, -86.0, -84.0, -82.0, -80.0, -78.0, -76.0, -74.0, -72.0, -70.0,
           -68.0, -66.0, -64.0, -62.0, -60.0, -58.0, -56.0, -54.0, -52.0, -50.0,
           -48.0, -46.0, -44.0, -42.0, -40.0, -38.0, -36.0, -34.0, -32.0, -30.0,
           -28.0, -26.0, -24.0, -22.0, -20.0, -18.0, -16.0, -14.0, -12.0, -10.0,
            -8.0,  -6.0,  -4.0,  -2.0,   0.0,   2.0,   4.0,   6.0,   8.0,  10.0,
            12.0,  14.0,  16.0,  18.0,  20.0,  22.0,  24.0,  26.0,  28.0,  30.0,
            32.0,  34.0,  36.0,  38.0,  40.0,  42.0,  44.0,  46.0,  48.0,  50.0,
            52.0,  54.0,  56.0,  58.0,  60.0,  62.0,  64.0,  66.0,  68.0,  70.0,
            72.0,  74.0,  76.0,  78.0,  80.0,  82.0,  84.0,  86.0,  88.0],
          dtype='float32', name='lat'))

  • lon
    PandasIndex

    PandasIndex(Index([  0.0,   2.0,   4.0,   6.0,   8.0,  10.0,  12.0,  14.0,  16.0,  18.0,
           ...
           340.0, 342.0, 344.0, 346.0, 348.0, 350.0, 352.0, 354.0, 356.0, 358.0],
          dtype='float32', name='lon', length=180))

  • time
    PandasIndex

    PandasIndex(DatetimeIndex(['1960-01-15', '1960-02-15', '1960-03-15', '1960-04-15',
                   '1960-05-15', '1960-06-15', '1960-07-15', '1960-08-15',
                   '1960-09-15', '1960-10-15', '1960-11-15', '1960-12-15'],
                  dtype='datetime64[ns]', name='time', freq=None))

• Attributes: (7)

  pointwidth :

  1.0

  valid_min :

  -3.0

  valid_max :

  45.0

  units :

  degree_Celsius

  long_name :

  Extended reconstructed sea surface temperature

  standard_name :

  sea_surface_temperature

  iridl:hasSemantics :

  iridl:SeaSurfaceTemperature

Indexing

sst.sel(time="1960-06-15").plot(vmin=-2, vmax=30);

We can select along any axis

sst.sel(lon=180).transpose().plot();

sst.sel(lon=180, lat=40).plot();