Visualizing PACE chlorophyll-a data interactively with HyperCoast¶

This notebook demonstrates how to visualize Plankton, Aerosol, Cloud, ocean Ecosystem (PACE) data interactively with HyperCoast.

In [1]:

# %pip install "hypercoast[extra]"

# %pip install "hypercoast[extra]"

In [2]:

import hypercoast

import hypercoast

To download PACE data, you will need to create an Earthdata login. You can register for an account at urs.earthdata.nasa.gov. Once you have an account, you can uncomment the code below to search and download the data.

In [3]:

# hypercoast.nasa_earth_login()
# temporal = ("2024-06-01", "2024-07-01")
# results= hypercoast.search_pace_chla(temporal=temporal)
# hypercoast.download_nasa_data(results, "chla")

# hypercoast.nasa_earth_login() # temporal = ("2024-06-01", "2024-07-01") # results= hypercoast.search_pace_chla(temporal=temporal) # hypercoast.download_nasa_data(results, "chla")

Alternatively, you can download some sample data from here.

In [4]:

url = "https://github.com/opengeos/datasets/releases/download/hypercoast/pace_chla.zip"
hypercoast.download_file(url)

url = "https://github.com/opengeos/datasets/releases/download/hypercoast/pace_chla.zip" hypercoast.download_file(url)

Out[4]:

'/home/runner/work/HyperCoast/HyperCoast/docs/examples/pace_chla.zip'

The downloaded zip file is automatically extracted and saved in the chla directory, which contains 17 daily files of chlorophyll-a concentration data in the netCDF format. The date range of the data is from 2024-06-01 to 2024-06-17.

In [5]:

files = "chla/*nc"

files = "chla/*nc"

Load all the data files in the chla directory as an xarray DataArray

In [6]:

array = hypercoast.read_pace_chla(files)
array

array = hypercoast.read_pace_chla(files) array

Out[6]:

<xarray.DataArray 'chlor_a' (lat: 1800, lon: 3600, date: 17)> Size: 441MB
dask.array<transpose, shape=(1800, 3600, 17), dtype=float32, chunksize=(512, 1024, 1), chunktype=numpy.ndarray>
Coordinates:
  * lat          (lat) float32 7kB 89.95 89.85 89.75 ... -89.75 -89.85 -89.95
  * lon          (lon) float32 14kB -179.9 -179.9 -179.8 ... 179.8 179.9 180.0
  * date         (date) <U10 680B '2024-06-01' '2024-06-02' ... '2024-06-17'
    spatial_ref  int64 8B 0
Attributes:
    long_name:      Chlorophyll Concentration, OCI Algorithm
    units:          lg(mg m^-3)
    standard_name:  mass_concentration_of_chlorophyll_in_sea_water
    valid_min:      0.001
    valid_max:      100.0
    reference:      Hu, C., Lee Z., and Franz, B.A. (2012). Chlorophyll-a alg...
    display_scale:  log
    display_min:    0.01
    display_max:    20.0
    date:           ['2024-06-01', '2024-06-02', '2024-06-03', '2024-06-04', ...

xarray.DataArray

'chlor_a'

• lat: 1800
• lon: 3600
• date: 17

• dask.array<chunksize=(512, 1024, 1), meta=np.ndarray>

  Array Chunk Bytes 420.23 MiB 2.00 MiB Shape (1800, 3600, 17) (512, 1024, 1) Dask graph 272 chunks in 54 graph layers Data type float32 numpy.ndarray

• Coordinates: (4)
  • lat
    (lat)
    float32
    89.95 89.85 89.75 ... -89.85 -89.95

    long_name :

    Latitude

    units :

    degrees_north

    standard_name :

    latitude

    valid_min :

    -90.0

    valid_max :

    90.0

    array([ 89.95    ,  89.85    ,  89.75    , ..., -89.75    , -89.850006,
           -89.950005], dtype=float32)

  • lon
    (lon)
    float32
    -179.9 -179.9 ... 179.9 180.0

    long_name :

    Longitude

    units :

    degrees_east

    standard_name :

    longitude

    valid_min :

    -180.0

    valid_max :

    180.0

    array([-179.95   , -179.85   , -179.75   , ...,  179.75   ,  179.85   ,
            179.95001], dtype=float32)

  • date
    (date)
    <U10
    '2024-06-01' ... '2024-06-17'

    array(['2024-06-01', '2024-06-02', '2024-06-03', '2024-06-04', '2024-06-05',
           '2024-06-06', '2024-06-07', '2024-06-08', '2024-06-09', '2024-06-10',
           '2024-06-11', '2024-06-12', '2024-06-13', '2024-06-14', '2024-06-15',
           '2024-06-16', '2024-06-17'], dtype='<U10')

  • spatial_ref
    ()
    int64
    0

    crs_wkt :

    GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AXIS["Latitude",NORTH],AXIS["Longitude",EAST],AUTHORITY["EPSG","4326"]]

    semi_major_axis :

    6378137.0

    semi_minor_axis :

    6356752.314245179

    inverse_flattening :

    298.257223563

    reference_ellipsoid_name :

    WGS 84

    longitude_of_prime_meridian :

    0.0

    prime_meridian_name :

    Greenwich

    geographic_crs_name :

    WGS 84

    horizontal_datum_name :

    World Geodetic System 1984

    grid_mapping_name :

    latitude_longitude

    spatial_ref :

    GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AXIS["Latitude",NORTH],AXIS["Longitude",EAST],AUTHORITY["EPSG","4326"]]

    array(0)

• Indexes: (3)
  • lat
    PandasIndex

    PandasIndex(Index([ 89.94999694824219,   89.8499984741211,              89.75,
             89.6500015258789,  89.55000305175781,  89.44999694824219,
             89.3499984741211,              89.25,   89.1500015258789,
            89.05000305175781,
           ...
           -89.05000305175781,  -89.1500015258789,             -89.25,
           -89.35000610351562, -89.45000457763672, -89.55000305175781,
            -89.6500015258789,             -89.75, -89.85000610351562,
           -89.95000457763672],
          dtype='float32', name='lat', length=1800))

  • lon
    PandasIndex

    PandasIndex(Index([ -179.9499969482422, -179.85000610351562,             -179.75,
           -179.64999389648438,  -179.5500030517578,  -179.4499969482422,
           -179.35000610351562,             -179.25, -179.14999389648438,
            -179.0500030517578,
           ...
             179.0500030517578,  179.15000915527344,              179.25,
            179.35000610351562,  179.45001220703125,   179.5500030517578,
            179.65000915527344,              179.75,  179.85000610351562,
            179.95001220703125],
          dtype='float32', name='lon', length=3600))

  • date
    PandasIndex

    PandasIndex(Index(['2024-06-01', '2024-06-02', '2024-06-03', '2024-06-04', '2024-06-05',
           '2024-06-06', '2024-06-07', '2024-06-08', '2024-06-09', '2024-06-10',
           '2024-06-11', '2024-06-12', '2024-06-13', '2024-06-14', '2024-06-15',
           '2024-06-16', '2024-06-17'],
          dtype='object', name='date'))

• Attributes: (10)

  long_name :

  Chlorophyll Concentration, OCI Algorithm

  units :

  lg(mg m^-3)

  standard_name :

  mass_concentration_of_chlorophyll_in_sea_water

  valid_min :

  0.001

  valid_max :

  100.0

  reference :

  Hu, C., Lee Z., and Franz, B.A. (2012). Chlorophyll-a algorithms for oligotrophic oceans: A novel approach based on three-band reflectance difference, J. Geophys. Res., 117, C01011, doi:10.1029/2011JC007395.

  display_scale :

  log

  display_min :

  0.01

  display_max :

  20.0

  date :

  ['2024-06-01', '2024-06-02', '2024-06-03', '2024-06-04', '2024-06-05', '2024-06-06', '2024-06-07', '2024-06-08', '2024-06-09', '2024-06-10', '2024-06-11', '2024-06-12', '2024-06-13', '2024-06-14', '2024-06-15', '2024-06-16', '2024-06-17']

Select a date and visualize the chlorophyll-a concentration data with Matplotlib.

In [7]:

hypercoast.viz_pace_chla(array, date="2024-06-01", cmap="jet", size=6)

hypercoast.viz_pace_chla(array, date="2024-06-01", cmap="jet", size=6)

Out[7]:

<matplotlib.collections.QuadMesh at 0x7f264e77be60>

If the date is not specified, the data are averaged over the entire time range.

In [8]:

hypercoast.viz_pace_chla(array, cmap="jet", size=6)

hypercoast.viz_pace_chla(array, cmap="jet", size=6)

Out[8]:

<matplotlib.collections.QuadMesh at 0x7f264e6862d0>

To visualize the data interactively, we can select either a single date or aggregate the data over a time range.

First, let's select a single date from the data array:

In [9]:

single_array = array.sel(date="2024-06-01")
single_array

single_array = array.sel(date="2024-06-01") single_array

Out[9]:

<xarray.DataArray 'chlor_a' (lat: 1800, lon: 3600)> Size: 26MB
dask.array<getitem, shape=(1800, 3600), dtype=float32, chunksize=(512, 1024), chunktype=numpy.ndarray>
Coordinates:
  * lat          (lat) float32 7kB 89.95 89.85 89.75 ... -89.75 -89.85 -89.95
  * lon          (lon) float32 14kB -179.9 -179.9 -179.8 ... 179.8 179.9 180.0
    date         <U10 40B '2024-06-01'
    spatial_ref  int64 8B 0
Attributes:
    long_name:      Chlorophyll Concentration, OCI Algorithm
    units:          lg(mg m^-3)
    standard_name:  mass_concentration_of_chlorophyll_in_sea_water
    valid_min:      0.001
    valid_max:      100.0
    reference:      Hu, C., Lee Z., and Franz, B.A. (2012). Chlorophyll-a alg...
    display_scale:  log
    display_min:    0.01
    display_max:    20.0
    date:           ['2024-06-01', '2024-06-02', '2024-06-03', '2024-06-04', ...

xarray.DataArray

'chlor_a'

• lat: 1800
• lon: 3600

• dask.array<chunksize=(512, 1024), meta=np.ndarray>

  Array Chunk Bytes 24.72 MiB 2.00 MiB Shape (1800, 3600) (512, 1024) Dask graph 16 chunks in 55 graph layers Data type float32 numpy.ndarray

• Coordinates: (4)
  • lat
    (lat)
    float32
    89.95 89.85 89.75 ... -89.85 -89.95

    long_name :

    Latitude

    units :

    degrees_north

    standard_name :

    latitude

    valid_min :

    -90.0

    valid_max :

    90.0

    array([ 89.95    ,  89.85    ,  89.75    , ..., -89.75    , -89.850006,
           -89.950005], dtype=float32)

  • lon
    (lon)
    float32
    -179.9 -179.9 ... 179.9 180.0

    long_name :

    Longitude

    units :

    degrees_east

    standard_name :

    longitude

    valid_min :

    -180.0

    valid_max :

    180.0

    array([-179.95   , -179.85   , -179.75   , ...,  179.75   ,  179.85   ,
            179.95001], dtype=float32)

  • date
    ()
    <U10
    '2024-06-01'

    array('2024-06-01', dtype='<U10')

  • spatial_ref
    ()
    int64
    0

    crs_wkt :

    GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AXIS["Latitude",NORTH],AXIS["Longitude",EAST],AUTHORITY["EPSG","4326"]]

    semi_major_axis :

    6378137.0

    semi_minor_axis :

    6356752.314245179

    inverse_flattening :

    298.257223563

    reference_ellipsoid_name :

    WGS 84

    longitude_of_prime_meridian :

    0.0

    prime_meridian_name :

    Greenwich

    geographic_crs_name :

    WGS 84

    horizontal_datum_name :

    World Geodetic System 1984

    grid_mapping_name :

    latitude_longitude

    spatial_ref :

    GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AXIS["Latitude",NORTH],AXIS["Longitude",EAST],AUTHORITY["EPSG","4326"]]

    array(0)

• Indexes: (2)
  • lat
    PandasIndex

    PandasIndex(Index([ 89.94999694824219,   89.8499984741211,              89.75,
             89.6500015258789,  89.55000305175781,  89.44999694824219,
             89.3499984741211,              89.25,   89.1500015258789,
            89.05000305175781,
           ...
           -89.05000305175781,  -89.1500015258789,             -89.25,
           -89.35000610351562, -89.45000457763672, -89.55000305175781,
            -89.6500015258789,             -89.75, -89.85000610351562,
           -89.95000457763672],
          dtype='float32', name='lat', length=1800))

  • lon
    PandasIndex

    PandasIndex(Index([ -179.9499969482422, -179.85000610351562,             -179.75,
           -179.64999389648438,  -179.5500030517578,  -179.4499969482422,
           -179.35000610351562,             -179.25, -179.14999389648438,
            -179.0500030517578,
           ...
             179.0500030517578,  179.15000915527344,              179.25,
            179.35000610351562,  179.45001220703125,   179.5500030517578,
            179.65000915527344,              179.75,  179.85000610351562,
            179.95001220703125],
          dtype='float32', name='lon', length=3600))

• Attributes: (10)

  long_name :

  Chlorophyll Concentration, OCI Algorithm

  units :

  lg(mg m^-3)

  standard_name :

  mass_concentration_of_chlorophyll_in_sea_water

  valid_min :

  0.001

  valid_max :

  100.0

  reference :

  Hu, C., Lee Z., and Franz, B.A. (2012). Chlorophyll-a algorithms for oligotrophic oceans: A novel approach based on three-band reflectance difference, J. Geophys. Res., 117, C01011, doi:10.1029/2011JC007395.

  display_scale :

  log

  display_min :

  0.01

  display_max :

  20.0

  date :

  ['2024-06-01', '2024-06-02', '2024-06-03', '2024-06-04', '2024-06-05', '2024-06-06', '2024-06-07', '2024-06-08', '2024-06-09', '2024-06-10', '2024-06-11', '2024-06-12', '2024-06-13', '2024-06-14', '2024-06-15', '2024-06-16', '2024-06-17']

Convert the data array to an image that can be displayed on an interactive map.

In [10]:

single_image = hypercoast.pace_chla_to_image(single_array)

single_image = hypercoast.pace_chla_to_image(single_array)

Create an interactive map and display the image on the map.

In [11]:

m = hypercoast.Map(center=[40, -100], zoom=4)
m.add_basemap("Hybrid")
m.add_raster(
    single_image,
    cmap="jet",
    vmin=-1,
    vmax=2,
    layer_name="Chlorophyll a",
    zoom_to_layer=False,
)
label = "Chlorophyll Concentration [lg(lg(mg m^-3))]"
m.add_colormap(cmap="jet", vmin=-1, vmax=2, label=label)
m

m = hypercoast.Map(center=[40, -100], zoom=4) m.add_basemap("Hybrid") m.add_raster( single_image, cmap="jet", vmin=-1, vmax=2, layer_name="Chlorophyll a", zoom_to_layer=False, ) label = "Chlorophyll Concentration [lg(lg(mg m^-3))]" m.add_colormap(cmap="jet", vmin=-1, vmax=2, label=label) m

Out[11]:

The daily image does not have a global coverage. To visualize the data globally, we can aggregate the data over a time range.

In [12]:

mean_array = array.mean(dim="date")

mean_array = array.mean(dim="date")

Convert the aggregated data array to an image that can be displayed on an interactive map.

In [13]:

image = hypercoast.pace_chla_to_image(mean_array)

image = hypercoast.pace_chla_to_image(mean_array)

Create an interactive map and display the image on the map.

In [14]:

m = hypercoast.Map(center=[40, -100], zoom=4)
m.add_basemap("Hybrid")
m.add_raster(
    image, cmap="jet", vmin=-1, vmax=2, layer_name="Chlorophyll a", zoom_to_layer=False
)
label = "Chlorophyll Concentration [lg(lg(mg m^-3))]"
m.add_colormap(cmap="jet", vmin=-1, vmax=2, label=label)
m

m = hypercoast.Map(center=[40, -100], zoom=4) m.add_basemap("Hybrid") m.add_raster( image, cmap="jet", vmin=-1, vmax=2, layer_name="Chlorophyll a", zoom_to_layer=False ) label = "Chlorophyll Concentration [lg(lg(mg m^-3))]" m.add_colormap(cmap="jet", vmin=-1, vmax=2, label=label) m

Out[14]: