Moving to ClimateData, Deprecation of get_data()

[neilSchroeder]

Moving to ClimateData

We’re moving toward one supported data-access interface in ClimakitAE: ClimateData.

The legacy data-access methods have served us well, but maintaining two interfaces makes it harder to improve the library, document the right patterns, and keep behavior consistent. We’re starting the process of retiring the legacy interface, with removal targeted for 2.0.0 in Q1 or Q2 2027.

What is changing?

These legacy entrypoints are now deprecated:

• DataParameters.retrieve()
• get_data_options()
• get_subsetting_options()
• get_data()

They emit DeprecationWarning messages and will be removed in 2.0.0.

Several older analysis workflows have also been removed:

• The legacy warming-level workflow
• The CmipOpt uncertainty workflow
• The legacy TimeSeries workflow
• The legacy threshold data-loading wrapper

The corresponding functionality is available through the newer processor-based architecture where appropriate. Some specialized workflows are still being migrated separately.

What should users do?

If you already use ClimateData, little changes. That is the supported direction for new work.

If you still use the legacy interface, please migrate during the 1.x release line rather than waiting for 2.0.0.

Legacy code like this:

from climakitae.core.data_interface import get_data

data = get_data(
    variable="Air Temperature at 2m",
    resolution="9 km",
    timescale="daily",
    downscaling_method="Dynamical",
    scenario=["Historical Climate", "SSP 3-7.0"],
    area_subset="CA counties",
    cached_area=["Los Angeles County"],
)

should move to:

from climakitae import ClimateData

data = (
    ClimateData()
    .catalog("cadcat")
    .activity_id("WRF")
    .institution_id("UCLA")
    .experiment_id(["historical", "ssp370"])
    .table_id("day")
    .grid_label("d02")
    .variable_id("t2")
    .processes({"clip": "Los Angeles County"})
    .get()
)

The main migration changes are:

• Import ClimateData from climakitae
• Use .variable_id(...) instead of .variable(...)
• Use catalog-native values such as activity_id, grid_label, table_id, and experiment_id
• Use processors such as clip, time_slice, and warming_level
• Replace mutable DataParameters workflows with fluent query construction

The Legacy to ClimateData migration guide includes detailed mappings and examples.

What stays the same?

The goal is not to change the climate data or scientific concepts users rely on. The goal is to provide one clearer, more maintainable path for accessing and processing that data.

We’d especially welcome feedback from users who maintain notebooks, applications, or downstream tools that still depend on the legacy interface. Please share which APIs or workflows would make migration difficult.