nataly 0.1.5

A comprehensive astrology library for natal chart calculations, analysis, geometric chart layout extraction, and accurate declination calculations.

Nataly

This library was developed to generate artistic natal posters with astronomical precision. For chart visuals and more details, visit: https://goker.art/natal

A comprehensive Python library for astrological chart calculations and analysis.

Features

• Natal Chart Calculations: Complete birth chart calculations with Swiss Ephemeris
• Transit Analysis: Transit chart calculations and aspect analysis
• Comprehensive Data: Planets, asteroids, lunar nodes, angles, and more
• Distribution Analysis: Elements, modalities, polarities, quadrants, hemispheres
• Aspect Calculations: Major and minor aspects with configurable orbs
• House Systems: Support for Placidus and other house systems
• Dignities: Planetary dignities (domicile, exaltation, detriment, fall)
• Filtering: Advanced filtering for celestial bodies by type, sign, house, etc.
• Declination Calculations: Accurate declination data for both bodies and house cusps
• Absolute Longitude: Full 360° longitude calculations for precise positioning
• Enhanced Reports: Comprehensive chart reports with all astrological data

Installation

You can install Nataly using pip:

pip install nataly

For development installation:

git clone https://github.com/gokerDEV/nataly.git
cd nataly
pip install -e .

Ephemeris Files (Required for Asteroids)

Important: For asteroid calculations (Ceres, Pallas, Juno, Vesta, Chiron), ephemeris files are required. The package automatically includes these files, but if you encounter issues:

Manual Download (if needed):

# Create ephemeris directory
mkdir -p ephe

# Download asteroid ephemeris files
curl -L -o ephe/seas_18.se1 https://www.astro.com/ftp/swisseph/ephe/seas_18.se1
curl -L -o ephe/semo_18.se1 https://www.astro.com/ftp/swisseph/ephe/semo_18.se1
curl -L -o ephe/semom18.se1 https://www.astro.com/ftp/swisseph/ephe/semom18.se1
curl -L -o ephe/sepl_18.se1 https://www.astro.com/ftp/swisseph/ephe/sepl_18.se1
curl -L -o ephe/seplm18.se1 https://www.astro.com/ftp/swisseph/ephe/seplm18.se1

Verify Installation:

from nataly import NatalChart
import datetime

# Test chart with asteroids
birth_dt = datetime.datetime(1990, 2, 27, 9, 15, tzinfo=datetime.timezone.utc)
chart = NatalChart(
    person_name="Test",
    dt_utc=birth_dt,
    lat=38.25,
    lon=27.09
)

# Check for asteroids
asteroids = [body for body in chart.bodies_dict.values() if body.body_type == "Asteroid"]
print(f"Found {len(asteroids)} asteroids: {[a.name for a in asteroids]}")

Quick Start

import datetime
from nataly import NatalChart, create_orb_config, to_utc

# Path to ephemeris directory (must be set by user)
ephe_path = "./ephe"  # <-- Set this to your .se1 files directory

# Create a natal chart
birth_dt = to_utc('1990-02-27 09:15', '+02:00')
chart = NatalChart(
    person_name="Joe Doe",
    dt_utc=birth_dt,
    lat=38.25,  # Izmir, Turkey
    lon=27.09,
    orb_config=create_orb_config('Placidus'),  # 'Placidus' is an alias for 'Default'
    ephe_path=ephe_path
)

# Get planetary positions with declination
sun = chart.get_body_by_name("Sun")
print(f"Sun: {sun.signed_dms} in House {sun.house}")
print(f"Sun declination: {sun.declination_dms}")

# Get aspects
for aspect in chart.aspects:
    print(f"{aspect.body1.name} {aspect.symbol} {aspect.body2.name} (orb: {aspect.orb_str})")

# Get distributions
print("Element distribution:", chart.element_distribution)
print("Modality distribution:", chart.modality_distribution)

# Get house cusps with declination
for house in chart.houses:
    print(f"House {house.id}: {house.dms} {house.sign.name} (declination: {house.declination_dms})")

Advanced Usage

Enhanced Chart Reports

# Generate comprehensive natal chart report
from nataly import NatalChart, to_utc

birth_dt = to_utc('1997-03-28 18:00', '+02:00')
chart = NatalChart(
    person_name="Joe Doe",
    dt_utc=birth_dt,
    lat=41.0529,  # Istanbul, Turkey
    lon=29.0661,
    ephe_path="./ephe"
)

# Get all bodies with absolute longitude and declination
for body in chart.get_bodies():
    print(f"{body.name}: {body.absolute_dms} (declination: {body.declination_dms})")

# Get house cusps with declination
for house in chart.houses:
    print(f"House {house.id}: {house.absolute_dms} {house.sign.name} (declination: {house.declination_dms})")

Filtering Celestial Bodies

from nataly import BodyFilter

# Get only planets (excluding luminaries)
planets_filter = BodyFilter(
    include_planets=True,
    include_luminaries=False,
    include_asteroids=False
)
planets = chart.get_bodies(planets_filter)

# Get bodies in specific signs
fire_signs = chart.get_bodies_by_signs(["Aries", "Leo", "Sagittarius"])

# Get retrograde bodies
retrograde = chart.get_retrograde_bodies()

Transit Analysis

from nataly import AstroEngine

# Create transit chart
transit_dt = datetime.datetime.now(datetime.timezone.utc)
transit_chart = NatalChart(
    person_name="Current Transit",
    dt_utc=transit_dt,
    lat=38.25,
    lon=27.09
)

# Calculate aspects between transit and natal
engine = AstroEngine()
transit_aspects = engine.get_aspects(
    transit_chart.bodies_dict, 
    chart.bodies_dict
)

Custom Orb Configuration

from nataly import OrbConfig

# Create custom orb configuration
custom_orbs = {
    'luminaries': {
        'Conjunction': 10.0,
        'Opposition': 10.0,
        'Trine': 8.0,
        'Square': 8.0
    },
    'planets': {
        'Conjunction': 8.0,
        'Opposition': 8.0,
        'Trine': 6.0,
        'Square': 6.0
    },
    'angles': {
        'Conjunction': 1.0,
        'Opposition': 1.0,
        'Trine': 1.0,
        'Square': 1.0
    }
}

orb_config = OrbConfig.from_dict(custom_orbs)
chart = NatalChart(
    person_name="Custom Orbs",
    dt_utc=birth_dt,
    lat=38.25,
    lon=27.09,
    orb_config=orb_config
)

Examples

Check the examples/ directory for complete examples:

• astrological_analysis.py: Comprehensive chart analysis with report generation
• basic_usage.py: Basic library usage examples
• reference_2_enhanced_report.py: Complete natal chart report with all bodies, aspects, and declinations
• reference_1_test.py: Test script for reference data validation

Development

To set up the development environment:

pip install -e ".[dev]"

Run tests:

pytest

Format code:

black nataly/

Lint code:

flake8 nataly/

Dependencies

Required

• swisseph>=2.10.0: Swiss Ephemeris for planetary calculations
• pytz>=2021.1: Timezone handling

Optional

• numpy>=1.20.0: Advanced calculations
• pandas>=1.3.0: Data analysis
• matplotlib>=3.3.0: Chart visualization
• seaborn>=0.11.0: Enhanced plotting

Ephemeris Files (REQUIRED)

You MUST provide the path to your ephemeris directory via ephe_path=... in all code.

Required files:

• seas_18.se1 (asteroids)
• sepl_18.se1 (planets)
• semo_18.se1 (asteroids)
• seplm18.se1 (planets)
• semom18.se1 (asteroids)

Example check:

import os
required_files = ["seas_18.se1", "sepl_18.se1", "semo_18.se1", "seplm18.se1", "semom18.se1"]
ephe_path = "./ephe"
if not os.path.isdir(ephe_path):
    raise RuntimeError(f"Ephemeris directory not found: {ephe_path}")
missing = [f for f in required_files if not os.path.isfile(os.path.join(ephe_path, f))]
if missing:
    raise RuntimeError(f"Missing ephemeris files in {ephe_path}: {missing}")

1. Go to https://www.astro.com/swisseph/swedownload_j.htm
2. Download ephemeris files (e.g., seas_18.se1)
3. Place files in ephe/ directory

Note: These files are required for accurate declination calculations and asteroid positions.

Orb Config

• 'Placidus' is an alias for 'Default' in orb_config (for compatibility)

Declination Calculations

Nataly provides accurate declination calculations for both celestial bodies and house cusps:

Body Declinations

• Uses Swiss Ephemeris equatorial coordinates for precise declination values
• Compatible with astro.com and other professional astrological software
• Available for all planets, asteroids, and lunar nodes

House Cusp Declinations

• Calculated using proper astrological formulas with dynamic obliquity
• Uses IAU 2006 formula for mean obliquity based on Julian centuries since J2000
• Accurate for all historical and future dates

Usage Example

# Get body declination
sun = chart.get_body_by_name("Sun")
print(f"Sun declination: {sun.declination_dms}")

# Get house cusp declination
first_house = chart.houses[0]
print(f"1st House declination: {first_house.declination_dms}")

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request

Geometric Chart Layout (NEW in 0.1.3)

Nataly now provides geometric layout data for visualizing natal charts via the ChartLayout class:

from nataly import NatalChart, ChartLayout
import datetime

# Create a natal chart
birth_dt = datetime.datetime(1990, 2, 27, 9, 15, tzinfo=datetime.timezone.utc)
chart = NatalChart(
    person_name="Joe Doe",
    dt_utc=birth_dt,
    lat=38.4192,  # Izmir, Turkey
    lon=27.1287
)

# Get geometric layout data for visualization
layout = ChartLayout(chart)
layout_data = layout.get_data()
print("Chart center:", layout_data["center"])
print("First house line:", layout_data["natal"]["houses"][0])
print("First planet position:", layout_data["natal"]["bodies"][0])

See examples/basic_usage.py for a runnable sample.

---

Version History

See CHANGELOG.md for detailed version history.

• 0.1.5: Enhanced declination calculations for bodies and house cusps, improved Swiss Ephemeris integration, added comprehensive chart reports
• 0.1.3: Added ChartLayout for geometric chart layout extraction and public API, new example in basic_usage.py
• 0.1.0: Initial release with complete astrological functionality