Skip to content

BeaconClient reference

Source code in c3s_event_attribution_tools/data/beacon_client.py 
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
class BeaconClient():
    def __init__(self, beacon_cache_url: str, beacon_token: str | None = None) -> None:
        """
        Initialize the BeaconClient with connection details for the Beacon API.

        This constructor sets up the internal beacon client using a specific 
        cache URL and an optional authentication token.

        Parameters:
            beacon_cache_url (str):
                The base URL for the Beacon cache service.
            beacon_token (str | None):
                An optional JSON Web Token (JWT) for authenticated access to 
                the Beacon API. Default is None.
        """
        self.beacon_cache_url = beacon_cache_url
        self.beacon_token = beacon_token

        self.beacon_client = beacon_api.Client(
            url=self.beacon_cache_url,
            jwt_token=self.beacon_token
        )

    def fetch_from_era5_daily_single_levels_query(self, bbox: tuple[float,float,float,float], time_range: tuple[datetime,datetime], variable: Variable.ERA5DailySingleLevel) -> beacon_api.JSONQuery:
        """
        Create a query to fetch data from the ERA5 Daily Zarr dataset in Beacon Cache.

        This method constructs a structured JSON query for the Beacon API, selecting 
        spatial and temporal columns alongside the requested variable. It applies 
        spatial filtering via a bounding box and temporal filtering via the 
        provided time range.

        Parameters:
            bbox (tuple[float, float, float, float]):
                Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).
            time_range (tuple[datetime, datetime]):
                A tuple containing the (start_date, end_date) for the data query.
            variable (str):
                The variable name to fetch. Available options include: 
                't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

        Returns:
            beacon_api.JSONQuery: A configured query object ready to be executed 
            against the Beacon Cache.
        """

        era5_table = self.beacon_client.list_tables()['daily_single_levels']
        query = (era5_table.query()
                 .add_select_column('longitude')
                 .add_select_column('latitude')
                 .add_select_column('valid_time')
                 .add_select_column(variable.beacon_name(), variable.beacon_alias())
                 .add_bbox_filter('longitude','latitude', bbox)
                 .add_range_filter('valid_time', gt_eq=time_range[0], lt_eq=time_range[1]))

        return query

    def fetch_from_era5_daily_single_levels_xr(self, bbox: tuple[float,float,float,float], time_range: tuple[datetime,datetime], variable: Variable.ERA5DailySingleLevel) -> xr.Dataset:
        """
        Fetch data from the ERA5 Daily Zarr dataset in Beacon Cache as an xarray Dataset.

        This method executes a Beacon API query for the specified variable and 
        geographic area, converting the resulting data into a multi-dimensional 
        xarray Dataset with longitude, latitude, and time as dimensions.

        Parameters:
            bbox (tuple[float, float, float, float]):
                Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).
            time_range (tuple[datetime, datetime]):
                A tuple containing the (start_date, end_date) for the data request.
            variable (str):
                The variable name to fetch. Available options include: 
                't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

        Returns:
            xr.Dataset: An xarray Dataset containing the fetched data organized 
            by spatial and temporal dimensions.
        """

        query = self.fetch_from_era5_daily_single_levels_query(bbox, time_range, variable)

        ds = query.to_xarray_dataset(dimension_columns=['valid_time','latitude','longitude'], force=True)

        # wrap longitude to -180 to 180
        ds = ds.assign_coords(
            longitude=((ds.longitude + 180) % 360) - 180
        ).sortby("longitude")

        return ds    

    def fetch_from_era5_daily_single_levels_gpd(self, bbox: tuple[float,float,float,float], time_range: tuple[datetime,datetime], variable: Variable.ERA5DailySingleLevel) -> gpd.GeoDataFrame:
        """
        Fetch data from the ERA5 Daily Zarr dataset in Beacon Cache as a GeoDataFrame.

        This method executes a Beacon API query, converts the resulting tabular
        data into a pandas DataFrame, and then constructs a GeoDataFrame by
        generating point geometries from the longitude and latitude coordinates.

        Parameters:
            bbox (tuple[float, float, float, float]):
                Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).
            time_range (tuple[datetime, datetime]):
                A tuple containing the (start_date, end_date) for the data request.
            variable (str):
                The variable name to fetch. Available options include: 
                't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

        Returns:
            gpd.GeoDataFrame: A GeoDataFrame containing the fetched data with 
            spatial point geometries and temporal information.
        """
        query = self.fetch_from_era5_daily_single_levels_query(bbox, time_range, variable)

        df = query.to_pandas_dataframe()

        if df.empty:
            return gpd.GeoDataFrame(columns=['longitude', 'latitude', 'valid_time', variable], geometry=gpd.points_from_xy([], []), crs='EPSG:4326')
        # Wrap longitude to -180 to 180
        df['longitude'] = ((df['longitude'] + 180) % 360)
        return gpd.GeoDataFrame(df, geometry=gpd.points_from_xy(df.longitude, df.latitude), crs='EPSG:4326')

    def fetch_from_era5_daily_pressure_levels_gpd(self, bbox: tuple[float,float,float,float], time_range: tuple[datetime,datetime], variable: str, levels: list[int]) -> gpd.GeoDataFrame:
        era5_pressure_levels_table = self.beacon_client.list_tables()['daily_pressure_levels']

        query = (era5_pressure_levels_table.query()
                .add_select_column('longitude')
                .add_select_column('latitude')
                .add_select_column('pressure_level')
                .add_select_column('valid_time')
                .add_select_column(variable)
                .add_bbox_filter('longitude','latitude', bbox)
                .add_range_filter('valid_time', gt_eq=time_range[0], lt_eq=time_range[1]))

        df = query.to_pandas_dataframe()
        if df.empty:
            return gpd.GeoDataFrame(columns=['longitude', 'latitude', 'valid_time', variable, 'pressure_level'], geometry=gpd.points_from_xy([], []), crs='EPSG:4326')
        # Wrap longitude to -180 to 180
        df['longitude'] = ((df['longitude'] + 180) % 360)
        return gpd.GeoDataFrame(df, geometry=gpd.points_from_xy(df.longitude, df.latitude), crs='EPSG:4326')

    def fetch_from_era5_daily_pressure_levels_xr(self, bbox: tuple[float,float,float,float], time_range: tuple[datetime,datetime], variable: str, levels: list[int]) -> xr.Dataset:
        era5_pressure_levels_table = self.beacon_client.list_tables()['daily_pressure_levels']

        query = (era5_pressure_levels_table.query()
                .add_select_column('longitude')
                .add_select_column('latitude')
                .add_select_column('pressure_level')
                .add_select_column('valid_time')
                .add_select_column(variable)
                .add_bbox_filter('longitude','latitude', bbox)
                .add_range_filter('valid_time', gt_eq=time_range[0], lt_eq=time_range[1]))

        ds = query.to_xarray_dataset(dimension_columns=['valid_time','latitude','longitude','pressure_level'], force=True)

        # wrap longitude to -180 to 180
        ds = ds.assign_coords(
            longitude=((ds.longitude + 180) % 360) - 180
        ).sortby("longitude")

        return ds

__init__(beacon_cache_url, beacon_token=None)

Initialize the BeaconClient with connection details for the Beacon API.

This constructor sets up the internal beacon client using a specific cache URL and an optional authentication token.

Parameters:

Name Type Description Default
beacon_cache_url str

The base URL for the Beacon cache service.

 required
beacon_token str | None

An optional JSON Web Token (JWT) for authenticated access to the Beacon API. Default is None.

 None
Source code in c3s_event_attribution_tools/data/beacon_client.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def __init__(self, beacon_cache_url: str, beacon_token: str | None = None) -> None:
    """
    Initialize the BeaconClient with connection details for the Beacon API.

    This constructor sets up the internal beacon client using a specific 
    cache URL and an optional authentication token.

    Parameters:
        beacon_cache_url (str):
            The base URL for the Beacon cache service.
        beacon_token (str | None):
            An optional JSON Web Token (JWT) for authenticated access to 
            the Beacon API. Default is None.
    """
    self.beacon_cache_url = beacon_cache_url
    self.beacon_token = beacon_token

    self.beacon_client = beacon_api.Client(
        url=self.beacon_cache_url,
        jwt_token=self.beacon_token
    )

fetch_from_era5_daily_single_levels_gpd(bbox, time_range, variable)

Fetch data from the ERA5 Daily Zarr dataset in Beacon Cache as a GeoDataFrame.

This method executes a Beacon API query, converts the resulting tabular data into a pandas DataFrame, and then constructs a GeoDataFrame by generating point geometries from the longitude and latitude coordinates.

Parameters:

Name Type Description Default
bbox tuple[float, float, float, float]

Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).

 required
time_range tuple[datetime, datetime]

A tuple containing the (start_date, end_date) for the data request.

 required
variable str

The variable name to fetch. Available options include: 't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

 required

Returns:

Type Description
GeoDataFrame

gpd.GeoDataFrame: A GeoDataFrame containing the fetched data with

GeoDataFrame

spatial point geometries and temporal information.
Source code in c3s_event_attribution_tools/data/beacon_client.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def fetch_from_era5_daily_single_levels_gpd(self, bbox: tuple[float,float,float,float], time_range: tuple[datetime,datetime], variable: Variable.ERA5DailySingleLevel) -> gpd.GeoDataFrame:
    """
    Fetch data from the ERA5 Daily Zarr dataset in Beacon Cache as a GeoDataFrame.

    This method executes a Beacon API query, converts the resulting tabular
    data into a pandas DataFrame, and then constructs a GeoDataFrame by
    generating point geometries from the longitude and latitude coordinates.

    Parameters:
        bbox (tuple[float, float, float, float]):
            Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).
        time_range (tuple[datetime, datetime]):
            A tuple containing the (start_date, end_date) for the data request.
        variable (str):
            The variable name to fetch. Available options include: 
            't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

    Returns:
        gpd.GeoDataFrame: A GeoDataFrame containing the fetched data with 
        spatial point geometries and temporal information.
    """
    query = self.fetch_from_era5_daily_single_levels_query(bbox, time_range, variable)

    df = query.to_pandas_dataframe()

    if df.empty:
        return gpd.GeoDataFrame(columns=['longitude', 'latitude', 'valid_time', variable], geometry=gpd.points_from_xy([], []), crs='EPSG:4326')
    # Wrap longitude to -180 to 180
    df['longitude'] = ((df['longitude'] + 180) % 360)
    return gpd.GeoDataFrame(df, geometry=gpd.points_from_xy(df.longitude, df.latitude), crs='EPSG:4326')

fetch_from_era5_daily_single_levels_query(bbox, time_range, variable)

Create a query to fetch data from the ERA5 Daily Zarr dataset in Beacon Cache.

This method constructs a structured JSON query for the Beacon API, selecting spatial and temporal columns alongside the requested variable. It applies spatial filtering via a bounding box and temporal filtering via the provided time range.

Parameters:

Name Type Description Default
bbox tuple[float, float, float, float]

Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).

 required
time_range tuple[datetime, datetime]

A tuple containing the (start_date, end_date) for the data query.

 required
variable str

The variable name to fetch. Available options include: 't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

 required

Returns:

Type Description
JSONQuery

beacon_api.JSONQuery: A configured query object ready to be executed

JSONQuery

against the Beacon Cache.
Source code in c3s_event_attribution_tools/data/beacon_client.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def fetch_from_era5_daily_single_levels_query(self, bbox: tuple[float,float,float,float], time_range: tuple[datetime,datetime], variable: Variable.ERA5DailySingleLevel) -> beacon_api.JSONQuery:
    """
    Create a query to fetch data from the ERA5 Daily Zarr dataset in Beacon Cache.

    This method constructs a structured JSON query for the Beacon API, selecting 
    spatial and temporal columns alongside the requested variable. It applies 
    spatial filtering via a bounding box and temporal filtering via the 
    provided time range.

    Parameters:
        bbox (tuple[float, float, float, float]):
            Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).
        time_range (tuple[datetime, datetime]):
            A tuple containing the (start_date, end_date) for the data query.
        variable (str):
            The variable name to fetch. Available options include: 
            't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

    Returns:
        beacon_api.JSONQuery: A configured query object ready to be executed 
        against the Beacon Cache.
    """

    era5_table = self.beacon_client.list_tables()['daily_single_levels']
    query = (era5_table.query()
             .add_select_column('longitude')
             .add_select_column('latitude')
             .add_select_column('valid_time')
             .add_select_column(variable.beacon_name(), variable.beacon_alias())
             .add_bbox_filter('longitude','latitude', bbox)
             .add_range_filter('valid_time', gt_eq=time_range[0], lt_eq=time_range[1]))

    return query

fetch_from_era5_daily_single_levels_xr(bbox, time_range, variable)

Fetch data from the ERA5 Daily Zarr dataset in Beacon Cache as an xarray Dataset.

This method executes a Beacon API query for the specified variable and geographic area, converting the resulting data into a multi-dimensional xarray Dataset with longitude, latitude, and time as dimensions.

Parameters:

Name Type Description Default
bbox tuple[float, float, float, float]

Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).

 required
time_range tuple[datetime, datetime]

A tuple containing the (start_date, end_date) for the data request.

 required
variable str

The variable name to fetch. Available options include: 't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

 required

Returns:

Type Description
Dataset

xr.Dataset: An xarray Dataset containing the fetched data organized

Dataset

by spatial and temporal dimensions.
Source code in c3s_event_attribution_tools/data/beacon_client.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def fetch_from_era5_daily_single_levels_xr(self, bbox: tuple[float,float,float,float], time_range: tuple[datetime,datetime], variable: Variable.ERA5DailySingleLevel) -> xr.Dataset:
    """
    Fetch data from the ERA5 Daily Zarr dataset in Beacon Cache as an xarray Dataset.

    This method executes a Beacon API query for the specified variable and 
    geographic area, converting the resulting data into a multi-dimensional 
    xarray Dataset with longitude, latitude, and time as dimensions.

    Parameters:
        bbox (tuple[float, float, float, float]):
            Bounding box coordinates as (min_longitude, min_latitude, max_longitude, max_latitude).
        time_range (tuple[datetime, datetime]):
            A tuple containing the (start_date, end_date) for the data request.
        variable (str):
            The variable name to fetch. Available options include: 
            't2m', 't2m_max', 't2m_tmin', and 'total_precipitation'.

    Returns:
        xr.Dataset: An xarray Dataset containing the fetched data organized 
        by spatial and temporal dimensions.
    """

    query = self.fetch_from_era5_daily_single_levels_query(bbox, time_range, variable)

    ds = query.to_xarray_dataset(dimension_columns=['valid_time','latitude','longitude'], force=True)

    # wrap longitude to -180 to 180
    ds = ds.assign_coords(
        longitude=((ds.longitude + 180) % 360) - 180
    ).sortby("longitude")

    return ds