dClimate Hackathon Playbook

Kick-start your build for the dClimate hackathon. This guide focuses on two core building blocks—jaxray for labeled multi-dimensional arrays, and dclimate-client-js for discovering and streaming dClimate IPFS datasets. The goal: help teams move from idea to prototype quickly, whether you are building climate dashboards, analytics, or new data-powered experiences.

What You Can Build Quickly

• Interactive web maps that overlay live or forecast weather layers
• Climate risk scoring tools that crunch historical and forecast data
• Data pipelines that normalize and enrich gridded climate datasets
• ML-powered insights that mix dClimate data with your own inputs

Key Libraries

jaxray (labeled arrays)

• Inspired by Python's xarray, but optimized for TypeScript/JavaScript
• Works in browsers and Node runtimes
• Handles chunked streaming for large datasets
• Rich selection API (sel, isel, rolling windows, where, math ops)

dclimate-client-js (dataset discovery)

• Resolves dataset keys to the latest IPFS CID
• Wraps jaxray stores behind a friendly API
• Optional returnJaxrayDataset flag returns the raw jaxray.Dataset recomended for now
• Ships separate browser + Node bundles so you can use the same code everywhere

Helpful dataset requests available today (collection / dataset / variant):

Collection	Dataset	Variants
aifs	precipitation	single, ensemble
aifs	temperature	single, ensemble
aifs	wind_u	single, ensemble
aifs	wind_v	single, ensemble
aifs	solar_radiation	single, ensemble
copernicus	fpar	default
ifs	precipitation	default
ifs	temperature	default
ifs	wind_u	default
ifs	wind_v	default
ifs	soil_moisture_l3	default
ifs	solar_radiation	default
prism	precipitation-800m	default
prism	tmax-800m	default
gfs	precipitation-rate	default
gfs	precipitation-total	default
gfs	temperature-max	default
gfs	temperature-min	default
era5	2m_temperature	finalized, non-finalized
era5	total_precipitation	finalized, non-finalized
era5	10m_u_wind	finalized, non-finalized
era5	10m_v_wind	finalized, non-finalized
era5	surface_solar_radiation	finalized, non-finalized
era5	land_total_precipitation	finalized

Use client.listAvailableDatasets() to inspect the current catalog at runtime.

Getting Started

1. Install dependencies that ship with this repo:

   npm install

2. Run the node example to verify connectivity and dataset access:

   npm run node-example

3. Inspect examples/browser/useTemperatureSeries.ts and drop the hook into your React app. It relies on the same installed dependencies (react, react-dom).

Local Project Setup

Already using this starter? The Getting Started section covers installation.

If you would rather scaffold a fresh project from scratch:

1. Install Node.js 18+ (LTS recommended) and npm, pnpm, or yarn.
2. Create a workspace for your project and pull in the same dependencies used here:

   mkdir my-climate-app && cd my-climate-app
   npm init -y
   npm install dclimate-client-js @dclimate/jaxray react react-dom chart.js react-chartjs-2
   npm install -D tsx typescript @types/node @types/react @types/react-dom

   Swap charting libraries to taste (D3, Recharts, etc.).
3. Scaffold your frontend stack (Vite, Next.js, Remix, etc.) and copy the examples from this repo into your source tree.
4. Run npx tsx or your bundler of choice to execute the examples.

Working with returnJaxrayDataset

dclimate-client-js returns a higher-level GeoTemporalDataset by default. Provide options.returnJaxrayDataset = true when calling loadDataset or selectDataset to receive the underlying jaxray.Dataset for full control.

import { DClimateClient } from 'dclimate-client-js';
import type { Dataset } from '@dclimate/jaxray';

const client = new DClimateClient();

async function openTemperature() {
  const [dataset, metadata] = (await client.loadDataset({
    request: {
      collection: 'ifs',
      dataset: 'temperature',
      variant: 'default',
    },
    options: {
      returnJaxrayDataset: true,
    },
  })) as [Dataset, DatasetMetadata];

  console.log(dataset.dataVars); // e.g. ['temperature']
  return dataset;
}

For some datasets like ERA5, there is finalized and non-finalized data. Sometimes you want to fetch a continuous series while acknowledging the non-finalized may later change. The dclimate-zarr-client automatically handles this for you by intelligently splicing the non-finalized data and concating to finalized data. Just leave off the variant you wish. Some datasets though this doesn't work and you will need to specify a variant.

import { DClimateClient } from 'dclimate-client-js';
import type { Dataset } from '@dclimate/jaxray';

const client = new DClimateClient();

async function openTemperature() {
  const [dataset, metadata]  = (await client.loadDataset({
    request: {
      collection: 'era5',
      dataset: '2m_temperature',
    },
    options: {
      returnJaxrayDataset: true,
    },
  })) as [Dataset, DatasetMetadata];

  console.log(dataset.dataVars); // e.g. ['2m_temperature']
  return dataset;
}

Once you have a Dataset, use jaxray to explore dimensions, select slices, compute stats, and feed the results straight into charts.

Example Assets in This Repo

• examples/node/return-jaxray-dataset.ts – script that loads the IFS temperature dataset (collection: 'ifs', dataset: 'temperature', variant: 'default'), inspects coordinates, and performs a point + time range selection. Run with npm run node-example.
• examples/browser/charting.tsx – Example on how to chart
• examples/browser/mapping.tsx – Example on how to map

Feel free to copy these directly into your project or fork them into other runtimes (Next.js API routes, workers, etc.).

Run the MapLibre demo

1. Scaffold a React app (Vite shown here):

   cd maplibre-demo

2. Run the dev server: npm run dev, open the printed URL, and you should see a couple examples.

Typical Data Flow

1. Discover – call client.listAvailableDatasets() or read the table above.
2. Open – use client.loadDataset({ request: { collection: 'ifs', dataset: 'temperature', variant: 'default' }, options: { returnJaxrayDataset: true } }).
3. Inspect – log dataset.coords and dataset.dataVars to learn dimension names.
4. Select – use DataArray.sel or Dataset.sel to pick lat/lon/time windows. method: 'nearest' is great for quick lookups.
5. Transform – compute stats with mean, sum, rolling windows, or boolean masks (where).
6. Visualize/Serve – send the processed array to your frontend, charting library, or API response.

Plotting Weather Data on the Frontend

1. Build a reusable data hook (see examples/browser/useTemperatureSeries.ts).
2. Normalize time/value pairs for your charting solution.
3. Cache selections on the client or edge (these datasets can be large).
4. Combine multiple variables (e.g., precipitation + temperature) for richer visuals.
5. Add map layers: use the same jaxray data to drive canvas/WebGL overlays or convert rasters to vector contours.

Quick Analysis Recipes

Goal	Approach
Daily aggregations	Call await data.sel({ time: { start, stop } }).compute().mean('time')
Lat/Lon slices	await data.sel({ latitude: 35, longitude: -97 }, { method: 'nearest' })
Ensemble stats	Load AIFS datasets with variant: 'ensemble', then use Dataset.stack or DataArray.mean('member')
Masking	DataArray.where(condition, valueIfTrue, valueIfFalse)
Rolling windows	data.rolling('time', windowSize).mean()
Export to JSON	data.toJSON() (serialize before sending to frontends)

Project Ideas to Spark Creativity

1. Climate Stories Dashboard – blend temperature, precipitation, and solar radiation to surface daily highlights per city.
2. Farmer Advisory Assistant – generate planting/harvest recommendations from soil moisture + forecast temperature.
3. Grid Resilience Monitor – detect heatwave risks by aggregating ensembles and alerting on thresholds.
4. Open Climate API – expose cleaned weather endpoints for other teams via Cloudflare Workers or Fastify.
5. Immersive Map Experience – render WebGL tiles from jaxray outputs and animate upcoming weather fronts.

Submission Checklist

• ✅ Clear README describing the problem, data, and solution impact
• ✅ Working demo (hosted link or walkthrough video)
• ✅ Source code with setup instructions
• ✅ Explanation of how dClimate datasets + jaxray enabled the project
• ✅ Stretch: mention scaling plans or real-world deployment path

Performance Optimization

Dataset chunking strategy: dClimate datasets are optimized along the time dimension. This means:

• ✅ Fast: Small locations over long time periods (e.g., single city temperature for 1 year)
• ⚠️ Slower: Wide regions over short time periods (e.g., entire continent for 1 day)

Why? Data is chunked temporally, so fetching a time series at one location streams efficiently. Fetching a large spatial area requires pulling many chunks for a single time step.

Best practices for location-based analysis:

• Query specific lat/lon points with method: 'nearest' for time series analysis
• Use toRecords() to convert time series data into chart-friendly formats
• When analyzing multiple locations, query them sequentially or in small batches
• For spatial analysis over large areas, consider limiting the time range or using lower-resolution data

Example - Optimized query:

// ✅ Fast: Single location, long time range
const timeSeries = await variable.sel({
  latitude: 40.7128,
  longitude: -74.0060,
  time: ['2023-01-01', '2023-12-31']
}, { method: 'nearest' });

Example - Slower query:

// ⚠️ Slower: Large region, short time range
const spatialSlice = await variable.sel({
  latitude: [25, 50],
  longitude: [-125, -66],
  time: '2023-01-15'
}, { method: 'nearest' });

Troubleshooting & Tips

• Network hiccups: switch gateways (client.loadDataset({ request: { ... }, options: { gatewayUrl: 'https://ipfs.io/ipfs/', returnJaxrayDataset: true } })), or run a local IPFS node with createIpfsElements from jaxray.
• Large selections: prefer selStream or iterate over DataArray.sel in chunks to stay memory-friendly.
• Time zones: datasets are UTC; convert for display.
• TypeScript ergonomics: import Dataset, DataArray, SelectionOptions from @dclimate/jaxray for strong typing.
• Testing: stub loadDataset and feed fixtures into your UI tests to avoid network calls.

Additional Resources

• jaxray README
• dclimate-client-js README

Good luck, have fun, and build something the climate world needs.