klio 1.4.7 → 1.4.9

package/README.md

@@ -86,17 +86,21 @@ klio --gui --gui-port 8080
 ### Health Analysis
 It's possible to analyze Apple Health data. This happens on the device and no server is involved like everything from this CLI. It just parses the export XML.
 
-- **Apple Health Export**: `klio [planet] --apple <filepath> --sleep ` - Analyzes Apple Health Export XML file and shows the most frequent aspects during sleep deprivation (Top 10):
+- **Sleep analysis**: `klio [planet] --apple <filepath> --sleep ` - Analyzes Apple Health Export XML file and shows the most frequent aspects during sleep deprivation (Top 10):
 - **Step analysis**: `klio [planet] --apple <filepath> --steps` - Analyzes step patterns of any planet
 - **Stress analysis**: `klio [planet] --apple <filepath> --stress` - Analyzes stress patterns of planet sign stress based on HRV
+- **Late night analysis**: `klio [planet] --apple <filepath> --night` - Analyzes late night sleep patterns (after 2am) and shows the most frequent aspects during these times
+- **All-nighter analysis**: `klio [planet] --apple <filepath> --night-all` - Analyzes all-nighter sleep patterns (starting at 04:00 or 06:00) and shows the most frequent aspects during these times
 
 ### CSV Analysis
 It's possible to analyze a csv with a column of either ISO date time or unix time stamp. 
 
 - **Show house and sign distribution of the datetime column**: `klio [planet] --csv <file-path>`
 - **Show aspect type distribution between two planets:** `klio [planet1] [planet2] --csv <file-path> --a`
+- **Filter CSV data by column value:** `klio [planet] --csv <file-path> --filter "column:value"` (e.g., `--filter "Item:coffee"`)
+- **Creating a bar chart**: Create a bar chart and save the image to the downloads' folder. The image shows the aspect distribution of your csv datetime values: `klio moon sun --csv /home/user/Downloads/coffee.csv  --filter "Item:cookie" --a --title "Eaten cookies during sun-moon aspects"`
 
-The command also returns a Chi-Square. 
+- The command also returns a Chi-Square. 
 
 ### Adding different charts
 
@@ -107,7 +111,7 @@ The command also returns a Chi-Square.
   - `--people` - Lists all saved persons
   - `--delete-person <id>` - Deletes a person
 
-Then, instead using `--i` for the commands from above you can use `--wp <id>` i.e. `--wp john`
+Then, instead using `--i` for the commands from above you can use `--wp <id>` or  `--wp john`
 
 ### Advanced Features
 
@@ -117,11 +121,21 @@ Then, instead using `--i` for the commands from above you can use `--wp <id>` i.
 - **Aspect figures**: `klio --af` - Shows active aspect figures like T-squares, Grand Trines, etc. Combine with `--wp <id>` or `--i` or `--d <"DD.MM.YYYY HH:MM>` or `--hs <house-system>`
 - **Transits**: `klio --tr` - Shows personal transits based on birth data. Combine with `--wp <id or --i>` and optional  `--d <"DD.MM.YYYY HH:MM>`
 - **Transit Houses**: `klio --s --tra --i`
+
+
+
 ### Past and Future Aspects
 
 - **Past aspects**: `klio --v <count> [planet1] [aspect-type] [planet2]` - Shows past aspects (Format: --v <count> planet1 aspectType planet2) Available aspect types: c, o, s, t, se (conjunction, opposition, square, trine, sextile)
 - **Future aspects**: `klio --z <count> [planet1] [aspect-type] [planet2]` - Shows future aspects (Format: --z <count> planet1 aspectType planet2)
 
+### Reference
+- **Transit frequency**: `[planet1] [aspect-type] [planet2] --o` - Calculates how often a transit occurs in the sky using astronomical synodic periods
+  - **Example**: `klio saturn c neptune --o` - Shows Saturn-Neptune conjunction frequency
+  - **Example**: `klio jupiter s pluto --o` - Shows Jupiter-Pluto square frequency
+  - **Aspect types**: c (conjunction), o (opposition), s (square), t (trine), se (sextile), q (quincunx)
+  - **Output**: Shows frequency in readable format (e.g., "every 36 years") with approximate
+
 ### Planet Ingresses
 
 - **Planet ingress**: `klio [planet] --in [count]` - Shows when a planet enters a new zodiac sign. Optional count parameter for multiple ingresses (default: 1). Works with any planet (moon, mercury, venus, etc.)
@@ -132,7 +146,7 @@ Then, instead using `--i` for the commands from above you can use `--wp <id>` i.
 ### Wikidata Integration
 
 - **Search for people with specific aspects**: `[planet1] [aspect-type] [planet2] --wiki <occupation> [limit]` - Searches Wikidata for people with specific astrological aspects
-  - **Available occupations**: authors, scientists, artists, musicians, politicians, actors, philosophers
+  - **Available occupations for now**: authors, scientists, artists, musicians, politicians, actors, philosophers
   - **Aspect types**: c (conjunction), o (opposition), s (square), t (trine), se (sextile), q (quincunx)
   - **Example**: `klio moon c neptune --wiki authors 50` - Tries to find authors with Moon conjunct Neptune aspect with a limit of 50. Is faster but less common aspects are maybe not found with 50
   - **Example**: `klio saturn s pluto --wiki scientists 100` - Finds scientists with Saturn square Pluto aspect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klio",
-  "version": "1.4.7",
+  "version": "1.4.9",
   "description": "A CLI for astrological calculations",
   "main": "src/main.js",
   "bin": {

package/src/astrology/astrologyService.js

@@ -1900,7 +1900,39 @@ function analyzeSignDistributionSignificance(signDistribution) {
   };
 }
 
-function analyzeCSVWithDatetime(filePath, planetName = 'moon', houseSystem = 'koch', analyzeAspects = false, partnerPlanet = null) {
+// Helper function to parse filter criteria
+function parseFilterCriteria(filterString) {
+  if (!filterString) return null;
+  
+  const parts = filterString.split(':');
+  if (parts.length !== 2) {
+    console.warn('Invalid filter format. Expected "column:value"');
+    return null;
+  }
+  
+  return {
+    column: parts[0].trim(),
+    value: parts[1].trim()
+  };
+}
+
+// Helper function to apply filter to records
+function applyFilter(records, filterCriteria) {
+  if (!filterCriteria || !records || records.length === 0) return records;
+  
+  const parsedCriteria = typeof filterCriteria === 'string' 
+    ? parseFilterCriteria(filterCriteria) 
+    : filterCriteria;
+  
+  if (!parsedCriteria) return records;
+  
+  return records.filter(record => {
+    const recordValue = record[parsedCriteria.column];
+    return recordValue && recordValue.toString() === parsedCriteria.value;
+  });
+}
+
+function analyzeCSVWithDatetime(filePath, planetName = 'moon', houseSystem = 'koch', analyzeAspects = false, partnerPlanet = null, filterCriteria = null) {
   return new Promise(async (resolve, reject) => {
     const results = [];
     let pendingOperations = 0;
@@ -1967,8 +1999,11 @@ function analyzeCSVWithDatetime(filePath, planetName = 'moon', houseSystem = 'ko
           skip_empty_lines: true
         });
 
+        // Apply filter if specified
+        const filteredRecords = filterCriteria ? applyFilter(records, filterCriteria) : records;
+
         // Process each row
-        for (const data of records) {
+        for (const data of filteredRecords) {
           // Look for a column with ISO-Datetime values or Unix-Timestamps
           const datetimeColumns = Object.keys(data).filter(key => {
             const value = data[key];
@@ -2107,6 +2142,20 @@ function analyzeCSVWithDatetime(filePath, planetName = 'moon', houseSystem = 'ko
       fs.createReadStream(filePath)
           .pipe(csvParser())
           .on('data', (data) => {
+            // Apply filter if specified
+            if (filterCriteria) {
+              const parsedCriteria = typeof filterCriteria === 'string' 
+                ? parseFilterCriteria(filterCriteria) 
+                : filterCriteria;
+              
+              if (parsedCriteria) {
+                const recordValue = data[parsedCriteria.column];
+                if (!recordValue || recordValue.toString() !== parsedCriteria.value) {
+                  return; // Skip this record
+                }
+              }
+            }
+
             // Look for a column with ISO-Datetime values or Unix-Timestamps
             const datetimeColumns = Object.keys(data).filter(key => {
               const value = data[key];
@@ -2780,5 +2829,91 @@ module.exports = {
   showPlanetComboAspects,
   calculateNextPlanetIngress,
   calculateAstrologicalAngles,
-  longitudeToSignDegree
+  longitudeToSignDegree,
+  calculateTransitFrequency
 };
+
+// Function to calculate how often a transit occurs between two planets
+function calculateTransitFrequency(planet1, planet2, aspectType) {
+  // Use astronomical synodic period calculation for more accurate results
+  const orbitalPeriods = {
+    'sun': 1, // Not applicable for conjunctions, but included for completeness
+    'moon': 0.0748, // 27.3 days
+    'mercury': 0.2408, // 87.97 days
+    'venus': 0.6152, // 224.7 days
+    'mars': 1.8808, // 686.98 days
+    'jupiter': 11.862, // 11.862 years
+    'saturn': 29.457, // 29.457 years
+    'uranus': 84.016, // 84.016 years
+    'neptune': 164.79, // 164.79 years
+    'pluto': 248.09 // 248.09 years
+  };
+  
+  // Get orbital periods for the two planets
+  const period1 = orbitalPeriods[planet1];
+  const period2 = orbitalPeriods[planet2];
+  
+  if (!period1 || !period2) {
+    return {
+      frequency: 'Cannot calculate frequency: unknown orbital periods',
+      averageInterval: null,
+      aspects: []
+    };
+  }
+  
+  // Calculate synodic period using the formula: 1/S = |1/P1 - 1/P2|
+  // For conjunctions, we use the absolute difference
+  const synodicPeriod = 1 / Math.abs(1/period1 - 1/period2);
+  
+  // Convert to days
+  const averageIntervalDays = synodicPeriod * 365.25;
+  
+  // Format the frequency in a more readable way
+  const formattedFrequency = formatFrequency(averageIntervalDays);
+  
+  // Also calculate some actual aspects for reference
+  const futureAspects = getFutureAspects(planet1, planet2, aspectType, 5);
+  
+  return {
+    frequency: formattedFrequency,
+    frequencyShort: `Approximately every ${synodicPeriod.toFixed(1)} years`,
+    averageInterval: averageIntervalDays,
+    averageIntervalYears: synodicPeriod,
+    intervals: [], // Not applicable for this calculation method
+    aspects: futureAspects,
+    note: `Note: Frequency calculated using astronomical synodic period (1/S = |1/${period1} - 1/${period2}| years)`
+  };
+}
+
+// Helper function to format frequency in a readable way
+function formatFrequency(days) {
+  if (days < 30) {
+    return `Approximately every ${Math.round(days)} days`;
+  } else if (days < 90) {
+    const months = days / 30;
+    return `Approximately every ${Math.round(months)} months`;
+  } else if (days < 365) {
+    const months = days / 30;
+    return `Approximately every ${Math.round(months)} months`;
+  } else if (days < 730) {
+    const years = days / 365.25;
+    const months = (years - Math.floor(years)) * 12;
+    if (months >= 9) {
+      return `Approximately every ${Math.floor(years) + 1} years`;
+    } else if (months >= 1) {
+      return `Approximately every ${Math.floor(years)} years, ${Math.round(months)} months`;
+    } else {
+      return `Approximately every ${Math.floor(years)} years`;
+    }
+  } else {
+    const years = days / 365.25;
+    const months = (years - Math.floor(years)) * 12;
+    if (months >= 9) {
+      return `Approximately every ${Math.floor(years) + 1} years`;
+    } else if (months >= 1) {
+      return `Approximately every ${Math.floor(years)} years, ${Math.round(months)} months`;
+    } else {
+      return `Approximately every ${Math.round(years)} years`;
+    }
+  }
+}

package/src/cli/cli.js

@@ -1,16 +1,26 @@
 const { Command } = require('commander');
 const { planets, signs } = require('../astrology/astrologyConstants');
 const { showRetrogradePlanets } = require('../astrology/retrogradeService');
-const { getCurrentTimeInTimezone, showAspectFigures, analyzeElementDistribution, getTimezoneOffset, calculateJulianDayUTC, calculateHouses, getAstrologicalData, getPlanetHouse, showPlanetAspects, calculatePlanetAspects, getAllActiveAspects, showAllActiveAspects, getBirthDataFromConfig, getPersonDataFromConfig, detectAspectFigures, calculatePersonalTransits, showPersonalTransitAspects, showCombinedAnalysis, calculatePersonalTransitAspects, determineAspectPhase, findExactAspectTime, findLastExactAspectTime, getAspectAngle, getFutureAspects, getPastAspects, analyzeCSVWithDatetime, analyzeHouseDistributionSignificance, analyzeAspectDistributionSignificance, analyzeSignDistributionSignificance, calculateAspectStatistics, calculatePlanetComboAspects, showPlanetComboAspects, getCriticalPlanets, getHouseSystemCode, calculateNextPlanetIngress, calculateAstrologicalAngles, longitudeToSignDegree } = require('../astrology/astrologyService');
+const { getCurrentTimeInTimezone, showAspectFigures, analyzeElementDistribution, getTimezoneOffset, calculateJulianDayUTC, calculateHouses, getAstrologicalData, getPlanetHouse, showPlanetAspects, calculatePlanetAspects, getAllActiveAspects, showAllActiveAspects, getBirthDataFromConfig, getPersonDataFromConfig, detectAspectFigures, calculatePersonalTransits, showPersonalTransitAspects, showCombinedAnalysis, calculatePersonalTransitAspects, determineAspectPhase, findExactAspectTime, findLastExactAspectTime, getAspectAngle, getFutureAspects, getPastAspects, analyzeCSVWithDatetime, analyzeHouseDistributionSignificance, analyzeAspectDistributionSignificance, analyzeSignDistributionSignificance, calculateAspectStatistics, calculatePlanetComboAspects, showPlanetComboAspects, getCriticalPlanets, getHouseSystemCode, calculateNextPlanetIngress, calculateAstrologicalAngles, longitudeToSignDegree, calculateTransitFrequency } = require('../astrology/astrologyService');
 const { performSetup, showConfigStatus, loadConfig, setAIModel, askAIModel, setPerson1, setPerson2, setPerson, getPersonData, listPeople, deletePerson } = require('../config/configService');
 const { parseAppleHealthXML } = require('../health/healthService');
-const { analyzeStepsByPlanetSign, analyzeStressByPlanetAspects, analyzePlanetAspectsForSleep } = require('../health/healthAnalysis');
+const { analyzeStepsByPlanetSign, analyzeStressByPlanetAspects, analyzePlanetAspectsForSleep, analyzeLateNightAspects, analyzeAllNighterAspects } = require('../health/healthAnalysis');
 const { analyzeHouseDistribution, filterFilesByHouse } = require('../health/fileAnalysis');
 const { getFileCreationDate, parseDateToComponents } = require('../utils/fileUtils');
 const swisseph = require('swisseph');
 const path = require('path');
 const fs = require('fs');
 
+// Import chart generation and downloads folder utilities
+let chartGenerator = null;
+let downloadsFolder = null;
+try {
+  chartGenerator = require('../utils/chartGenerator');
+  downloadsFolder = require('../utils/downloadsFolder');
+} catch (error) {
+  console.debug('Chart generation utilities not available');
+}
+
 // Wikidata service import
 let wikidataService = null;
 try {
@@ -232,6 +242,8 @@ program
   .option('--sleep', 'Analyzes sleep patterns with moon aspects')
   .option('--steps', 'Analyzes step patterns with moon signs')
   .option('--stress', 'Analyzes stress patterns with moon aspects based on HRV')
+  .option('--night', 'Analyzes late night sleep patterns (after 2am) and common aspects')
+  .option('--night-all', 'Analyzes all-nighter sleep patterns (04:00 and 06:00 starts)')
   .option('--setup', 'Configures location and birth data for personalized calculations')
   .option('--ai <model>', 'Sets a specific AI model (e.g. "google/gemma-3n-e4b")')
   .option('--system <prompt>', 'Sets a custom system prompt for all AI requests')
@@ -263,10 +275,13 @@ program
   .option('--v <count>', 'Shows past aspects between two planets (Format: --v <count> planet1 aspectType planet2)')
   .option('--z <count>', 'Shows future aspects between two planets (Format: --z <count> planet1 aspectType planet2)')
   .option('--csv <filepath>', 'Analyzes a CSV file with ISO-Datetime values or Unix timestamps')
+  .option('--filter <column:value>', 'Filters CSV data by column:value (e.g., --filter "Item:coffee")')
+  .option('--title <title>', 'Title for the chart image (generates PNG image when provided)')
   .option('--in [count]', 'Shows next planet ingress (entering new sign). Optional count for multiple ingresses')
   .option('--wiki <occupation>', 'Fetches people from Wikidata by occupation and checks for specific aspects (Format: planet1 aspectType planet2 --wiki <occupation> [limit])')
   .option('--gui', 'Launches the web interface for command history (port 37421)')
   .option('--gui-port <port>', 'Specify custom port for GUI server')
+  .option('--o', 'Shows how often this transit occurs in the sky (frequency calculation)')
   .description('Shows astrological data for a planet')
   .action(async (planetArg, planet2Arg, options) => {
     // If planet2Arg is an object, it contains the options (commander behavior)
@@ -1492,8 +1507,9 @@ program
       const planet = planetArg ? planetArg.toLowerCase() : 'moon';
       const houseSystem = actualOptions.hs ? actualOptions.hs.toLowerCase() : 'koch';
       const analyzeAspects = actualOptions.a || false;
+      const filterCriteria = actualOptions.filter;
       
-      analyzeCSVWithDatetime(actualOptions.csv, planet, houseSystem, analyzeAspects, planet2)
+      analyzeCSVWithDatetime(actualOptions.csv, planet, houseSystem, analyzeAspects, planet2, filterCriteria)
         .then(({ results, houseDistribution, signDistribution, aspectStatistics }) => {
           if (results.length === 0) {
             console.log('No valid ISO-Datetime values found in the CSV file.');
@@ -1611,6 +1627,60 @@ program
             // Also show total number of records and house system
             console.log(`\nIn Total: ${results.length}`);
             console.log(`House system: ${houseSystem.charAt(0).toUpperCase() + houseSystem.slice(1)}`);
+            
+            // Generate chart image if --title option is provided
+            if (actualOptions.title && chartGenerator && downloadsFolder) {
+              try {
+                // Get the downloads folder path
+                const downloadsPath = downloadsFolder.getValidDownloadsFolder();
+                
+                // Create a safe filename from the title
+                const safeTitle = actualOptions.title
+                  .replace(/[^a-zA-Z0-9\s\-_.]/g, '')
+                  .substring(0, 50)
+                  .trim();
+                
+                const timestamp = new Date().toISOString()
+                  .replace(/[:.]/g, '-')
+                  .substring(0, 19);
+                
+                const filename = `${timestamp}_${safeTitle}.png`;
+                const outputPath = path.join(downloadsPath, filename);
+                
+                console.log(`\n📊 Generating chart image: ${filename}`);
+                console.log(`💾 Saving to: ${outputPath}`);
+                
+                // Calculate statistics for the chart
+                let chartStats = null;
+                if (analyzeAspects && aspectStatistics) {
+                  const { analyzeAspectDistributionSignificance } = require('../astrology/astrologyService');
+                  chartStats = analyzeAspectDistributionSignificance(aspectStatistics);
+                } else if (houseDistribution) {
+                  const { analyzeHouseDistributionSignificance } = require('../astrology/astrologyService');
+                  chartStats = analyzeHouseDistributionSignificance(houseDistribution);
+                }
+                
+                // Generate the chart
+                const chartData = {
+                  houseDistribution: houseDistribution || { counts: {}, total: results.length },
+                  aspectStatistics: aspectStatistics || { types: [], counts: {}, total: 0 },
+                  results: results,
+                  statistics: chartStats
+                };
+                
+                return chartGenerator.generateBarChart(
+                  chartData,
+                  actualOptions.title,
+                  outputPath,
+                  analyzeAspects // Show aspects if --a option was used
+                ).then(imagePath => {
+                  console.log(`✅ Chart image successfully saved to: ${imagePath}`);
+                  console.log(`📁 You can find it in your Downloads folder`);
+                });
+              } catch (error) {
+                console.error('❌ Error generating chart image:', error.message);
+              }
+            }
           }
         })
         .catch(error => {
@@ -1946,6 +2016,44 @@ program
           };
           await handleAIRequest(options, healthDataSummary);
         }
+      } else if (options.night) {
+        console.log(`Apple Health late night sleep analysis with ${pLabel} aspects`);
+        console.log('========================================================\n');
+        await analyzeLateNightAspects(planet, healthData);
+        
+        // Handle AI request for night analysis
+        if (options.p) {
+          const healthDataSummary = {
+            planet: planet,
+            sign: 'Multiple',
+            degreeInSign: 'Multiple',
+            dignity: `Apple Health late night sleep analysis with ${planet} aspects`,
+            element: 'Multiple',
+            decan: 'Multiple',
+            healthAnalysisType: 'night',
+            planetName: planet
+          };
+          await handleAIRequest(options, healthDataSummary);
+        }
+      } else if (options.nightAll) {
+        console.log(`Apple Health all-nighter sleep analysis with ${pLabel} aspects`);
+        console.log('============================================================\n');
+        await analyzeAllNighterAspects(planet, healthData);
+        
+        // Handle AI request for all-nighter analysis
+        if (options.p) {
+          const healthDataSummary = {
+            planet: planet,
+            sign: 'Multiple',
+            degreeInSign: 'Multiple',
+            dignity: `Apple Health all-nighter sleep analysis with ${planet} aspects`,
+            element: 'Multiple',
+            decan: 'Multiple',
+            healthAnalysisType: 'night-all',
+            planetName: planet
+          };
+          await handleAIRequest(options, healthDataSummary);
+        }
       } else if (hypothesis === 'stress-moon') {
         console.log(`Apple Health stress analysis with ${pLabel} aspects`);
         console.log('==========================================\n');
@@ -2394,13 +2502,83 @@ program
       return;
     }
 
+    // Show transit frequency if --o option is specified
+    if (options.o) {
+      // We expect a specific format: planet1 aspectType planet2 --o
+      // Example: "saturn k neptun --o" for Saturn conjunction Neptune
+
+      // Parse planet and aspect information from positional arguments
+      // For the format: planet1 aspectType planet2 --o
+      // planetArg = planet1, planet2Arg = aspectType, and we need to get planet2 from excess arguments
+      const planet1 = planetArg ? planetArg.toLowerCase() : null;
+      const aspectType = planet2Arg ? planet2Arg.toLowerCase() : null;
+      
+      // Get the third argument (planet2) from excess arguments
+      const excessArgs = program.args;
+      const planet2 = excessArgs.length >= 3 ? excessArgs[2].toLowerCase() : null;
+
+      // Check if we have all required arguments
+      if (!planet1 || !aspectType || !planet2) {
+        console.error('Error: Transit frequency requires two planets and an aspect type.');
+        console.error('Format: planet1 aspectType planet2 --o');
+        console.error('Example: saturn c neptune --o');
+        console.error('Aspect types: c=conjunction, o=opposition, s=square, t=trine, se=sextile, q=quincunx');
+        process.exit(1);
+      }
+
+      // Check if planets are valid
+      if (!planets[planet1] || !planets[planet2]) {
+        console.error('Error: Invalid planets.');
+        console.error('Available planets:', Object.keys(planets).join(', '));
+        process.exit(1);
+      }
+
+      // Check if aspect type is valid
+      const targetAngle = getAspectAngle(aspectType);
+      if (targetAngle === null) {
+        console.error('Error: Invalid aspect type.');
+        console.error('Available aspect types: c, o, s, t, se (conjunction, opposition, square, trine, sextile)');
+        process.exit(1);
+      }
+
+      // Calculate transit frequency
+      const frequencyData = calculateTransitFrequency(planet1, planet2, aspectType);
+
+      // Show results
+      const aspectTypeFull = getAspectTypeFullName(aspectType);
+      console.log(`Frequency: ${frequencyData.frequency}`);
+      console.log(`(Average interval: ${frequencyData.averageInterval.toFixed(1)} days / ${frequencyData.averageIntervalYears.toFixed(1)} years)`);
+      
+      // Show note if available
+      if (frequencyData.note) {
+        console.log(`${frequencyData.note}`);
+      }
+
+      // Handle AI request for transit frequency
+      if (options.p) {
+        const frequencyDataForAI = {
+          planet: `${planet1}-${planet2}`,
+          sign: 'Multiple',
+          degreeInSign: 'Multiple',
+          dignity: `Transit frequency: ${frequencyData.frequency} for ${aspectTypeFull} between ${planet1} and ${planet2}`,
+          element: 'Multiple',
+          decan: 'Multiple',
+          frequencyData: frequencyData
+        };
+        await handleAIRequest(options, frequencyDataForAI);
+      }
+
+      return;
+    }
+
     // Analyze CSV file if --csv option is provided
     if (actualOptions.csv) {
       const planet = planetArg ? planetArg.toLowerCase() : 'moon';
       const houseSystem = actualOptions.hs ? actualOptions.hs.toLowerCase() : 'koch';
       const analyzeAspects = actualOptions.a || false;
+      const filterCriteria = actualOptions.filter;
       
-      analyzeCSVWithDatetime(actualOptions.csv, planet, houseSystem, analyzeAspects, planet2)
+      analyzeCSVWithDatetime(actualOptions.csv, planet, houseSystem, analyzeAspects, planet2, filterCriteria)
         .then(({ results, houseDistribution, signDistribution, aspectStatistics }) => {
           if (results.length === 0) {
             console.log('No valid ISO-Datetime values found in the CSV file.');

package/src/health/healthAnalysis.js

@@ -1,6 +1,219 @@
 const { getAstrologicalData, calculatePlanetAspects } = require('../astrology/astrologyService');
 const { extractStepData, extractHRVData, extractSleepData, extractSleepGoal } = require('./healthService');
 
+// Function to analyze all-nighter sleep patterns (04:00 and 06:00 starts)
+async function analyzeAllNighterAspects(planetName, healthData) {
+  const sleepRecords = extractSleepData(healthData);
+  
+  if (sleepRecords.length === 0) {
+    console.log('No sleep data found to analyze.');
+    return;
+  }
+
+  // Filter sleep periods that start at typical all-nighter hours (04:00 and 06:00)
+  const allNighterHours = [4, 6];
+  const allNighterSleepRecords = sleepRecords.filter(record => {
+    const startHour = record.startDate.getHours();
+    return allNighterHours.includes(startHour);
+  });
+
+  console.log(`All-nighter sleep periods (starting at 04:00 or 06:00): ${allNighterSleepRecords.length} of ${sleepRecords.length} total sleep periods`);
+  
+  if (allNighterSleepRecords.length === 0) {
+    console.log('No all-nighter sleep periods found (starting at 04:00 or 06:00).');
+    return;
+  }
+
+  // Analyze planet aspects for each all-nighter sleep period
+  const aspectStats = {};
+  
+  for (const night of allNighterSleepRecords) {
+    const midSleepTime = new Date(night.startDate.getTime() + 
+                                  (night.endDate.getTime() - night.startDate.getTime()) / 2);
+    const dateComponents = {
+      year: midSleepTime.getFullYear(),
+      month: midSleepTime.getMonth() + 1,
+      day: midSleepTime.getDate(),
+      hour: midSleepTime.getHours(),
+      minute: midSleepTime.getMinutes()
+    };
+    const planetAspects = calculatePlanetAspects(planetName, dateComponents);
+
+    // Count aspects
+    for (const aspect of planetAspects) {
+      const aspectKey = `${aspect.type} with ${aspect.planet}`;
+      aspectStats[aspectKey] = (aspectStats[aspectKey] || 0) + 1;
+    }
+  }
+
+  // Show statistics (Top 10 planet aspects)
+  console.log(`\nMost frequent ${planetName.charAt(0).toUpperCase() + planetName.slice(1)} aspects during all-nighters (Top 10):`);
+  console.log('Aspect | Frequency | Percent | Active today');
+  console.log('-------|-----------|--------|------------');
+
+  const totalAllNighters = allNighterSleepRecords.length;
+  const sortedAspects = Object.entries(aspectStats)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10); // Limit to Top 10
+
+  // Calculate current planet aspects for comparison
+  const currentDate = new Date();
+  const currentDateComponents = {
+    year: currentDate.getFullYear(),
+    month: currentDate.getMonth() + 1,
+    day: currentDate.getDate(),
+    hour: currentDate.getHours(),
+    minute: currentDate.getMinutes()
+  };
+  const currentPlanetAspects = calculatePlanetAspects(planetName, currentDateComponents);
+  const currentAspectSet = new Set(currentPlanetAspects.map(a => `${a.type} with ${a.planet}`));
+
+  for (const [aspect, count] of sortedAspects) {
+    const percentage = totalAllNighters > 0 ? ((count / totalAllNighters) * 100).toFixed(1) : 0;
+    const isActiveToday = currentAspectSet.has(aspect) ? '✓' : '✗';
+    console.log(`${aspect.padEnd(25)} |    ${count.toString().padStart(2)}     |  ${percentage}%    |    ${isActiveToday}`);
+  }
+
+  if (sortedAspects.length === 0) {
+    console.log(`No ${planetName.charAt(0).toUpperCase() + planetName.slice(1)} aspects found in all-nighter sleep periods.`);
+  }
+
+  // Show all-nighter statistics
+  console.log(`\nAll-nighter sleep statistics:`);
+  const totalAllNighterDuration = allNighterSleepRecords.reduce((sum, record) => sum + record.duration, 0);
+  const avgAllNighterDuration = totalAllNighterDuration / allNighterSleepRecords.length;
+  
+  console.log(`Average all-nighter sleep duration: ${avgAllNighterDuration.toFixed(2)} hours`);
+  console.log(`Total all-nighter sleep periods: ${allNighterSleepRecords.length}`);
+  
+  // Show breakdown by all-nighter start hours
+  const hourCounts = {};
+  allNighterSleepRecords.forEach(record => {
+    const hour = record.startDate.getHours();
+    hourCounts[hour] = (hourCounts[hour] || 0) + 1;
+  });
+  
+  console.log(`All-nighter start hour breakdown:`);
+  allNighterHours.forEach(hour => {
+    if (hourCounts[hour]) {
+      console.log(`  ${hour}:00 - ${hourCounts[hour]} times`);
+    }
+  });
+}
+
+// Function to analyze late night sleep patterns (after 2am) and common aspects
+async function analyzeLateNightAspects(planetName, healthData) {
+  const sleepRecords = extractSleepData(healthData);
+  
+  if (sleepRecords.length === 0) {
+    console.log('No sleep data found to analyze.');
+    return;
+  }
+
+  // Filter sleep periods that start after 2am (went to bed later than 2am)
+  const lateNightSleepRecords = sleepRecords.filter(record => {
+    const startHour = record.startDate.getHours();
+    return startHour >= 2; // Started after 2am
+  });
+
+  console.log(`Late night sleep periods (starting after 2am): ${lateNightSleepRecords.length} of ${sleepRecords.length} total sleep periods`);
+  
+  if (lateNightSleepRecords.length === 0) {
+    console.log('No late night sleep periods found (starting after 2am).');
+    return;
+  }
+
+  // Analyze planet aspects for each late night sleep period
+  const aspectStats = {};
+  
+  for (const night of lateNightSleepRecords) {
+    const midSleepTime = new Date(night.startDate.getTime() + 
+                                  (night.endDate.getTime() - night.startDate.getTime()) / 2);
+    const dateComponents = {
+      year: midSleepTime.getFullYear(),
+      month: midSleepTime.getMonth() + 1,
+      day: midSleepTime.getDate(),
+      hour: midSleepTime.getHours(),
+      minute: midSleepTime.getMinutes()
+    };
+    const planetAspects = calculatePlanetAspects(planetName, dateComponents);
+
+    // Count aspects
+    for (const aspect of planetAspects) {
+      const aspectKey = `${aspect.type} with ${aspect.planet}`;
+      aspectStats[aspectKey] = (aspectStats[aspectKey] || 0) + 1;
+    }
+  }
+
+  // Show statistics (Top 10 planet aspects)
+  console.log(`\nMost frequent ${planetName.charAt(0).toUpperCase() + planetName.slice(1)} aspects during late night sleep (Top 10):`);
+  console.log('Aspect | Frequency | Percent | Active today');
+  console.log('-------|-----------|--------|------------');
+
+  const totalLateNights = lateNightSleepRecords.length;
+  const sortedAspects = Object.entries(aspectStats)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10); // Limit to Top 10
+
+  // Calculate current planet aspects for comparison
+  const currentDate = new Date();
+  const currentDateComponents = {
+    year: currentDate.getFullYear(),
+    month: currentDate.getMonth() + 1,
+    day: currentDate.getDate(),
+    hour: currentDate.getHours(),
+    minute: currentDate.getMinutes()
+  };
+  const currentPlanetAspects = calculatePlanetAspects(planetName, currentDateComponents);
+  const currentAspectSet = new Set(currentPlanetAspects.map(a => `${a.type} with ${a.planet}`));
+
+  for (const [aspect, count] of sortedAspects) {
+    const percentage = totalLateNights > 0 ? ((count / totalLateNights) * 100).toFixed(1) : 0;
+    const isActiveToday = currentAspectSet.has(aspect) ? '✓' : '✗';
+    console.log(`${aspect.padEnd(25)} |    ${count.toString().padStart(2)}     |  ${percentage}%    |    ${isActiveToday}`);
+  }
+
+  if (sortedAspects.length === 0) {
+    console.log(`No ${planetName.charAt(0).toUpperCase() + planetName.slice(1)} aspects found in late night sleep periods.`);
+  }
+
+  // Show some statistics about the late night sleep patterns
+  console.log(`\nLate night sleep statistics:`);
+  const totalLateNightDuration = lateNightSleepRecords.reduce((sum, record) => sum + record.duration, 0);
+  const avgLateNightDuration = totalLateNightDuration / lateNightSleepRecords.length;
+  
+  console.log(`Average late night sleep duration: ${avgLateNightDuration.toFixed(2)} hours`);
+  console.log(`Total late night sleep periods: ${lateNightSleepRecords.length}`);
+  
+  // Show the most common late night sleep start times
+  const startHours = lateNightSleepRecords.map(record => record.startDate.getHours());
+  const hourCounts = {};
+  startHours.forEach(hour => {
+    hourCounts[hour] = (hourCounts[hour] || 0) + 1;
+  });
+  
+  const sortedHours = Object.entries(hourCounts).sort((a, b) => b[1] - a[1]);
+  console.log(`Most common late night sleep start hours:`);
+  
+  // Show top 3 most common hours
+  sortedHours.slice(0, 3).forEach(([hour, count]) => {
+    console.log(`  ${hour}:00 - ${count} times`);
+  });
+  
+  // Check for all-nighter patterns (04:00 and 06:00)
+  const allNighterHours = [4, 6];
+  const allNighterFound = allNighterHours.some(hour => hourCounts[hour] && hourCounts[hour] > 0);
+  
+  if (allNighterFound) {
+    console.log(`\nAll-nighter patterns detected:`);
+    allNighterHours.forEach(hour => {
+      if (hourCounts[hour] && hourCounts[hour] > 0) {
+        console.log(`  ${hour}:00 - ${hourCounts[hour]} times (potential all-nighter)`);
+      }
+    });
+  }
+}
+
 // Function to analyze steps by planet sign
 async function analyzeStepsByPlanetSign(planetName, healthData, timeLimitDays = null) {
   let stepRecords = extractStepData(healthData);
@@ -421,5 +634,7 @@ async function analyzePlanetAspectsForSleep(planetName, healthData, sleepGoal =
 module.exports = {
   analyzeStepsByPlanetSign,
   analyzeStressByPlanetAspects,
-  analyzePlanetAspectsForSleep
+  analyzePlanetAspectsForSleep,
+  analyzeLateNightAspects,
+  analyzeAllNighterAspects
 };

package/src/utils/chartGenerator.js

@@ -0,0 +1,129 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Generate a bar chart SVG from CSV analysis data
+ * @param {Object} data - CSV analysis data
+ * @param {string} title - Chart title
+ * @param {string} outputPath - Output file path
+ * @param {boolean} showAspects - Whether to show aspects or house distribution
+ * @returns {Promise<string>} Path to the generated image
+ */
+async function generateBarChart(data, title, outputPath, showAspects = false) {
+  // SVG dimensions
+  const width = 1200;
+  const height = 800;
+  const padding = 60;
+  const chartWidth = width - 2 * padding;
+  const chartHeight = height - 2 * padding;
+  const titleHeight = 80;
+  const legendHeight = 100;
+
+  // Colors
+  const barColors = ['#4e79a7', '#f28e2b', '#e15759', '#76b7b2', '#59a14f', '#edc948', '#b07aa1', '#ff9da7', '#9c755f', '#bab0ac'];
+
+  // Prepare data for charting
+  let chartData, labels, maxValue, dataType;
+
+  if (showAspects && data.aspectStatistics) {
+    // Aspect statistics chart
+    dataType = 'Aspects';
+    chartData = data.aspectStatistics.types.map((type, index) => ({
+      label: type,
+      value: data.aspectStatistics.counts[type] || 0,
+      color: barColors[index % barColors.length]
+    }));
+    maxValue = Math.max(...chartData.map(d => d.value), 10);
+  } else {
+    // House distribution chart (default)
+    dataType = 'House Distribution';
+    chartData = [];
+    
+    // Ensure houseDistribution exists and has counts
+    const houseDist = data.houseDistribution || { counts: {} };
+    
+    for (let i = 1; i <= 12; i++) {
+      chartData.push({
+        label: `House ${i}`,
+        value: houseDist.counts[i] || 0,
+        color: barColors[(i-1) % barColors.length]
+      });
+    }
+    
+    maxValue = Math.max(...chartData.map(d => d.value), 10);
+  }
+
+  // Calculate bar dimensions
+  const barCount = chartData.length;
+  const barWidth = chartWidth / barCount / 1.5;
+  const maxBarHeight = chartHeight - titleHeight - legendHeight;
+  const yScale = maxBarHeight / maxValue;
+
+  // Generate SVG
+  const svgContent = `<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">
+  <!-- Background -->
+  <rect width="100%" height="100%" fill="#f8f9fa"/>
+
+  <!-- Title -->
+  <text x="${width/2}" y="${padding + titleHeight/2 + 10}" font-family="Arial" font-size="24" font-weight="bold" text-anchor="middle" fill="#333333">${title}</text>
+  
+  <!-- Statistical Subtitle -->
+  ${data.statistics ? `
+  <text x="${width/2}" y="${padding + titleHeight/2 + 40}" font-family="Arial" font-size="16" font-weight="bold" text-anchor="middle" fill="#666666">
+    χ²(${data.statistics.degreesOfFreedom}) = ${data.statistics.chiSquare}, p ${data.statistics.isSignificant ? '&lt; 0.05' : '≥ 0.05'}, Cramer's V = ${data.statistics.effectSize}
+  </text>
+  ` : ''}
+
+  <!-- Y-axis grid lines -->
+  ${Array.from({length: 6}).map((_, i) => {
+    const y = height - padding - (i * maxBarHeight / 5);
+    return `<line x1="${padding}" y1="${y}" x2="${width - padding}" y2="${y}" stroke="#e0e0e0" stroke-width="1"/>`;
+  }).join('')}
+
+  <!-- Y-axis labels -->
+  ${Array.from({length: 6}).map((_, i) => {
+    const y = height - padding - (i * maxBarHeight / 5);
+    const value = Math.round(maxValue * (i / 5));
+    return `<text x="${padding - 10}" y="${y + 4}" font-family="Arial" font-size="14" text-anchor="end" fill="#666666">${value}</text>`;
+  }).join('')}
+
+  <!-- X-axis -->
+  <line x1="${padding}" y1="${height - padding}" x2="${width - padding}" y2="${height - padding}" stroke="#666666" stroke-width="2"/>
+
+  <!-- Bars -->
+  ${chartData.map((d, index) => {
+    const barHeight = d.value * yScale;
+    const x = padding + (index * (barWidth * 1.5)) + barWidth / 2;
+    const y = height - padding - barHeight;
+    
+    return `
+    <rect x="${x - barWidth / 2}" y="${y}" width="${barWidth}" height="${barHeight}" fill="${d.color}"/>
+    ${barHeight > 20 ? `<text x="${x}" y="${y + 20}" font-family="Arial" font-size="14" font-weight="bold" text-anchor="middle" fill="white">${d.value}</text>` : ''}
+    `;
+  }).join('')}
+
+  <!-- X-axis labels -->
+  ${chartData.map((d, index) => {
+    const x = padding + (index * (barWidth * 1.5)) + barWidth / 2;
+    const y = height - padding + 25;
+    return `<text x="${x}" y="${y}" font-family="Arial" font-size="14" text-anchor="middle" fill="#666666">${d.label}</text>`;
+  }).join('')}
+</svg>`;
+
+  // Save the SVG file
+  return new Promise((resolve, reject) => {
+    fs.writeFile(outputPath, svgContent, 'utf8', (error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(outputPath);
+      }
+    });
+  });
+}
+
+module.exports = {
+  generateBarChart
+};

package/src/utils/downloadsFolder.js

@@ -0,0 +1,70 @@
+const path = require('path');
+const os = require('os');
+
+/**
+ * Gets the default downloads folder path for the current operating system
+ * @returns {string} Path to the downloads folder
+ */
+function getDownloadsFolder() {
+  const homeDir = os.homedir();
+  
+  switch (process.platform) {
+    case 'win32':
+      // Windows: %USERPROFILE%\Downloads
+      return path.join(homeDir, 'Downloads');
+    
+    case 'darwin':
+      // macOS: ~/Downloads
+      return path.join(homeDir, 'Downloads');
+    
+    case 'linux':
+      // Linux: Check common locations
+      const xdgDownload = process.env.XDG_DOWNLOAD_DIR;
+      if (xdgDownload) {
+        return xdgDownload;
+      }
+      // Fallback to ~/Downloads
+      return path.join(homeDir, 'Downloads');
+    
+    default:
+      // Fallback for other platforms
+      return path.join(homeDir, 'Downloads');
+  }
+}
+
+/**
+ * Ensures the downloads folder exists and is writable
+ * @returns {string} Valid downloads folder path
+ */
+function getValidDownloadsFolder() {
+  const fs = require('fs');
+  const downloadsFolder = getDownloadsFolder();
+  
+  try {
+    // Check if folder exists
+    if (!fs.existsSync(downloadsFolder)) {
+      // Try to create it
+      fs.mkdirSync(downloadsFolder, { recursive: true });
+    }
+    
+    // Check if folder is writable
+    const testFile = path.join(downloadsFolder, '.write_test_' + Date.now());
+    try {
+      fs.writeFileSync(testFile, 'test');
+      fs.unlinkSync(testFile);
+      return downloadsFolder;
+    } catch (error) {
+      // Fallback to current directory if downloads folder is not writable
+      console.warn(`⚠️  Downloads folder not writable: ${downloadsFolder}, using current directory`);
+      return process.cwd();
+    }
+  } catch (error) {
+    console.warn(`⚠️  Could not access downloads folder: ${error.message}, using current directory`);
+    return process.cwd();
+  }
+}
+
+module.exports = {
+  getDownloadsFolder,
+  getValidDownloadsFolder
+};