Chart Data Factory #

The ChartDataFactory extracts and structures all astronomical calculations into machine-readable Pydantic models. It separates the computational layer from the visualization layer (ChartDrawer).

Key Features #

• Structured Output: Returns Pydantic models (SingleChartDataModel or DualChartDataModel) perfect for APIs.
• Automatic Analysis: Calculates element/quality distributions and relationship scores automatically.
• Optimized: Only calculates what is necessary for the requested chart type.

Factory Methods #

1. create_natal_chart_data #

Calculates all standard chart data (planets, houses, aspects, elements) for a single subject.

from kerykeion import AstrologicalSubjectFactory, ChartDataFactory

subject = AstrologicalSubjectFactory.from_birth_data(
    "Alice", 1990, 6, 15, 12, 0,
    lng=-0.1276, lat=51.5074, tz_str="Europe/London",
    online=False
)
natal_data = ChartDataFactory.create_natal_chart_data(subject)

print(f"Elements: {natal_data.element_distribution.fire_percentage}% Fire")
print(f"Qualities: {natal_data.quality_distribution.cardinal_percentage}% Cardinal")

Parameters #

See Element & Quality Distribution for details on distribution methods and custom weights.

2. create_synastry_chart_data #

Used for comparing two subjects. Includes relationship scoring and house comparison.

subject_b = AstrologicalSubjectFactory.from_birth_data(
    "Bob", 1992, 8, 20, 14, 30,
    lng=-74.006, lat=40.7128, tz_str="America/New_York",
    online=False
)

synastry_data = ChartDataFactory.create_synastry_chart_data(
    subject,
    subject_b,
    include_relationship_score=True,
    include_house_comparison=True
)

if synastry_data.relationship_score:
    print(f"Compatibility Score: {synastry_data.relationship_score.score_value}")

Parameters #

3. create_transit_chart_data #

Compares a natal chart against a current/event time subject.

now = AstrologicalSubjectFactory.from_current_time("Now", "London", "GB")
transit_data = ChartDataFactory.create_transit_chart_data(subject, now)

Parameters #

4. create_composite_chart_data #

Creates data for a composite (midpoint) chart from a CompositeSubjectModel.

from kerykeion import CompositeSubjectFactory

composite_subject = CompositeSubjectFactory(subject, subject_b).get_midpoint_composite_subject_model()
composite_data = ChartDataFactory.create_composite_chart_data(composite_subject)

Parameters #

5. create_return_chart_data #

Creates a dual-wheel planetary return chart (natal + return overlay).

from kerykeion import PlanetaryReturnFactory

return_factory = PlanetaryReturnFactory(subject, city="New York", nation="US")
solar_return = return_factory.next_return_from_date(2024, 1, 1, return_type="Solar")

return_data = ChartDataFactory.create_return_chart_data(subject, solar_return)

Parameters #

6. create_single_wheel_return_chart_data #

Creates a single-wheel view of a planetary return (return only, no natal overlay).

single_return_data = ChartDataFactory.create_single_wheel_return_chart_data(solar_return)

Parameters #

7. create_progression_chart_data #

Creates a dual-wheel secondary progression chart (natal inner ring + progressed outer ring).

from kerykeion import SecondaryProgressionFactory

progressed = SecondaryProgressionFactory.compute(subject, target_year=2026)
progression_data = ChartDataFactory.create_progression_chart_data(subject, progressed)

Parameters #

8. create_chart_data (Generic) #

The underlying generic method that all convenience methods delegate to. Use this when you need full control over the chart type.

chart_data = ChartDataFactory.create_chart_data(
    chart_type="Natal",
    first_subject=subject,
    distribution_method="pure_count"
)

An unknown chart_type, or a missing second_subject for a dual chart type, raises KerykeionException; so does a first_subject/second_subject whose model class does not match the requested chart type (for example a Composite chart whose first subject is not a CompositeSubjectModel).

Data Models #

SingleChartDataModel #

Used for Natal, Composite, and Single Return charts.

• chart_type: "Natal", "Composite" or "SingleReturnChart".
• subject: The subject — an AstrologicalSubjectModel, CompositeSubjectModel or PlanetReturnModel.
• aspects: List of internal aspects.
• element_distribution: Fire/Earth/Air/Water breakdown.
• quality_distribution: Cardinal/Fixed/Mutable breakdown.
• angularities: List of AngularityModel — classical planets conjunct the four angles (Ascendant, Medium Coeli, Descendant, Imum Coeli) within the orb (default 8°). Each entry carries point, angle, and distance.
• stelliums: List of StelliumModel — houses with three or more classical planets. Each entry carries house (1-12) and points (list of planet names).
• active_points: The points actually used, after the intersection described above.
• active_aspects: The aspects and orbs actually used.

DualChartDataModel #

Used for Synastry, Transit, Progression, and Dual Return charts.

• chart_type: "Transit", "Synastry", "DualReturnChart" or "Progression".
• first_subject, second_subject: The two subjects.
• aspects: Inter-chart aspects.
• relationship_score: Compatibility score (if requested).
• house_comparison: Planet overlays in houses (if requested).
• element_distribution, quality_distribution: Combined over both subjects for Synastry; over the first subject alone for Transit, Progression and Dual Return charts.
• first_subject_angularities, first_subject_stelliums: Angularities and stelliums for the first (natal) subject.
• second_subject_angularities, second_subject_stelliums: Angularities and stelliums for the second (transit/partner/progressed/return) subject.
• active_points: The points actually used, after the intersection described above.
• active_aspects: The aspects and orbs actually used.

Analysis Example #

Get a full JSON dump of a chart’s data.

import json
natal_data = ChartDataFactory.create_natal_chart_data(subject)

# Dump to JSON
json_output = natal_data.model_dump_json(indent=2)
print(json_output)

---