nixtla-contract-schema-mapper

intent-solutions-io's avatarfrom intent-solutions-io

Transform prediction market data to Nixtla format (unique_id, ds, y). Use when preparing datasets for forecasting. Trigger with 'convert to Nixtla format' or 'schema mapping'.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026
[Data Cleaning]

When & Why to Use This Skill

This Claude skill automates the transformation of prediction market data into the standardized Nixtla format (unique_id, ds, y), which is essential for time-series forecasting. It streamlines the data preparation pipeline by handling complex schema mapping, date validation, and numeric type conversion, ensuring raw datasets are perfectly formatted for tools like TimeGPT and StatsForecast.

Use Cases

  • Converting raw CSV exports from prediction markets (e.g., Polymarket) into standardized formats for financial forecasting.
  • Mapping inconsistent column headers like 'timestamp' or 'price' to the required 'ds' and 'y' schema automatically.
  • Validating date formats and cleaning non-numeric values in time-series datasets to prevent errors during model training.
  • Generating quick time-series visualizations and baseline forecasts to assess data quality before performing advanced analytics.
namenixtla-contract-schema-mapper
description"Transform prediction market data to Nixtla format (unique_id, ds, y). Use when preparing datasets for forecasting. Trigger with 'convert to Nixtla format' or 'schema mapping'."
version"1.0.0"
author"Jeremy Longshore <jeremy@intentsolutions.io>"
licenseMIT
allowed-tools"Read,Write,Bash(python:*),Glob,Grep"

Nixtla Contract Schema Mapper

Transforms prediction market data into Nixtla-compatible format (unique_id, ds, y).

Overview

Converts prediction market datasets with varying schemas into standardized Nixtla format. Maps arbitrary column names to required schema, validates date parsing and numeric types, produces clean CSV output ready for forecasting. Optional visualization and sample forecast generation.

Prerequisites

Required:

  • Python 3.8+
  • pandas, matplotlib packages

Optional (for forecasting):

  • statsforecast for open-source models
  • nixtla for TimeGPT (requires API key)

Environment Variables:

  • NIXTLA_TIMEGPT_API_KEY: Required only if using --timegpt flag

Installation:

pip install pandas matplotlib statsforecast nixtla

Instructions

Step 1: Identify Column Mappings

Examine your input CSV to identify:

  • ID column: Unique identifier for each contract/series
  • Date column: Timestamp or date values
  • Target column: Numeric value to forecast (price, volume, probability)

Step 2: Run Transformation

Execute the transformation script:

python {baseDir}/scripts/transform_data.py --input data.csv \
    --id_col contract_id --date_col date --target_col price

Available options:

  • --input: Input CSV file path (required)
  • --id_col: Column name for unique ID (required)
  • --date_col: Column name for date (required)
  • --target_col: Column name for target variable (required)
  • --output: Output file path (default: nixtla_data.csv)
  • --plot: Generate time series visualization
  • --forecast: Run sample forecast after transform
  • --timegpt: Use TimeGPT instead of StatsForecast

Step 3: Verify Output

Check the transformed data:

head -5 nixtla_data.csv

Expected format:

unique_id,ds,y
contract_1,2024-01-01,0.75
contract_1,2024-01-02,0.78

Output

  • nixtla_data.csv: Transformed data with columns (unique_id, ds, y)
  • time_series_plot.png: Visualization of first series (if --plot)
  • Console output: Transformation summary with series count, date range, value statistics

Error Handling

  1. Error: Input file not found: data.csv Solution: Verify file path exists and is readable

  2. Error: Column 'contract_id' not found. Available: [...] Solution: Use exact column name from the available list

  3. Error: Invalid date format in date column Solution: Ensure dates use YYYY-MM-DD or standard parseable format

  4. Error: Non-numeric data in target column Solution: Clean non-numeric values from target column

  5. Error: NIXTLA_TIMEGPT_API_KEY not set Solution: export NIXTLA_TIMEGPT_API_KEY=your_key or omit --timegpt

Examples

Example 1: Basic Transformation

python {baseDir}/scripts/transform_data.py \
    --input polymarket_prices.csv \
    --id_col market_id \
    --date_col timestamp \
    --target_col last_price

Output:

Transformed data saved to: nixtla_data.csv

Transformation Summary:
  Series count: 15
  Total rows: 4500
  Date range: 2024-01-01 to 2024-06-30
  Value range: 0.0100 to 0.9900

Example 2: With Visualization and Forecast

python {baseDir}/scripts/transform_data.py \
    --input election_contracts.csv \
    --id_col candidate_id \
    --date_col date \
    --target_col probability \
    --plot \
    --forecast

Resources

  • Script: {baseDir}/scripts/transform_data.py
  • Nixtla Docs: https://nixtla.github.io/
  • Nixtla Schema: unique_id (string), ds (datetime), y (numeric)