@nrweb/astro-calc/README.md

Comprehensive astrological calculations using Swiss Ephemeris and astronomy-engine for positions, aspects, houses, lots, and scoring metrics

# Astro Calculator

A comprehensive TypeScript library for astrological calculations using Swiss Ephemeris and astronomy-engine. Calculate planetary positions, aspects, houses, lots, and scoring metrics for celestial bodies with high precision.

## Features

- **Planetary Positions**: Calculate precise positions for all planets, Moon, and lunar nodes
- **Zodiac Signs & Dignities**: Determine zodiac signs, dignities, decans, and bounds
- **Houses**: Generate house systems with planet placements
- **Aspects**: Calculate major aspects between planets with orbs and grades
- **Lots**: Compute various Arabic parts and lots
- **Retrograde Tracking**: Track retrograde periods and planetary motion
- **Scoring Systems**: Romance, career, wealth, magic, friendship, and health scores
- **Planetary Hours**: Calculate planetary hour rulers
- **Moon Phases**: Determine lunar phases and illumination

## Installation

```bash
npm install astro-calculator
```

## Quick Start

```typescript
import { getAstrologicalPositions } from "astro-calculator";

// Get astrological data for current time and default location
const chart = getAstrologicalPositions();

// Get data for specific date and location
const specificChart = getAstrologicalPositions(
  new Date("2024-03-15"),
  40.7128, // latitude
  -74.006 // longitude
);

console.log(chart.positions); // Planetary positions
console.log(chart.houses); // House system
console.log(chart.romanceScore); // Romance compatibility score
```

## API Reference

### Main Functions

#### `getAstrologicalPositions(date?, latitude?, longitude?)`

Returns a complete astrological chart with positions, houses, aspects, and scores.

**Parameters:**

- `date` (Date, optional): Target date (defaults to current date)
- `latitude` (number, optional): Latitude in degrees (defaults to Belfast)
- `longitude` (number, optional): Longitude in degrees (defaults to Belfast)

**Returns:** `Chart` object containing:

- `positions`: Array of planetary positions
- `houses`: Array of house data
- `lots`: Array of calculated lots
- `aspects`: Array of planetary aspects
- `romanceScore`, `careerScore`, `wealthScore`, etc.: Scoring metrics
- `planetaryHours`: Planetary hour rulers
- `moonPhase`: Current lunar phase information

### Scoring Functions

```typescript
import {
  calculateRomanceScore,
  calculateCareerScore,
  calculateWealthScore,
  calculateMagicScore,
  calculateFriendshipScore,
  calculateHealthScore,
} from "astro-calculator";

const chart = getAstrologicalPositions();
const romanceScore = calculateRomanceScore(
  chart.positions,
  chart.houses,
  chart.isDayChart
);
```

## Usage Examples

### Basic Chart Calculation

```typescript
import { getAstrologicalPositions } from "astro-calculator";

const chart = getAstrologicalPositions();

// Access planetary positions
chart.positions.forEach((planet) => {
  console.log(`${planet.name}: ${planet.degrees}° ${planet.sign}`);
  console.log(`Dignity: ${planet.dignity}`);
  console.log(`Motion: ${planet.planetaryMotion}`);
});

// Access houses
chart.houses.forEach((house) => {
  console.log(
    `House ${house.number}: ${house.startDegrees}° ${house.startSign}`
  );
});
```

### Aspect Analysis

```typescript
const chart = getAstrologicalPositions();

// Find all aspects involving the Sun
const sunAspects = chart.positions.find((p) => p.name === "Sun")?.aspects || [];

sunAspects.forEach((aspect) => {
  console.log(`Sun ${aspect.type} ${aspect.planets.right}`);
  console.log(`Deviation: ${aspect.deviation}°`);
});
```

### Historical Chart

```typescript
// Calculate chart for a historical date
const historicalChart = getAstrologicalPositions(
  new Date("1969-07-20T20:17:00Z"), // Moon landing
  28.5383, // Kennedy Space Center latitude
  -80.6511 // Kennedy Space Center longitude
);

console.log("Moon landing chart:", historicalChart);
```

This will run the TypeScript code directly without building.

## Output

The script outputs a comprehensive JSON object containing:

- **Date and Location**: The date/time and coordinates used for calculations
- **Planets**: Positions, motion states, dignities, and aspects for all traditional planets
- **Houses**: 12 houses with planetary placements and aspects
- **Lots**: Traditional lots (Fortune, Spirit, Marriage, Children, Career, Health, Wealth, Love) with positions and aspects
- **Challenges**: Astrological challenges (Algol transit, aneretic degrees, Via Combusta, Void Course)
- **Moon Phase**: Current lunar phase and illumination
- **Scoring Metrics**: Five normalized scores (0-1) for different life areas

## Scoring Metrics

The application calculates five normalized scores (0-1) for different life areas. Each score starts at 0.5 and is adjusted based on positive and negative astrological factors.

### Romance Score

**Positive Factors (+0.1 to +0.3 each):**

- Venus in dignity (exaltation, rulership, triplicity, term, face)
- Venus in angular houses (1st, 4th, 7th, 10th)
- Jupiter in dignity or angular houses
- Moon in dignity or angular houses
- Venus-Jupiter aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Venus-Moon aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Venus in 5th or 7th house (+0.2 each)
- Jupiter in 5th or 7th house (+0.2 each)
- Moon in 5th or 7th house (+0.2 each)
- Venus not combust or retrograde (+0.1 each)
- Jupiter not combust or retrograde (+0.1 each)
- Moon not combust (+0.1)
- Waxing moon phase (+0.1)
- Lot of Love in dignity or angular houses (+0.2 each)

**Negative Factors (-0.1 to -0.3 each):**

- Venus in detriment or fall
- Venus in cadent houses (3rd, 6th, 9th, 12th)
- Saturn in 5th or 7th house
- Mars in 5th or 7th house
- Venus-Saturn aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Venus-Mars aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Venus combust or retrograde
- Waning moon phase
- Lot of Love in detriment or fall

### Career Score

**Positive Factors (+0.1 to +0.3 each):**

- Sun in dignity (exaltation, rulership, triplicity, term, face)
- Sun in angular houses (1st, 4th, 7th, 10th)
- Mercury in dignity or angular houses
- Jupiter in dignity or angular houses
- Sun-Jupiter aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Sun-Mercury aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Sun in 6th or 10th house (+0.2 each)
- Mercury in 6th or 10th house (+0.2 each)
- Jupiter in 6th or 10th house (+0.2 each)
- Sun not combust (+0.1)
- Mercury not combust or retrograde (+0.1 each)
- Jupiter not combust or retrograde (+0.1 each)
- Waxing moon phase (+0.1)
- Lot of Career in dignity or angular houses (+0.2 each)

**Negative Factors (-0.1 to -0.3 each):**

- Sun in detriment or fall
- Sun in cadent houses (3rd, 6th, 9th, 12th)
- Saturn in 6th or 10th house
- Mars in 6th or 10th house
- Sun-Saturn aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Sun-Mars aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Sun combust
- Mercury combust or retrograde
- Waning moon phase
- Lot of Career in detriment or fall

### Wealth Score

**Positive Factors (+0.1 to +0.3 each):**

- Jupiter in dignity (exaltation, rulership, triplicity, term, face)
- Jupiter in angular houses (1st, 4th, 7th, 10th)
- Venus in dignity or angular houses
- Moon in dignity or angular houses
- Jupiter-Venus aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Jupiter-Moon aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Jupiter in 2nd or 8th house (+0.2 each)
- Venus in 2nd or 8th house (+0.2 each)
- Moon in 2nd or 8th house (+0.2 each)
- Jupiter not combust or retrograde (+0.1 each)
- Venus not combust or retrograde (+0.1 each)
- Moon not combust (+0.1)
- Waxing moon phase (+0.1)
- Lot of Wealth in dignity or angular houses (+0.2 each)

**Negative Factors (-0.1 to -0.3 each):**

- Jupiter in detriment or fall
- Jupiter in cadent houses (3rd, 6th, 9th, 12th)
- Saturn in 2nd or 8th house
- Mars in 2nd or 8th house
- Jupiter-Saturn aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Jupiter-Mars aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Jupiter combust or retrograde
- Venus combust or retrograde
- Waning moon phase
- Lot of Wealth in detriment or fall

### Magic Score

**Positive Factors (+0.1 to +0.3 each):**

- Moon in dignity (exaltation, rulership, triplicity, term, face)
- Moon in angular houses (1st, 4th, 7th, 10th)
- Neptune in dignity or angular houses
- Pluto in dignity or angular houses
- Moon-Neptune aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Moon-Pluto aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Moon in 8th or 12th house (+0.2 each)
- Neptune in 8th or 12th house (+0.2 each)
- Pluto in 8th or 12th house (+0.2 each)
- Moon not combust (+0.1)
- Neptune not combust or retrograde (+0.1 each)
- Pluto not combust or retrograde (+0.1 each)
- New or full moon phase (+0.2)
- Lot of Spirit in dignity or angular houses (+0.2 each)

**Negative Factors (-0.1 to -0.3 each):**

- Moon in detriment or fall
- Moon in cadent houses (3rd, 6th, 9th, 12th)
- Saturn in 8th or 12th house
- Mars in 8th or 12th house
- Moon-Saturn aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Moon-Mars aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Moon combust
- Neptune combust or retrograde
- Pluto combust or retrograde
- Quarter moon phases
- Lot of Spirit in detriment or fall

### Friendship Score

**Positive Factors (+0.1 to +0.3 each):**

- Venus in dignity (exaltation, rulership, triplicity, term, face)
- Venus in angular houses (1st, 4th, 7th, 10th)
- Jupiter in dignity or angular houses
- Mercury in dignity or angular houses
- Venus-Jupiter aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Venus-Mercury aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Venus in 3rd or 11th house (+0.2 each)
- Jupiter in 3rd or 11th house (+0.2 each)
- Mercury in 3rd or 11th house (+0.2 each)
- Venus not combust or retrograde (+0.1 each)
- Jupiter not combust or retrograde (+0.1 each)
- Mercury not combust or retrograde (+0.1 each)
- Waxing moon phase (+0.1)
- Lot of Fortune in dignity or angular houses (+0.2 each)

**Negative Factors (-0.1 to -0.3 each):**

- Venus in detriment or fall
- Venus in cadent houses (3rd, 6th, 9th, 12th)
- Saturn in 3rd or 11th house
- Mars in 3rd or 11th house
- Venus-Saturn aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Venus-Mars aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Venus combust or retrograde
- Waning moon phase
- Lot of Fortune in detriment or fall

### Health Score

**Positive Factors (+0.1 to +0.3 each):**

- Sun in dignity (exaltation, rulership, triplicity, term, face)
- Sun in angular houses (1st, 4th, 7th, 10th)
- Moon in dignity or angular houses
- Jupiter in dignity or angular houses
- Sun-Moon aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Sun-Jupiter aspects (trine +0.3, sextile +0.2, conjunction +0.1)
- Sun in 1st or 6th house (+0.2 each)
- Moon in 1st or 6th house (+0.2 each)
- Jupiter in 1st or 6th house (+0.2 each)
- Sun not combust (+0.1)
- Moon not combust (+0.1)
- Jupiter not combust or retrograde (+0.1 each)
- Waxing moon phase (+0.1)
- Lot of Health in dignity or angular houses (+0.2 each)

**Negative Factors (-0.1 to -0.3 each):**

- Sun in detriment or fall
- Sun in cadent houses (3rd, 6th, 9th, 12th)
- Saturn in 1st or 6th house
- Mars in 1st or 6th house
- Sun-Saturn aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Sun-Mars aspects (square -0.3, opposition -0.2, conjunction -0.1)
- Sun combust
- Moon combust
- Waning moon phase
- Lot of Health in detriment or fall

## Score Calculation Details

- **Baseline**: All scores start at 0.5
- **Normalization**: Final scores are clamped between 0 and 1
- **Aspect Grading**: Aspects are graded as "perfect" (0° orb), "joining" (1-3° orb), or "assembly" (3-10° orb)
- **House Classification**: Angular (1st, 4th, 7th, 10th), Succedent (2nd, 5th, 8th, 11th), Cadent (3rd, 6th, 9th, 12th)
- **Dignities**: Exaltation, rulership, triplicity, term, face, detriment, fall
- **Combust**: Planets within 8° of the Sun (except traditional planets only)
- **Retrograde**: Planets appearing to move backward from Earth's perspective

## Development

### Building the Project

```bash
npm run build
```

### Publishing to npm

1. Make sure you're logged in to npm:

```bash
npm login
```

2. Update the version in package.json:

```bash
npm version patch  # for bug fixes
npm version minor  # for new features
npm version major  # for breaking changes
```

3. Build and publish:

```bash
npm publish
```

The `prepublishOnly` script will automatically run the build before publishing.

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run `npm run build` to ensure everything compiles
6. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Dependencies

- **astronomy-engine**: Core astronomical calculations
- **swiss-ephemeris**: High-precision planetary positions
- **suncalc**: Solar calculations for sunrise/sunset
- **lune**: Lunar phase calculations

## Requirements

- Node.js >= 14.0.0
- TypeScript (for development)