What is HydroBlox?

HydroBlox is an open-source visual workflow platform for hydrology data retrieval, analysis, and visualization. Built at the Hydroinformatics Lab, Tulane University.

HydroBlox provides a drag-and-drop canvas where you connect blocks — each block is a self-contained unit that fetches data, runs analysis code, or renders a visualization. Blocks wire together into directed acyclic graphs (DAGs) that represent complete analytical pipelines, from raw API data to publication-ready charts and maps.

The platform is designed to remove barriers between data access and analysis. Rather than writing boilerplate API and parsing code, users configure data blocks through a UI and focus on the analytical logic. The AI assistant can generate that logic from a plain-English description.

Data retrieval is powered by HydroLang, a modular JavaScript library developed by the same lab. For full details on available functions and the underlying data retrieval API, see the HydroLang documentation →

Features

HydroBlox covers the full hydrology analysis stack in a single interface.

Web App

The web app runs entirely in the browser — no installation required.

Accessing the Web App

The web app is already hosted on this server! You can access it directly by clicking below:

Open Web App

Python & R in the browser

Code blocks run via Pyodide (Python) and WebR (R) — WebAssembly runtimes that require no local installation. Most scientific libraries are available: numpy, pandas, scipy, statsmodels, scikit-learn. Libraries that depend on C extensions or system calls may not be available in Pyodide — for those, use the desktop app.

Desktop App

The desktop app is a portable Electron executable — no installation needed, just open and run.

Getting the app

Download the .exe (Windows portable) from the Downloads section of the landing page. No installer, no admin rights required. (Builds for macOS and Linux are coming soon!)

Native Python & R execution

On first launch, HydroBlox auto-detects your Python and R installations. If detection fails, open Settings → Workspace and set the binary paths manually (e.g. C:\ProgramData\anaconda3\python.exe).

When a Python or R code block runs on the desktop, HydroBlox spawns a native subprocess — giving full access to every installed package, filesystem reads, and multi-core computation. There is no memory sandbox.

Workspace

On first launch you are prompted to pick a workspace folder. HydroBlox stores workflow files, cached results, and runtime logs there. You can change the workspace at any time in Settings.

Differences from the web app

• Full Python/R library access (no Pyodide restrictions)
• No browser memory ceiling — limited only by system RAM
• Faster block execution (native processes, no WASM overhead)
• Results stored in SQLite rather than IndexedDB
• Filesystem read/write access from code blocks

NGIAB / NextGen

Connect NOAA's NextGen In A Box (NGIAB) Docker container to HydroBlox using the BMI Bridge block. (Integration Coming Soon)

Overview

HydroBlox provides a BMI (Basic Model Interface) Bridge block that can connect to local or remote NGIAB containers. This allows you to orchestrate NextGen framework models (like NGEN, CFE, Noah-OWP) directly from the HydroBlox canvas.

Configuration Example

Drop a BMI Bridge block on the canvas and configure it with the IP address and port of your running NGIAB container. You can pass JSON inputs to the block to drive the model.

Example JSON Payload:

{
  "model": "cfe",
  "forcing_file": "cat-87_2015-12-01_2015-12-30.csv",
  "time_step": 3600,
  "run_duration": 86400
}

The block will output the simulation results for downstream visualization or analysis as a structured array.

Block Types

Every element on the canvas is a block. Blocks have typed input and output ports. Connect blocks by dragging from an output port to an input port.

Example: Hello World Workflow

Building a workflow is as simple as dragging blocks onto the canvas and wiring their ports together. Here is a basic pipeline:

Click Run All. The platform will automatically execute the blocks in sequence, respecting the topological order of your connections.

Data

Fetches data from an external API or file upload. Configuration is done via a point-and-click UI. Output is a structured data object (JSON, array, binary).

Code

Executes Python, R, or JavaScript. Connect upstream data and process it natively.

Analysis

Built-in processing blocks: geoprocessing (clip, reproject, zonal statistics), statistical transforms, and HydroLang functions (flood frequency, ET estimation).

Visualization

Charts (line, bar, heatmap, box plot), Maps (Leaflet with raster/GeoJSON overlay), and Tables (sortable, CSV-exportable).

Control Flow

Use Parallel Map to fan-out operations across lists, Aggregator to merge results, and Conditional/Loop for dynamic routing.

Data Sources

Data retrieval in HydroBlox is powered by HydroLang. Over 50 APIs are natively supported via a simplified configuration UI.

Example: Configuring USGS NWIS

To pull streamflow data, you do not need to read USGS documentation. Simply use the Data block UI:

When the block runs, it handles the REST call, parses the JSON/WaterML response, and normalizes it into a standard JSON array for downstream use.

Code Blocks

Code blocks are the primary tool for custom analysis. They run Python, R, or JavaScript and receive upstream data automatically.

Input Convention

Upstream data is injected into your execution environment. If you connect one block, access it via data. If you connect multiple, access them as a list: data[0], data[1], etc.

Example: Python Rolling Average

Assume data is a list of dictionaries with date and value fields fetched from a USGS block. To compute a 7-day rolling average:

import pandas as pd

# Convert incoming JSON-like array to a pandas DataFrame
df = pd.DataFrame(data)
df['date'] = pd.to_datetime(df['date'])
df.set_index('date', inplace=True)

# Calculate the rolling mean
df['rolling_mean'] = df['value'].rolling(window=7).mean()

# Return as a dictionary so downstream blocks can consume it
return df.reset_index().to_dict(orient='records')

Example: Multiple Inputs in R

Assume data[[1]] is observed flow and data[[2]] is simulated flow. You can compute an error metric directly:

obs <- as.numeric(data[[1]]$discharge)
sim <- as.numeric(data[[2]]$discharge)

# Calculate Root Mean Square Error (RMSE)
rmse <- sqrt(mean((sim - obs)^2, na.rm = TRUE))

return(list(metric = "RMSE", value = rmse))

Libraries

Enter package names in the Libraries field (e.g., pandas, scipy). They are installed automatically on first run.

AI Assistant

The AI assistant is context-aware—it reads your canvas structure and the output shape of adjacent blocks to write accurate code and debug errors.

Example Prompts

Instead of writing boilerplate pandas code, use the AI block or sidebar assistant:

• "Write a Python script to calculate the Standardized Precipitation Index (SPI) from the upstream monthly precipitation array."
• "Merge the two upstream datasets on the 'site_id' column."
• "Why did my last block fail? Explain the KeyError and fix the code."

Configuring a Provider

Open Settings → AI to choose your model:

• OpenAI: Enter your API key for GPT-4o.
• Local (Ollama / LM Studio): Point to http://localhost:11434 to run Llama 3 or Mistral locally. No API key needed; data stays on your machine.
• WebLLM: Downloads a quantized model directly into the browser cache and runs entirely offline via WebGPU.

Exporting Data

Every block result is stored automatically. Export individual datasets or bulk-download everything as a ZIP.

The Data Store panel

Open the sidebar and click Data Store. Each saved result shows its type (timeseries, raster, geojson, table…), size, and timestamp. Click a result to preview it in the Data Explorer.

Download formats

• JSON / CSV — for timeseries and tabular data
• GeoTIFF — for raster outputs from MRMS, AORC, 3DEP, or rasterio-based code blocks. Magic-byte detection ensures the file is saved with the correct extension and MIME type.
• GeoJSON / Shapefile ZIP — for vector geospatial outputs
• NetCDF / HDF5 — for multidimensional array outputs
• ZIP archive — bulk export: select multiple results and download as a single ZIP

Re-injecting results

Any saved result can be dragged back onto the canvas as a static Data node. This lets you checkpoint a long-running fetch and reuse the result across multiple workflows without re-fetching.

Sharing Workflows

Workflows are saved as .blox files — portable JSON that anyone can load on the web or desktop app.

Saving a workflow

Click the Save button in the sidebar (or Ctrl+S). A .blox file is downloaded. The file embeds node positions, block configurations, and connection graph. Result data is not embedded — recipients re-run the workflow to generate fresh data.

Loading a workflow

Drag a .blox file onto the canvas, or click Open in the sidebar. Example workflows are available in the Examples panel.

Sharing via HydroShare

Use a HydroShare block in upload mode to publish result datasets or .blox files as community resources. Other users can access them through the HydroShare data block by searching by keyword or resource ID.

Exported Apps

HydroBlox allows you to export your workflows as fully standalone, interactive Progressive Web Apps (PWAs). Below are live examples deployed directly from the canvas.