pybiorythm

JSON Schema Reference

This document describes the JSON output format for biorhythm data generated by the generate_timeseries_json() method.

Overview

The JSON output provides structured biorhythm data suitable for:

API responses
Data analysis and visualization
Integration with other systems
Long-term data storage

Schema Structure

Root Object

{
  "meta": { ... },
  "cycle_repeats": { ... },
  "critical_days": [ ... ],
  "data": [ ... ]
}

Detailed Schema

meta (Object)

Metadata about the biorhythm calculation and generation.

{
  "meta": {
    "generator": "biorhythm_enhanced.py",
    "version": "2025-08-07",
    "birthdate": "1990-05-15",
    "plot_date": "2025-08-07",
    "days_alive": 12869,
    "cycle_lengths_days": {
      "physical": 23,
      "emotional": 28,
      "intellectual": 33
    },
    "chart_orientation": "vertical",
    "days": 29,
    "width": 55,
    "scientific_warning": "⚠️  SCIENTIFIC WARNING ⚠️\nBiorhythm theory is PSEUDOSCIENCE..."
  }
}

Fields:

generator (string): Software that generated the data
version (string): Version of the generator
birthdate (string): Birth date in ISO format (YYYY-MM-DD)
plot_date (string): Center date for the data in ISO format
days_alive (integer): Number of days between birth and plot date
cycle_lengths_days (object): Cycle lengths for each biorhythm
- physical (integer): Physical cycle length (23 days)
- emotional (integer): Emotional cycle length (28 days)
- intellectual (integer): Intellectual cycle length (33 days)
chart_orientation (string): Chart orientation (“vertical” or “horizontal”)
days (integer): Number of days in the dataset
width (integer): Chart width used for generation
scientific_warning (string): Scientific disclaimer text

cycle_repeats (Object)

Information about when biorhythm cycles repeat.

{
  "cycle_repeats": {
    "physical_emotional_repeat_in_days": 234,
    "all_cycles_repeat_in_days": 8383
  }
}

Fields:

physical_emotional_repeat_in_days (integer): Days until physical and emotional cycles align again
all_cycles_repeat_in_days (integer): Days until all three cycles return to the same state

critical_days (Array)

List of dates where one or more cycles are near zero (considered “critical”).

{
  "critical_days": [
    {
      "date": "2025-08-15",
      "cycles": "Physical, Emotional cycle(s) near zero"
    }
  ]
}

Array Elements:

date (string): Date in ISO format (YYYY-MM-DD)
cycles (string): Human-readable description of which cycles are critical

data (Array)

Daily biorhythm values for the requested time period.

{
  "data": [
    {
      "date": "2025-07-24",
      "days_alive": 12855,
      "physical": -0.8387,
      "emotional": 0.2817,
      "intellectual": 0.7431,
      "critical_cycles": []
    },
    {
      "date": "2025-08-15",
      "days_alive": 12877,
      "physical": -0.0435,
      "emotional": 0.0348,
      "intellectual": 0.9397,
      "critical_cycles": ["Physical", "Emotional"]
    }
  ]
}

Array Elements:

date (string): Date in ISO format (YYYY-MM-DD)
days_alive (integer): Number of days since birth for this date
physical (number): Physical cycle value (-1.0 to 1.0)
emotional (number): Emotional cycle value (-1.0 to 1.0)
intellectual (number): Intellectual cycle value (-1.0 to 1.0)
critical_cycles (array): List of cycle names that are critical on this date

Value Ranges

Cycle Values

Range: -1.0 to +1.0
-1.0: Cycle at minimum (lowest point)
0.0: Cycle at neutral/critical point
+1.0: Cycle at maximum (highest point)

Critical Threshold

Values between -0.05 and +0.05 are considered “critical”
Critical days are when cycles transition between positive and negative

Usage Examples

Python Usage

import json
from biorythm.core import BiorhythmCalculator
from datetime import datetime

# Generate JSON data
calc = BiorhythmCalculator(days=14)
birthdate = datetime(1990, 5, 15)
data = calc.generate_timeseries_json(birthdate)

# Access metadata
print(f"Total days alive: {data['meta']['days_alive']}")
print(f"Physical cycle length: {data['meta']['cycle_lengths_days']['physical']} days")

# Find critical days
critical_count = len(data['critical_days'])
print(f"Critical days in period: {critical_count}")

# Process daily data
for entry in data['data']:
    date = entry['date']
    physical = entry['physical']
    
    if abs(physical) > 0.8:  # High or low physical
        state = "HIGH" if physical > 0 else "LOW" 
        print(f"{date}: Physical {state} ({physical:.2f})")

JavaScript Usage

// Parse JSON response
const biorhythmData = JSON.parse(jsonResponse);

// Access cycle information
const cycleInfo = biorhythmData.meta.cycle_lengths_days;
console.log(`Cycles: ${cycleInfo.physical}, ${cycleInfo.emotional}, ${cycleInfo.intellectual} days`);

// Find peak performance days
const peakDays = biorhythmData.data.filter(day => 
  day.physical > 0.7 && day.emotional > 0.7 && day.intellectual > 0.7
);

console.log(`${peakDays.length} peak performance days found`);

// Alert for critical days
biorhythmData.critical_days.forEach(critical => {
  console.warn(`Critical day ${critical.date}: ${critical.cycles}`);
});

API Integration

# Example API endpoint returning biorhythm JSON
curl -X POST https://api.example.com/biorhythm \
  -H "Content-Type: application/json" \
  -d '{
    "birthdate": "1990-05-15",
    "plot_date": "2025-08-07",
    "days": 30,
    "orientation": "vertical"
  }'

Data Analysis Examples

Finding Cycle Patterns

import pandas as pd

# Convert to DataFrame for analysis
df = pd.DataFrame(data['data'])
df['date'] = pd.to_datetime(df['date'])

# Find correlation between cycles
correlation = df[['physical', 'emotional', 'intellectual']].corr()
print(correlation)

# Identify optimal periods (all cycles positive)
optimal_days = df[
    (df['physical'] > 0) & 
    (df['emotional'] > 0) & 
    (df['intellectual'] > 0)
]
print(f"Optimal days: {len(optimal_days)}")

Visualization

import matplotlib.pyplot as plt

# Plot all cycles
plt.figure(figsize=(12, 6))
plt.plot(df['date'], df['physical'], label='Physical (23d)', color='red')
plt.plot(df['date'], df['emotional'], label='Emotional (28d)', color='blue')  
plt.plot(df['date'], df['intellectual'], label='Intellectual (33d)', color='green')

# Mark critical days
critical_dates = [datetime.fromisoformat(cd['date']) for cd in data['critical_days']]
plt.scatter(critical_dates, [0] * len(critical_dates), 
           color='orange', marker='x', s=100, label='Critical Days')

plt.legend()
plt.title('Biorhythm Cycles')
plt.ylabel('Cycle Value')
plt.grid(True)
plt.show()

Validation

JSON Schema Validation

import jsonschema

# Basic validation schema
schema = {
    "type": "object",
    "required": ["meta", "cycle_repeats", "critical_days", "data"],
    "properties": {
        "meta": {
            "type": "object",
            "required": ["birthdate", "plot_date", "days_alive"]
        },
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "required": ["date", "physical", "emotional", "intellectual"],
                "properties": {
                    "physical": {"type": "number", "minimum": -1, "maximum": 1},
                    "emotional": {"type": "number", "minimum": -1, "maximum": 1},
                    "intellectual": {"type": "number", "minimum": -1, "maximum": 1}
                }
            }
        }
    }
}

# Validate data
jsonschema.validate(data, schema)

File Format Recommendations

Storage

Format: JSON (.json)
Encoding: UTF-8
Compression: gzip for large datasets
Naming: biorhythm_YYYY-MM-DD_to_YYYY-MM-DD.json

API Transport

Content-Type: application/json
Compression: gzip encoding accepted
Size limits: Consider pagination for large date ranges

Scientific Disclaimer

⚠️ Important: The JSON data represents biorhythm calculations based on pseudoscientific theory. This data format is provided for educational, entertainment, and software development purposes only. The underlying biorhythm theory has no scientific validity.