Source Tutorial¶

This tutorial covers the Source classes in rompy-xbeach, which provide a unified interface for loading data from various file formats and sources.

What You'll Learn¶

1. Understanding the source abstraction
2. Loading data from NetCDF files (SourceCRSFile)
3. Loading data from Intake catalogs (SourceCRSIntake)
4. Using in-memory xarray datasets (SourceCRSDataset)
5. Loading GeoTIFF files (SourceGeotiff)
6. Loading XYZ point cloud data (SourceXYZ)

Prerequisites¶

• Basic understanding of xarray and coordinate reference systems (CRS)

In [1]:

import warnings
warnings.filterwarnings("ignore")

import warnings warnings.filterwarnings("ignore")

---

1. The Source Abstraction¶

Source objects in rompy-xbeach extend the core sources from rompy with CRS support. The key requirement is that the _open() method returns an xarray Dataset with:

• The rio accessor available (via rioxarray)
• The crs attribute set

This ensures all data has consistent spatial reference information for interpolation onto the XBeach grid.

Available Source Types¶

Source Class	Use Case
SourceCRSFile	NetCDF, Zarr, or other xarray-compatible files
SourceCRSIntake	Data from Intake catalogs
SourceCRSDataset	In-memory xarray Dataset objects
SourceGeotiff	GeoTIFF raster files (CRS auto-detected)
SourceXYZ	XYZ point cloud / CSV files

---

2. SourceCRSFile¶

Load data from any file format supported by xarray (NetCDF, Zarr, etc.). You must specify the CRS since NetCDF files typically don't embed it.

In [2]:

from pathlib import Path

# Change the data directory to the location in your computer where rompy-xbeach is cloned into
DATADIR = Path("../../../../rompy-xbeach/tests/data")

from pathlib import Path # Change the data directory to the location in your computer where rompy-xbeach is cloned into DATADIR = Path("../../../../rompy-xbeach/tests/data")

In [3]:

from rompy_xbeach.source import SourceCRSFile

source = SourceCRSFile(
    uri=DATADIR / "bathy.nc",
    kwargs=dict(engine="netcdf4"),  # xarray.open_dataset kwargs
    crs="EPSG:4326",                # Coordinate reference system
    x_dim="x",                      # Name of x dimension
    y_dim="y",                      # Name of y dimension
)

# Open the dataset
ds = source._open()
ds

from rompy_xbeach.source import SourceCRSFile source = SourceCRSFile( uri=DATADIR / "bathy.nc", kwargs=dict(engine="netcdf4"), # xarray.open_dataset kwargs crs="EPSG:4326", # Coordinate reference system x_dim="x", # Name of x dimension y_dim="y", # Name of y dimension ) # Open the dataset ds = source._open() ds

Out[3]:

<xarray.Dataset> Size: 130kB
Dimensions:  (y: 180, x: 176)
Coordinates:
  * y        (y) float64 1kB -32.65 -32.65 -32.65 ... -32.61 -32.61 -32.61
  * x        (x) float64 1kB 115.6 115.6 115.6 115.6 ... 115.6 115.6 115.6 115.6
Data variables:
    depth    (y, x) float32 127kB ...

xarray.Dataset

• Dimensions:
  • y: 180
  • x: 176
• Coordinates: (2)
  • y
    (y)
    float64
    -32.65 -32.65 ... -32.61 -32.61

    array([-32.648301, -32.648087, -32.647874, -32.64766 , -32.647447, -32.647233,
           -32.64702 , -32.646806, -32.646593, -32.646379, -32.646166, -32.645952,
           -32.645739, -32.645525, -32.645312, -32.645098, -32.644885, -32.644671,
           -32.644458, -32.644244, -32.644031, -32.643817, -32.643604, -32.64339 ,
           -32.643177, -32.642963, -32.64275 , -32.642536, -32.642323, -32.642109,
           -32.641896, -32.641682, -32.641469, -32.641255, -32.641042, -32.640828,
           -32.640615, -32.640401, -32.640188, -32.639974, -32.639761, -32.639547,
           -32.639334, -32.63912 , -32.638907, -32.638693, -32.63848 , -32.638266,
           -32.638053, -32.637839, -32.637626, -32.637412, -32.637199, -32.636985,
           -32.636772, -32.636558, -32.636345, -32.636131, -32.635918, -32.635704,
           -32.635491, -32.635277, -32.635064, -32.63485 , -32.634637, -32.634423,
           -32.63421 , -32.633996, -32.633783, -32.633569, -32.633356, -32.633142,
           -32.632929, -32.632715, -32.632502, -32.632288, -32.632075, -32.631861,
           -32.631648, -32.631434, -32.631221, -32.631007, -32.630794, -32.63058 ,
           -32.630367, -32.630153, -32.62994 , -32.629726, -32.629513, -32.629299,
           -32.629086, -32.628872, -32.628659, -32.628445, -32.628232, -32.628018,
           -32.627805, -32.627591, -32.627378, -32.627164, -32.626951, -32.626737,
           -32.626524, -32.62631 , -32.626097, -32.625883, -32.62567 , -32.625456,
           -32.625243, -32.625029, -32.624816, -32.624602, -32.624389, -32.624175,
           -32.623962, -32.623748, -32.623535, -32.623321, -32.623108, -32.622894,
           -32.622681, -32.622467, -32.622254, -32.62204 , -32.621827, -32.621613,
           -32.6214  , -32.621186, -32.620973, -32.620759, -32.620546, -32.620332,
           -32.620119, -32.619905, -32.619692, -32.619478, -32.619265, -32.619051,
           -32.618838, -32.618624, -32.618411, -32.618197, -32.617984, -32.61777 ,
           -32.617557, -32.617343, -32.61713 , -32.616916, -32.616703, -32.616489,
           -32.616276, -32.616062, -32.615849, -32.615635, -32.615422, -32.615208,
           -32.614995, -32.614781, -32.614568, -32.614354, -32.614141, -32.613927,
           -32.613714, -32.6135  , -32.613287, -32.613073, -32.61286 , -32.612646,
           -32.612433, -32.612219, -32.612006, -32.611792, -32.611579, -32.611365,
           -32.611152, -32.610938, -32.610725, -32.610511, -32.610298, -32.610084])

  • x
    (x)
    float64
    115.6 115.6 115.6 ... 115.6 115.6

    array([115.591525, 115.591739, 115.591952, 115.592166, 115.592379, 115.592593,
           115.592806, 115.59302 , 115.593233, 115.593447, 115.59366 , 115.593874,
           115.594087, 115.594301, 115.594514, 115.594728, 115.594941, 115.595155,
           115.595368, 115.595582, 115.595795, 115.596009, 115.596222, 115.596436,
           115.596649, 115.596863, 115.597076, 115.59729 , 115.597503, 115.597717,
           115.59793 , 115.598144, 115.598357, 115.598571, 115.598784, 115.598998,
           115.599211, 115.599425, 115.599638, 115.599852, 115.600065, 115.600279,
           115.600492, 115.600706, 115.600919, 115.601133, 115.601346, 115.60156 ,
           115.601773, 115.601987, 115.6022  , 115.602414, 115.602627, 115.602841,
           115.603054, 115.603268, 115.603481, 115.603695, 115.603908, 115.604122,
           115.604335, 115.604549, 115.604762, 115.604976, 115.605189, 115.605403,
           115.605616, 115.60583 , 115.606043, 115.606257, 115.60647 , 115.606684,
           115.606897, 115.607111, 115.607324, 115.607538, 115.607751, 115.607965,
           115.608178, 115.608392, 115.608605, 115.608819, 115.609032, 115.609246,
           115.609459, 115.609673, 115.609886, 115.6101  , 115.610313, 115.610527,
           115.61074 , 115.610954, 115.611167, 115.611381, 115.611594, 115.611808,
           115.612021, 115.612235, 115.612448, 115.612662, 115.612875, 115.613089,
           115.613302, 115.613516, 115.613729, 115.613943, 115.614156, 115.61437 ,
           115.614583, 115.614797, 115.61501 , 115.615224, 115.615437, 115.615651,
           115.615864, 115.616078, 115.616291, 115.616505, 115.616718, 115.616932,
           115.617145, 115.617359, 115.617572, 115.617786, 115.617999, 115.618213,
           115.618426, 115.61864 , 115.618853, 115.619067, 115.61928 , 115.619494,
           115.619707, 115.619921, 115.620134, 115.620348, 115.620561, 115.620775,
           115.620988, 115.621202, 115.621415, 115.621629, 115.621842, 115.622056,
           115.622269, 115.622483, 115.622696, 115.62291 , 115.623123, 115.623337,
           115.62355 , 115.623764, 115.623977, 115.624191, 115.624404, 115.624618,
           115.624831, 115.625045, 115.625258, 115.625472, 115.625685, 115.625899,
           115.626112, 115.626326, 115.626539, 115.626753, 115.626966, 115.62718 ,
           115.627393, 115.627607, 115.62782 , 115.628034, 115.628247, 115.628461,
           115.628674, 115.628888])

• Data variables: (1)
  • depth
    (y, x)
    float32
    ...

    AREA_OR_POINT :

    Area

    [31680 values with dtype=float32]

In [4]:

# Verify CRS is set
print(f"CRS: {source.crs}")

# Verify CRS is set print(f"CRS: {source.crs}")

CRS: EPSG:4326

Key Parameters¶

Parameter	Description
uri	Path to the file
kwargs	Arguments passed to xarray.open_dataset()
crs	Coordinate reference system (EPSG code or WKT)
x_dim, y_dim	Names of the spatial dimensions

---

3. SourceCRSIntake¶

Load data from an Intake catalog. Useful for managing multiple datasets with metadata.

In [5]:

from rompy_xbeach.source import SourceCRSIntake

source = SourceCRSIntake(
    catalog_uri=DATADIR / "catalog.yaml",
    dataset_id="bathy_netcdf",
    crs="EPSG:4326",
)

ds = source._open()
print(f"Loaded dataset with variables: {list(ds.data_vars)}")

from rompy_xbeach.source import SourceCRSIntake source = SourceCRSIntake( catalog_uri=DATADIR / "catalog.yaml", dataset_id="bathy_netcdf", crs="EPSG:4326", ) ds = source._open() print(f"Loaded dataset with variables: {list(ds.data_vars)}")

Loaded dataset with variables: ['depth']

Key Parameters¶

Parameter	Description
catalog_uri	Path to the Intake catalog YAML file
dataset_id	ID of the dataset in the catalog
crs	Coordinate reference system

---

4. SourceCRSDataset¶

Use an existing xarray Dataset object. Useful when you've already loaded and processed data in memory.

In [6]:

from rompy_xbeach.source import SourceCRSDataset

# Use the dataset we loaded earlier
source = SourceCRSDataset(
    obj=ds,
    crs="EPSG:4326",
)

ds_from_source = source._open()
print(f"CRS: {source.crs}")

from rompy_xbeach.source import SourceCRSDataset # Use the dataset we loaded earlier source = SourceCRSDataset( obj=ds, crs="EPSG:4326", ) ds_from_source = source._open() print(f"CRS: {source.crs}")

CRS: EPSG:4326

Key Parameters¶

Parameter	Description
obj	xarray Dataset object
crs	Coordinate reference system

---

5. SourceGeotiff¶

Load GeoTIFF raster files. The CRS is automatically extracted from the file metadata, so you don't need to specify it.

In [7]:

from rompy_xbeach.source import SourceGeotiff

source = SourceGeotiff(
    filename=DATADIR / "bathy.tif",
)
source

from rompy_xbeach.source import SourceGeotiff source = SourceGeotiff( filename=DATADIR / "bathy.tif", ) source

Out[7]:

SourceGeotiff(model_type='geotiff', filename=PosixPath('../../../../rompy-xbeach/tests/data/bathy.tif'), band=1, kwargs={})

In [8]:

ds = source._open()
print(f"Shape: {ds.data.shape}")
print(f"CRS: {ds.rio.crs}")

ds = source._open() print(f"Shape: {ds.data.shape}") print(f"CRS: {ds.rio.crs}")

Shape: (180, 176)
CRS: EPSG:4326

In [9]:

# Visualise the data
ds.data.plot(cmap="terrain")

# Visualise the data ds.data.plot(cmap="terrain")

Out[9]:

<matplotlib.collections.QuadMesh at 0x7cd45e4ae630>

Key Parameters¶

Parameter	Description
filename	Path to the GeoTIFF file

Note: CRS is automatically read from the GeoTIFF metadata.

---

6. SourceXYZ¶

Load XYZ point cloud data (e.g., from survey files or LiDAR exports). The data is interpolated onto a regular grid during loading.

In [10]:

from rompy_xbeach.source import SourceXYZ

source = SourceXYZ(
    filename=DATADIR / "bathy_xyz.zip",
    res=0.0005,                              # Grid resolution (in CRS units)
    xcol="easting",                          # Column name for x coordinates
    ycol="northing",                         # Column name for y coordinates
    zcol="elevation",                        # Column name for z values
    crs="EPSG:4326",                         # Coordinate reference system
    read_csv_kwargs=dict(sep="\t"),          # pandas.read_csv kwargs
    griddata_kwargs=dict(method="linear"),   # scipy.griddata kwargs
)
source

from rompy_xbeach.source import SourceXYZ source = SourceXYZ( filename=DATADIR / "bathy_xyz.zip", res=0.0005, # Grid resolution (in CRS units) xcol="easting", # Column name for x coordinates ycol="northing", # Column name for y coordinates zcol="elevation", # Column name for z values crs="EPSG:4326", # Coordinate reference system read_csv_kwargs=dict(sep="\t"), # pandas.read_csv kwargs griddata_kwargs=dict(method="linear"), # scipy.griddata kwargs ) source

Out[10]:

SourceXYZ(model_type='xyz', filename=PosixPath('../../../../rompy-xbeach/tests/data/bathy_xyz.zip'), crs='EPSG:4326', res=0.0005, xcol='easting', ycol='northing', zcol='elevation', read_csv_kwargs={'sep': '\t'}, griddata_kwargs={'method': 'linear'})

In [11]:

ds = source._open()
ds

ds = source._open() ds

2026-01-10 18:35:07 [INFO] rompy_xbeach.source : Interpolating onto a grid of shape (78, 76)

Out[11]:

<xarray.Dataset> Size: 49kB
Dimensions:      (y: 78, x: 76)
Coordinates:
  * y            (y) float64 624B -32.65 -32.65 -32.65 ... -32.61 -32.61 -32.61
  * x            (x) float64 608B 115.6 115.6 115.6 115.6 ... 115.6 115.6 115.6
    spatial_ref  int64 8B 0
Data variables:
    data         (y, x) float64 47kB -13.21 -13.19 -13.28 -13.17 ... nan nan nan

xarray.Dataset

• Dimensions:
  • y: 78
  • x: 76
• Coordinates: (3)
  • y
    (y)
    float64
    -32.65 -32.65 ... -32.61 -32.61

    array([-32.648301, -32.647801, -32.647301, -32.646801, -32.646301, -32.645801,
           -32.645301, -32.644801, -32.644301, -32.643801, -32.643301, -32.642801,
           -32.642301, -32.641801, -32.641301, -32.640801, -32.640301, -32.639801,
           -32.639301, -32.638801, -32.638301, -32.637801, -32.637301, -32.636801,
           -32.636301, -32.635801, -32.635301, -32.634801, -32.634301, -32.633801,
           -32.633301, -32.632801, -32.632301, -32.631801, -32.631301, -32.630801,
           -32.630301, -32.629801, -32.629301, -32.628801, -32.628301, -32.627801,
           -32.627301, -32.626801, -32.626301, -32.625801, -32.625301, -32.624801,
           -32.624301, -32.623801, -32.623301, -32.622801, -32.622301, -32.621801,
           -32.621301, -32.620801, -32.620301, -32.619801, -32.619301, -32.618801,
           -32.618301, -32.617801, -32.617301, -32.616801, -32.616301, -32.615801,
           -32.615301, -32.614801, -32.614301, -32.613801, -32.613301, -32.612801,
           -32.612301, -32.611801, -32.611301, -32.610801, -32.610301, -32.609801])

  • x
    (x)
    float64
    115.6 115.6 115.6 ... 115.6 115.6

    array([115.591525, 115.592025, 115.592525, 115.593025, 115.593525, 115.594025,
           115.594525, 115.595025, 115.595525, 115.596025, 115.596525, 115.597025,
           115.597525, 115.598025, 115.598525, 115.599025, 115.599525, 115.600025,
           115.600525, 115.601025, 115.601525, 115.602025, 115.602525, 115.603025,
           115.603525, 115.604025, 115.604525, 115.605025, 115.605525, 115.606025,
           115.606525, 115.607025, 115.607525, 115.608025, 115.608525, 115.609025,
           115.609525, 115.610025, 115.610525, 115.611025, 115.611525, 115.612025,
           115.612525, 115.613025, 115.613525, 115.614025, 115.614525, 115.615025,
           115.615525, 115.616025, 115.616525, 115.617025, 115.617525, 115.618025,
           115.618525, 115.619025, 115.619525, 115.620025, 115.620525, 115.621025,
           115.621525, 115.622025, 115.622525, 115.623025, 115.623525, 115.624025,
           115.624525, 115.625025, 115.625525, 115.626025, 115.626525, 115.627025,
           115.627525, 115.628025, 115.628525, 115.629025])

  • 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)

• Data variables: (1)
  • data
    (y, x)
    float64
    -13.21 -13.19 -13.28 ... nan nan

    array([[-13.2075    , -13.18553264, -13.27709197, ...,          nan,
                     nan,          nan],
           [-13.03953179, -13.08546839, -13.18639817, ...,          nan,
                     nan,          nan],
           [-13.14932132, -13.42463076, -13.2565743 , ...,          nan,
                     nan,          nan],
           ...,
           [-10.96309615, -11.61893097, -12.08805764, ...,   9.68100842,
             15.84821514,          nan],
           [-11.44075854, -11.76471013, -12.21400225, ...,   6.66639894,
             12.65149763,          nan],
           [         nan,          nan,          nan, ...,          nan,
                     nan,          nan]], shape=(78, 76))

In [12]:

# Visualise the interpolated grid
ds.data.plot(cmap="terrain")

# Visualise the interpolated grid ds.data.plot(cmap="terrain")

Out[12]:

<matplotlib.collections.QuadMesh at 0x7cd45d165250>

Key Parameters¶

Parameter	Description
filename	Path to the XYZ file (supports .zip)
res	Output grid resolution
xcol, ycol, zcol	Column names in the file
crs	Coordinate reference system
read_csv_kwargs	Arguments for pandas.read_csv()
griddata_kwargs	Arguments for scipy.interpolate.griddata()

---

7. Summary¶

Choosing a Source Type¶

Data Format	Source Class
NetCDF / Zarr	SourceCRSFile
Intake catalog	SourceCRSIntake
In-memory xarray	SourceCRSDataset
GeoTIFF	SourceGeotiff
XYZ / CSV point cloud	SourceXYZ

Common Pattern¶

All source types follow the same pattern:

# 1. Create the source
source = SourceGeotiff(filename="bathy.tif")

# 2. Use with a data class
bathy = XBeachBathy(source=source, ...)

# 3. Generate files
bathy.get(destdir=destdir, grid=grid)

Next Steps¶

• See the Bathymetry Tutorial for using sources with XBeachBathy
• See the Wave Boundary Tutorial for using sources with wave data
• See the Forcing Tutorial for using sources with wind/tide data