nixtla-schema-mapper

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

Transform data sources to Nixtla schema (unique_id, ds, y) with column inference. Use when preparing data for forecasting. Trigger with 'map to Nixtla schema' or 'transform data'.

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

When & Why to Use This Skill

The Nixtla Schema Mapper is a specialized Claude skill designed to streamline time-series data preparation for forecasting. It automates the transformation of diverse data sources—including CSV, SQL, Parquet, and dbt models—into the standardized Nixtla format (unique_id, ds, y). By utilizing intelligent column inference and automated Python code generation, this skill eliminates manual data munging, ensures schema consistency through validation contracts, and accelerates the transition from raw data to actionable forecasting insights.

Use Cases

  • Case 1: Converting raw sales spreadsheets or CSV files into the required Nixtla format by automatically detecting timestamps, target values, and series IDs.
  • Case 2: Generating reusable Python transformation scripts for SQL databases to ensure data pipelines consistently output forecasting-ready datasets.
  • Case 3: Establishing schema contracts and validation rules for data engineering teams to maintain high data quality and prevent 'no timestamp' or 'non-numeric target' errors during model training.
  • Case 4: Preparing complex dbt models for integration with forecasting tools like TimeGPT or StatsForecast by automating column renaming and type casting.
namenixtla-schema-mapper
description"Transform data sources to Nixtla schema (unique_id, ds, y) with column inference. Use when preparing data for forecasting. Trigger with 'map to Nixtla schema' or 'transform data'."
allowed-tools"Read,Write,Glob,Grep,Edit"
version"1.1.0"
author"Jeremy Longshore <jeremy@intentsolutions.io>"
licenseMIT

Nixtla Schema Mapper

Transform data sources to Nixtla-compatible schema (unique_id, ds, y).

Overview

This skill automates data transformation:

  • Column inference: Detects timestamp, target, and ID columns
  • Code generation: Python modules for CSV/SQL/Parquet/dbt
  • Schema contracts: Documentation with validation rules
  • Quality checks: Validates transformed data

Prerequisites

Required:

  • Python 3.8+
  • pandas

Optional:

  • pyarrow: For Parquet support
  • sqlalchemy: For SQL sources
  • dbt-core: For dbt models

Installation:

pip install pandas pyarrow sqlalchemy

Instructions

Step 1: Identify Data Source

Supported formats:

  • CSV/Parquet files
  • SQL tables or queries
  • dbt models

Step 2: Analyze Schema

python {baseDir}/scripts/analyze_schema.py --input data/sales.csv

Output:

Detected columns:
  Timestamp: 'date' (datetime64)
  Target: 'sales' (float64)
  Series ID: 'store_id' (object)
  Exogenous: price, promotion

Step 3: Generate Transformation

python {baseDir}/scripts/generate_transform.py \
    --input data/sales.csv \
    --id_col store_id \
    --date_col date \
    --target_col sales \
    --output data/transform/to_nixtla_schema.py

Step 4: Create Schema Contract

python {baseDir}/scripts/create_contract.py \
    --mapping mapping.json \
    --output NIXTLA_SCHEMA_CONTRACT.md

Step 5: Validate Transformation

python data/transform/to_nixtla_schema.py

Output

  • data/transform/to_nixtla_schema.py: Transformation module
  • NIXTLA_SCHEMA_CONTRACT.md: Schema documentation
  • nixtla_data.csv: Transformed data (optional)

Error Handling

  1. Error: No timestamp column detected Solution: Specify manually with --date_col

  2. Error: Multiple target candidates Solution: Specify manually with --target_col

  3. Error: Date parsing failed Solution: Specify format with --date_format "%Y-%m-%d"

  4. Error: Non-numeric target column Solution: Check for string values, use pd.to_numeric(errors='coerce')

Examples

Example 1: CSV Transformation

python {baseDir}/scripts/generate_transform.py \
    --input sales.csv \
    --id_col product_id \
    --date_col timestamp \
    --target_col revenue

Generated code:

def to_nixtla_schema(path="sales.csv"):
    df = pd.read_csv(path)
    df = df.rename(columns={
        'product_id': 'unique_id',
        'timestamp': 'ds',
        'revenue': 'y'
    })
    df['ds'] = pd.to_datetime(df['ds'])
    return df[['unique_id', 'ds', 'y']]

Example 2: SQL Source

python {baseDir}/scripts/generate_transform.py \
    --sql "SELECT * FROM daily_sales" \
    --connection postgresql://localhost/db \
    --id_col store_id \
    --date_col sale_date \
    --target_col amount

Resources

Related Skills:

  • nixtla-timegpt-lab: Use transformed data for forecasting
  • nixtla-experiment-architect: Reference in experiments