iris-meteo 0.0.1

package/README.md

@@ -0,0 +1,80 @@
+# Iris Weather CLI
+
+A command-line tool for correlating any CSV data with historical weather data from Open-Meteo.
+
+## Features
+
+- **CSV-Weather Correlation**: Analyze relationships between any CSV data and weather conditions
+- **Historical Data**: Use Open-Meteo archive endpoint for past dates
+- **Flexible Filtering**: Filter both CSV and weather data
+- **Comprehensive Statistics**: Pearson correlation, R-squared, and detailed analysis
+- **Multiple Weather Parameters**: Temperature, precipitation, wind speed, etc.
+
+## Installation
+
+```bash
+npm install iris-meteo -g
+```
+
+Refer to the open-meteo docs for how to install and run a local instance: [https://github.com/open-meteo/open-meteo/blob/main/docs/getting-started.md](https://github.com/open-meteo/open-meteo/blob/main/docs/getting-started.md)
+
+## Basic Usage
+
+### Correlate data with temperature
+```bash
+iris --csv data.csv --latitude 52.52 --longitude 13.41
+```
+
+
+
+### Filter data before correlation
+```bash
+iris --csv data.csv --latitude 52.52 --longitude 13.41 \
+     --filter "amount > 1000" --weather-filter "temperature_2m > 15"
+```
+
+### Custom field names and parameters
+```bash
+iris --csv energy_data.csv --csv-date "timestamp" --csv-value "kwh_used" \
+     --weather-param precipitation --latitude 51.5074 --longitude -0.1278
+```
+
+## Options
+
+```
+Usage: iris [options]
+
+Options:
+  -V, --version          output the version number
+  --csv <file>           Load weather data from CSV file
+  --filter <expression>  Filter CSV data using expressions like "temperature_2m:15" or "temperature_2m > 20"
+  --api-url <url>        Open-Meteo API URL (for local instances) (default: "http://localhost:8080/v1/forecast")
+  --latitude <lat>       Latitude for API requests
+  --longitude <lon>      Longitude for API requests
+  --parameter <param>    Weather parameter to analyze (e.g., temperature_2m, precipitation) (default: "temperature_2m")
+  --output <file>        Output file for results
+  --verbose              Show detailed output (default: false)
+  --o <filter>           Filter API response data using expressions like "temperature_2m > 20" or "precipitation <= 5"
+  --correlate            Analyze correlation between CSV and API data (default: false)
+  -h, --help             display help for command
+```
+
+
+### Supported Date Formats
+The tool supports multiple date formats for international compatibility:
+
+- **ISO Format**: `YYYY-MM-DD` (e.g., `2023-01-15`)
+- **European Format**: `DD.MM.YYYY` (e.g., `15.01.2023`)
+- **US Format**: `MM/DD/YYYY` (e.g., `01/15/2023`)
+- **ISO with Time**: `YYYY-MM-DDTHH:MM` (e.g., `2023-01-15T14:30`)
+
+The tool will automatically detect and normalize all supported date formats to match with weather data.
+
+## Requirements
+
+- Node.js 12+
+- Local Open-Meteo instance (for API features)
+- Internet connection (only if using public Open-Meteo API)
+
+## License
+ISC

package/index.js

@@ -0,0 +1,585 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const fs = require('fs');
+const csv = require('csv-parser');
+const axios = require('axios');
+const path = require('path');
+
+const program = new Command();
+
+program
+  .name('iris')
+  .description('CLI tool for correlating any CSV data with weather data from open-meteo.com')
+  .version('1.0.0');
+
+program
+  .option('--csv <file>', 'Load data from CSV file (must contain date column)')
+  .option('--csv-date <field>', 'CSV date field name', 'date')
+  .option('--csv-value <field>', 'CSV value field to correlate with weather', 'sales_amount')
+  .option('--weather-param <param>', 'Daily weather parameter to correlate with (e.g., temperature_2m_max, precipitation_sum, windspeed_10m_max)', 'temperature_2m_max')
+  .option('--api-url <url>', 'Open-Meteo API URL (for local instances)', 'http://localhost:8080/v1/forecast')
+  .option('--latitude <lat>', 'Latitude for weather data')
+  .option('--longitude <lon>', 'Longitude for weather data')
+  .option('--start-date <date>', 'Start date for analysis (YYYY-MM-DD)')
+  .option('--end-date <date>', 'End date for analysis (YYYY-MM-DD)')
+  .option('--filter <expression>', 'Filter CSV data using expressions like "sales_amount > 1000"')
+  .option('--weather-filter <expression>', 'Filter weather data using expressions like "temperature_2m > 15"')
+  .option('--output <file>', 'Output file for correlation results')
+  .option('--verbose', 'Show detailed correlation analysis', false);
+
+program.parse(process.argv);
+
+const options = program.opts();
+
+// Main function to handle the CLI logic
+async function main() {
+  try {
+    // Validate required options
+    if (!options.csv) {
+      console.error('Error: --csv option is required');
+      program.help();
+      process.exit(1);
+    }
+
+    if (!options.latitude || !options.longitude) {
+      console.error('Error: Both --latitude and --longitude are required');
+      program.help();
+      process.exit(1);
+    }
+
+    console.log('Iris Weather Correlation Analysis');
+    console.log('=================================');
+
+    // Load CSV data
+    const csvData = await loadAndProcessCsvData(options);
+    console.log(`Loaded ${csvData.length} records from CSV file`);
+
+    // Apply CSV filtering if specified
+    let filteredCsvData = csvData;
+    if (options.filter) {
+      filteredCsvData = filterCsvData(csvData, options.filter);
+      console.log(`🔍 Filtered CSV to ${filteredCsvData.length} records`);
+    }
+
+    // Determine date range for weather data
+    const dateRange = determineDateRange(filteredCsvData, options);
+    console.log(`Analyzing date range: ${dateRange.start} to ${dateRange.end}`);
+
+    // Fetch weather data
+    const weatherData = await fetchWeatherData(options, dateRange);
+    console.log(`Fetched ${weatherData.length} weather records from Open-Meteo API`);
+
+    // Apply weather filtering if specified
+    let filteredWeatherData = weatherData;
+    if (options.weatherFilter) {
+      filteredWeatherData = filterWeatherData(weatherData, options.weatherFilter);
+      console.log(`🌡️ Filtered weather data to ${filteredWeatherData.length} records`);
+    }
+
+    // Match CSV data with weather data by date
+    const matchedData = matchDataByDate(filteredCsvData, filteredWeatherData, options);
+    console.log(`Found ${matchedData.length} matching date pairs`);
+
+    if (matchedData.length < 2) {
+      console.warn('⚠️  Insufficient data for meaningful correlation analysis');
+      console.warn('   Try adjusting your date range or filters');
+      return;
+    }
+
+    // Perform correlation analysis
+    const correlationResults = analyzeCorrelation(matchedData, options);
+    displayCorrelationResults(correlationResults, options);
+
+    // Save results if requested
+    if (options.output) {
+      saveResultsToFile(correlationResults, options.output);
+      console.log(`💾 Results saved to ${options.output}`);
+    }
+
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    if (options.verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Load and process CSV data
+function loadAndProcessCsvData(options) {
+  return new Promise((resolve, reject) => {
+    if (!fs.existsSync(options.csv)) {
+      reject(new Error(`CSV file not found: ${options.csv}`));
+      return;
+    }
+
+    const results = [];
+    fs.createReadStream(options.csv)
+      .pipe(csv())
+      .on('data', (data) => results.push(data))
+      .on('end', () => {
+        if (results.length === 0) {
+          reject(new Error('CSV file is empty or contains no valid data'));
+        }
+        
+        // Validate that required fields exist
+        if (!results[0].hasOwnProperty(options.csvDate)) {
+          reject(new Error(`CSV file does not contain a '${options.csvDate}' field`));
+        }
+        
+        if (!results[0].hasOwnProperty(options.csvValue)) {
+          reject(new Error(`CSV file does not contain a '${options.csvValue}' field`));
+        }
+        
+        resolve(results);
+      })
+      .on('error', (error) => reject(new Error(`Error reading CSV file: ${error.message}`)));
+  });
+}
+
+// Determine date range for analysis
+function determineDateRange(csvData, options) {
+  // Parse and normalize dates from CSV data
+  const dateObjects = [];
+  const validDates = [];
+  
+  csvData.forEach(item => {
+    let dateStr = item[options.csvDate];
+    
+    // Remove time portion if present
+    if (dateStr.includes('T')) {
+      dateStr = dateStr.split('T')[0];
+    }
+    
+    // Try to parse the date in various formats
+    const parsedDate = parseFlexibleDate(dateStr);
+    if (parsedDate) {
+      dateObjects.push(parsedDate);
+      validDates.push(dateStr);
+    }
+  });
+
+  if (dateObjects.length === 0) {
+    throw new Error('No valid dates found in CSV data. Supported formats: YYYY-MM-DD, DD.MM.YYYY, MM/DD/YYYY');
+  }
+
+  // Sort dates to find min and max
+  dateObjects.sort((a, b) => a - b);
+  
+  // Format dates back to YYYY-MM-DD for API
+  const formatDate = (date) => {
+    return date.toISOString().split('T')[0];
+  };
+  
+  const startDate = options.startDate || formatDate(dateObjects[0]);
+  const endDate = options.endDate || formatDate(dateObjects[dateObjects.length - 1]);
+
+  return { start: startDate, end: endDate };
+}
+
+// Parse dates in multiple formats
+function parseFlexibleDate(dateStr) {
+  // Try ISO format first (YYYY-MM-DD)
+  if (dateStr.match(/^\d{4}-\d{2}-\d{2}$/)) {
+    const date = new Date(dateStr);
+    if (!isNaN(date.getTime())) return date;
+  }
+
+  // Try European format (DD.MM.YYYY)
+  if (dateStr.match(/^\d{2}\.\d{2}\.\d{4}$/)) {
+    const parts = dateStr.split('.');
+    const date = new Date(`${parts[2]}-${parts[1]}-${parts[0]}`);
+    if (!isNaN(date.getTime())) return date;
+  }
+
+  // Try US format (MM/DD/YYYY)
+  if (dateStr.match(/^\d{2}\/\d{2}\/\d{4}$/)) {
+    const parts = dateStr.split('/');
+    const date = new Date(`${parts[2]}-${parts[0]}-${parts[1]}`);
+    if (!isNaN(date.getTime())) return date;
+  }
+
+  // Try ISO with time (YYYY-MM-DDTHH:MM)
+  if (dateStr.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/)) {
+    const date = new Date(dateStr);
+    if (!isNaN(date.getTime())) return date;
+  }
+
+  return null;
+}
+
+// Fetch weather data from Open-Meteo API
+async function fetchWeatherData(options, dateRange) {
+  try {
+        let apiUrl = options.apiUrl;
+
+    // Map old hourly parameter names to their daily equivalents
+    const parameterMapping = {
+      'temperature_2m': 'temperature_2m_max',
+      'temperature': 'temperature_2m_max',
+      'temp': 'temperature_2m_max',
+      'precipitation': 'precipitation_sum',
+      'rain': 'rain_sum',
+      'windspeed': 'windspeed_10m_max',
+      'wind': 'windspeed_10m_max'
+    };
+
+    // Apply parameter mapping if needed
+    let weatherParam = options.weatherParam;
+    if (parameterMapping[weatherParam]) {
+      console.log(`🔄 Mapping parameter '${weatherParam}' to daily equivalent '${parameterMapping[weatherParam]}'`);
+      weatherParam = parameterMapping[weatherParam];
+    }
+
+    const params = {
+      latitude: options.latitude,
+      longitude: options.longitude,
+      daily: weatherParam,
+      start_date: dateRange.start,
+      end_date: dateRange.end,
+      timezone: 'auto',
+      models: 'ecmwf_ifs025'
+    };
+
+    console.log(`Connecting to Open-Meteo API at: ${apiUrl}`);
+    
+    const response = await axios.get(apiUrl, { params });
+    
+    if (!response.data || !response.data.daily) {
+      throw new Error('Invalid API response format - expected daily weather data');
+    }
+
+    const dailyData = response.data.daily;
+    const timeData = dailyData.time;
+    const parameterData = dailyData[weatherParam];
+    
+    if (!timeData || !parameterData || timeData.length !== parameterData.length) {
+      throw new Error('Inconsistent data in API response');
+    }
+
+    // Convert to date-value pairs for daily data
+    const results = [];
+    for (let i = 0; i < timeData.length; i++) {
+      results.push({
+        date: timeData[i],
+        [options.weatherParam]: parameterData[i]  // Use original parameter name for consistency
+      });
+    }
+
+    return results;
+  } catch (error) {
+    throw new Error(`Failed to fetch weather data: ${error.message}`);
+  }
+}
+
+
+
+// Filter CSV data
+function filterCsvData(data, filterExpression) {
+  const [field, operator, value] = parseFilterExpression(filterExpression);
+  
+  return data.filter(item => {
+    const itemValue = parseFloat(item[field]);
+    const filterValue = parseFloat(value);
+    
+    if (isNaN(itemValue) || isNaN(filterValue)) {
+      return false;
+    }
+    
+    switch (operator) {
+      case '=':
+      case ':':
+        return itemValue === filterValue;
+      case '>':
+        return itemValue > filterValue;
+      case '<':
+        return itemValue < filterValue;
+      case '>=':
+        return itemValue >= filterValue;
+      case '<=':
+        return itemValue <= filterValue;
+      case '!=':
+        return itemValue !== filterValue;
+      default:
+        return false;
+    }
+  });
+}
+
+// Filter weather data
+function filterWeatherData(data, filterExpression) {
+  const [field, operator, value] = parseFilterExpression(filterExpression);
+  
+  return data.filter(item => {
+    const itemValue = parseFloat(item[field]);
+    const filterValue = parseFloat(value);
+    
+    if (isNaN(itemValue) || isNaN(filterValue)) {
+      return false;
+    }
+    
+    switch (operator) {
+      case '=':
+      case ':':
+        return itemValue === filterValue;
+      case '>':
+        return itemValue > filterValue;
+      case '<':
+        return itemValue < filterValue;
+      case '>=':
+        return itemValue >= filterValue;
+      case '<=':
+        return itemValue <= filterValue;
+      case '!=':
+        return itemValue !== filterValue;
+      default:
+        return false;
+    }
+  });
+}
+
+// Helper function to parse numbers in German format (commas as thousand separators, periods as decimals)
+function parseGermanNumber(value) {
+  if (typeof value !== 'string') {
+    return parseFloat(value);
+  }
+  
+  // Remove thousand separators (commas) and replace decimal points with dots
+  const cleanedValue = value.replace(/\./g, '').replace(/,/g, '.');
+  return parseFloat(cleanedValue);
+}
+
+// Match CSV data with weather data by date
+function matchDataByDate(csvData, weatherData, options) {
+  const matchedPairs = [];
+  
+  // Create a map of weather data by date for faster lookup
+  const weatherMap = {};
+  weatherData.forEach(weatherItem => {
+    const date = weatherItem.date;
+    if (!weatherMap[date]) {
+      weatherMap[date] = [];
+    }
+    weatherMap[date].push(weatherItem);
+  });
+
+  // Match each CSV record with corresponding weather data
+  csvData.forEach(csvItem => {
+    // Extract and normalize date
+    let dateStr = csvItem[options.csvDate];
+    
+    // Parse the CSV date to get the normalized format (YYYY-MM-DD)
+    const parsedDate = parseFlexibleDate(dateStr);
+    if (!parsedDate) {
+      console.warn(`⚠️  Skipping record with unparseable date: ${dateStr}`);
+      return;
+    }
+    
+    // Format as YYYY-MM-DD for matching
+    const normalizedDate = parsedDate.toISOString().split('T')[0];
+    
+    // Find matching weather data
+    if (weatherMap[normalizedDate] && weatherMap[normalizedDate].length > 0) {
+      // Use the first weather record for the day (could be enhanced to use average, etc.)
+      const weatherItem = weatherMap[normalizedDate][0];
+      
+      const csvValue = parseGermanNumber(csvItem[options.csvValue]);
+      const weatherValue = parseFloat(weatherItem[options.weatherParam]);
+      
+      // Debug logging removed
+      
+      matchedPairs.push({
+        date: normalizedDate,
+        originalDate: dateStr,
+        csvValue: csvValue,
+        weatherValue: weatherValue,
+        csvData: csvItem,
+        weatherData: weatherItem
+      });
+    } else {
+      console.warn(`⚠️  No weather data found for date: ${normalizedDate} (original: ${dateStr})`);
+    }
+  });
+
+  return matchedPairs;
+}
+
+// Parse filter expression
+function parseFilterExpression(expression) {
+  // Handle equality operators (= or :)
+  const equalityMatch = expression.match(/^(\w+)\s*(=|:)\s*(\S+)$/);
+  if (equalityMatch) {
+    return [equalityMatch[1], '=', equalityMatch[3]];
+  }
+
+  // Handle comparison operators
+  const comparisonMatch = expression.match(/^(\w+)\s*(>=|<=|>|<|!=)\s*(\S+)$/);
+  if (comparisonMatch) {
+    return [comparisonMatch[1], comparisonMatch[2], comparisonMatch[3]];
+  }
+
+  throw new Error(`Invalid filter expression: ${expression}. Use format like "field:value" or "field > value"`);
+}
+
+// Analyze correlation between CSV values and weather data
+function analyzeCorrelation(matchedData, options) {
+  // Extract values
+  const csvValues = [];
+  const weatherValues = [];
+  
+  matchedData.forEach(pair => {
+    if (!isNaN(pair.csvValue) && !isNaN(pair.weatherValue)) {
+      csvValues.push(pair.csvValue);
+      weatherValues.push(pair.weatherValue);
+    }
+  });
+
+  // Debug logging removed
+
+  if (csvValues.length < 2) {
+    return {
+      csvField: options.csvValue,
+      weatherParam: options.weatherParam,
+      dataPoints: csvValues.length,
+      correlation: null,
+      rSquared: null,
+      message: 'Insufficient matching data points for correlation analysis'
+    };
+  }
+
+  // Calculate Pearson correlation coefficient
+  const correlation = calculatePearsonCorrelation(csvValues, weatherValues);
+  const rSquared = Math.pow(correlation, 2);
+
+  // Calculate additional statistics
+  const csvStats = calculateBasicStats(csvValues);
+  const weatherStats = calculateBasicStats(weatherValues);
+
+  return {
+    csvField: options.csvValue,
+    weatherParam: options.weatherParam,
+    dataPoints: csvValues.length,
+    correlation: correlation,
+    rSquared: rSquared,
+    interpretation: interpretCorrelation(correlation),
+    csvStats: csvStats,
+    weatherStats: weatherStats,
+    matchedData: matchedData
+  };
+}
+
+// Calculate basic statistics
+function calculateBasicStats(values) {
+  if (values.length === 0) {
+    return {
+      min: null,
+      max: null,
+      average: null,
+      median: null
+    };
+  }
+
+  const sortedValues = [...values].sort((a, b) => a - b);
+
+  return {
+    min: Math.min(...values),
+    max: Math.max(...values),
+    average: values.reduce((sum, val) => sum + val, 0) / values.length,
+    median: calculateMedian(sortedValues)
+  };
+}
+
+// Calculate median value
+function calculateMedian(sortedValues) {
+  const middle = Math.floor(sortedValues.length / 2);
+  
+  if (sortedValues.length % 2 === 0) {
+    return (sortedValues[middle - 1] + sortedValues[middle]) / 2;
+  } else {
+    return sortedValues[middle];
+  }
+}
+
+// Calculate Pearson correlation coefficient
+function calculatePearsonCorrelation(x, y) {
+  const n = x.length;
+  
+  // Calculate means
+  const meanX = x.reduce((sum, val) => sum + val, 0) / n;
+  const meanY = y.reduce((sum, val) => sum + val, 0) / n;
+  
+  // Calculate covariance and standard deviations
+  let covariance = 0;
+  let stdDevX = 0;
+  let stdDevY = 0;
+  
+  for (let i = 0; i < n; i++) {
+    const diffX = x[i] - meanX;
+    const diffY = y[i] - meanY;
+    covariance += diffX * diffY;
+    stdDevX += Math.pow(diffX, 2);
+    stdDevY += Math.pow(diffY, 2);
+  }
+  
+  // Handle division by zero
+  if (stdDevX === 0 || stdDevY === 0) {
+    return 0;
+  }
+  
+  return covariance / (Math.sqrt(stdDevX) * Math.sqrt(stdDevY));
+}
+
+// Interpret correlation coefficient
+function interpretCorrelation(r) {
+  const absR = Math.abs(r);
+  
+  if (absR >= 0.9) return 'Very strong correlation';
+  if (absR >= 0.7) return 'Strong correlation';
+  if (absR >= 0.5) return 'Moderate correlation';
+  if (absR >= 0.3) return 'Weak correlation';
+  return 'No or negligible correlation';
+}
+
+// Display correlation results
+function displayCorrelationResults(results, options) {
+  console.log('\nCorrelation Analysis Results');
+  console.log('============================');
+  console.log(`CSV Field: ${results.csvField}`);
+  console.log(`Weather Parameter: ${results.weatherParam}`);
+  console.log(`Data Points Analyzed: ${results.dataPoints}`);
+  
+  if (results.correlation !== null) {
+    console.log(`\nStatistical Results:`);
+    console.log(`   Pearson Correlation (r): ${results.correlation.toFixed(4)}`);
+    console.log(`   R-squared: ${results.rSquared.toFixed(4)}`);
+    console.log(`   Interpretation: ${results.interpretation}`);
+    
+
+  } else {
+    console.log(`${results.message}`);
+  }
+}
+
+// Save results to file
+function saveResultsToFile(results, filePath) {
+  const output = {
+    timestamp: new Date().toISOString(),
+    analysisType: 'CSV-Weather Correlation',
+    correlationResults: {
+      csvField: results.csvField,
+      weatherParam: results.weatherParam,
+      dataPoints: results.dataPoints,
+      correlation: results.correlation,
+      rSquared: results.rSquared,
+      interpretation: results.interpretation,
+      csvStats: results.csvStats,
+      weatherStats: results.weatherStats
+    }
+  };
+  
+  fs.writeFileSync(filePath, JSON.stringify(output, null, 2), 'utf8');
+}
+
+// Start the application
+main();

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "iris-meteo",
+  "version": "0.0.1",
+  "description": "CLI tool for analyzing weather data with  open-meteo.com",
+  "main": "index.js",
+  "bin": {
+    "iris": "./index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node index.js"
+  },
+  "keywords": ["weather", "cli", "open-meteo", "analysis"],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "axios": "^1.13.5",
+    "commander": "^14.0.3",
+    "csv-parser": "^3.2.0"
+  }
+}