Accessing Chronax Benchmark Datasets

This guide shows you how to load and prepare a time series dataset from the Chronax benchmark suite, making the data ready for model training. You should use this when starting any new forecasting project within Chronax.

Prerequisites

Chronax installed (including the data module).
The target variable y must be a 1-D jnp.ndarray of type float32.
Exogenous variables X (if used) must be a 2-D jnp.ndarray of type float32 (shape [time_steps, features]).

Steps

1. Import JAX and the DataLoader

You need jax.numpy for array manipulation and the DataLoader utility provided by Chronax to parse the benchmark CSV files into JAX arrays.

import jax.numpy as jnp
from chronax.data import DataLoader

2. Specify and Load the Task

Identify the task you want to use (e.g., chickenpox_dense_univariate from the Healthcare category). Use the DataLoader.load_task method to retrieve the structured data.

task_name = "chickenpox_dense_univariate"
# The DataLoader handles parsing the CSV and converting JSON arrays to jnp.ndarrays
loaded_data = DataLoader.load_task(task_name)

3. Extract the Target Variable

The loaded data structure contains the target time series, typically accessible via a key like "y" or "target_values". Extract this array and ensure it is the correct shape and type for modeling.

For univariate tasks, the target variable y is the only required input for fitting a model.

# Assuming the DataLoader returns a dictionary containing the target values
y = loaded_data["target_values"]

# Verify shape and type
print(f"Target shape: {y.shape}")
print(f"Target dtype: {y.dtype}")

# Ensure y is float32, which is standard for JAX/Chronax models
if y.dtype != jnp.float32:
    y = y.astype(jnp.float32)

4. Handle Multivariate Data (Optional)

If you load a multivariate task (e.g., gold_india_dense_multivariate), the loaded_data structure will also contain exogenous features X (covariates). Extract these features if your chosen model supports them.

# Example for a multivariate task (if applicable)
# X = loaded_data["covariate_values"]
# print(f"Exogenous features shape: {X.shape}")

Full example

This example loads the weekly chickenpox case counts and prepares the target array y for use with a Chronax model.

import jax.numpy as jnp
from chronax.data import DataLoader

# 1. Specify the task
task_name = "chickenpox_dense_univariate"

# 2. Load the data
loaded_data = DataLoader.load_task(task_name)

# 3. Extract and prepare the target variable y
y = loaded_data["target_values"]

# Ensure y is float32
if y.dtype != jnp.float32:
    y = y.astype(jnp.float32)

print(f"Successfully loaded {task_name}.")
print(f"Prepared target array y with shape: {y.shape} and dtype: {y.dtype}")

Next steps

Consult the guide on "Forecast a univariate series" to learn how to use y with models like AutoARIMA.
Review the guide on "Using exogenous features" if you are working with multivariate tasks and need to handle X.
Explore the chronax.data.DataLoader documentation for options on handling missing values or scaling.