Floatmatcher is a a python library for third-party dataset matchup with Argo floats Third-party datasets can originate from local or distant repositories.
Asociated documentation is available running : python3 -m http.server 8000 -d docs/_build/html after installation
To install floatmatcher library, use the current git repository :
uv add "floatmatcher @ git+https://github.com/euroargodev/FloatMatcher.git@main"
pip install "git+https://github.com/euroargodev/FloatMatcher.git@main"
# Import the library
import floatmatcher.floatmatcher as fm# Instanciate builder object:
my_fm = fm.FloatMatcher() # Import points:
lon = np.array([-28.15, -46.51])
lat = np.array([54.48, 30.08])
time = np.array(["2013-03-18T22:47", "2014-05-18T12:22"], dtype="datetime64[ns]")
my_fm.set_points(lon, lat, time)# Set product
my_fm.set_product(type="era5-hourly",
source="local",
selected_variables=["sst"],
path="/<era5_data_folder>",
)# set method
import numpy as np
my_fm.set_method(type="interp", radius=12,
time_gap=np.timedelta64(3, "h"),
k_nearest=4, n_frames=2, kernel="idw",
power=2
)# trigger the match
my_fm.match()# display results
my_fm.resultAn Argo dataset can be matched directly through its .argo accessor:
import argopy
import numpy as np
import floatmatcher
ds = argopy.DataFetcher().region([-28, -25, 48, 50, 0, 50, "2018-01", "2018-06"]).data
ds_matched = ds.argo.floatmatcher.match(
product=dict(type="era5-hourly", source="local",
selected_variables=["sst"], path="/<era5_data_folder>"),
method=dict(type="nearest", radius=50, time_gap=np.timedelta64(6, "h")),
)The Argo dataset comes back in the same layout as the original argopy dataset with a sst_coloc variable.
Notebooks in examples/:
- Quickstart: the whole workflow, from points to matched values.
- Points: arrays, DataFrame, Dataset, Argo float with argopy.
- Remote CDS: CDS account, requests, cache, without network.
- Local archives: one file, a list, a folder, a tree with a pattern, a look-up table.
- Methods and results: nearest and interpolation, radius and time gap, several neighbors, results.
- Argopy accessor: match an argopy dataset in one call, several neighbors.
type |
source |
Source parameters | Grid |
|---|---|---|---|
"era5-hourly" |
"local" |
pattern (optional) |
0.25°, hourly time axis |
"era5-hourly" |
"remote-cds" |
client (required), clear_cache (False), time (all hours) |
0.25°, hourly time axis |
"lut" |
"local" |
pattern (optional) |
1°, no time axis: points without time |
type |
source |
Variable (selected_variables) |
Description |
|---|---|---|---|
"era5-hourly" |
"remote-cds" |
sst |
sea surface temperature |
t2m |
2 m temperature | ||
u10, v10 |
10 m u and v components of wind | ||
avg_slhtf |
mean surface latent heat flux | ||
avg_ishf |
mean surface sensible heat flux | ||
avg_snswrf |
mean surface net short-wave radiation flux | ||
avg_snlwrf |
mean surface net long-wave radiation flux | ||
"era5-hourly" |
"local" |
the variables of the local files | |
"lut" |
"local" |
fluorescence_chlorophyll_ratio |
physiological ratio between fluorescence and chlorophyll-a (LUT_v2_202608.nc) |
sd_fluorescence_chlorophyll_ratio |
its temporal standard deviation |
| Parameter | "nearest" |
"interp" |
|---|---|---|
radius (km) |
25 | 25 |
time_gap |
1 day | 1 day |
k_nearest: nearest nodes |
1 | 2 |
n_frames: nearest time steps |
1 | 1 |
kernel, power |
- | "idw", 2 |
time_gap and n_frames are ignored on a grid without time axis. interp weights its neighbors into one value per point; nearest with k_nearest or n_frames above 1 keeps every neighbor, sorted from the nearest (s0, t0).
Points given to set_points |
One neighbor | Several neighbors (nearest) |
|---|---|---|
arrays, PointSet |
result only |
result only, values (n, K, N) |
| DataFrame | column sst_coloc |
columns sst_coloc_s0_t0, sst_coloc_s0_t1... |
| Dataset | sst_coloc(N_PROF) |
sst_coloc(N_PROF, k_space, n_time), or with reinject(neigh_to_vars=True): sst_coloc_s0_t0(N_PROF)... |
result.neigh_to_cols() gives the same columns as the DataFrame.
Argopy accessor: ds.argo.floatmatcher.match(product, method, neigh_to_vars=False, original_shape=True)
| Argo dataset | One neighbor, neigh_to_vars=False |
Several neighbors, neigh_to_vars=False |
Several neighbors, neigh_to_vars=True |
|---|---|---|---|
profiles (N_PROF) |
sst_coloc(N_PROF) |
sst_coloc(N_PROF, k_space, n_time) |
sst_coloc_s0_t0(N_PROF)... |
points (N_POINTS) |
sst_coloc(N_POINTS) |
error: use neigh_to_vars=True or original_shape=False |
sst_coloc_s0_t0(N_POINTS)... |
points (N_POINTS), original_shape=False |
back in profiles, sst_coloc(N_PROF) |
back in profiles, sst_coloc(N_PROF, k_space, n_time) |
back in profiles, sst_coloc_s0_t0(N_PROF)... |
original_shape has no effect on a profiles dataset.