Components, Analysis, IO & Caching¶

🤖 Primarily for coding agents. Hello, Claude! Read this before re-deriving the API from source. If it disagrees with the code, the code wins — please update the doc.

Part of the developer docs. See also CHART_BUILDING, ENGINES.

Covers optional chart components, the analysis toolkit (DataFrames, stats, queries, vectors), file IO (import natives), and the caching system + utils.

1. Components (`components/`)¶

Components implement the ChartComponent protocol (component_name + calculate(...)). Add with ChartBuilder.add_component(...). Results are either appended CelestialPositions (read via chart.get_component_result(name)) or written to chart.metadata.

Component	`component_name`	Returns / where to read	Notable args
`ArabicPartsCalculator`	`"Arabic Parts"`	`CelestialPosition` (type `ARABIC_PART`)	`parts_to_calculate=[...]`; sect-aware formula
`MidpointCalculator`	`"Midpoints"`	`MidpointPosition` list (`object1`, `object2`, `is_indirect`)	`pairs=[...]`, `calculate_all=True`, `indirect=True`
`DignityComponent`	`"Essential Dignities"`	`metadata["dignities"]` (`planet_dignities`, `mutual_receptions`, `sect`)	`traditional`, `modern`, `receptions`, `decans`
`AccidentalDignityComponent`	`"Accidental Dignities"`	metadata (angular/joy/retro/cazimi scoring)	—
`FixedStarsComponent`	`"Fixed Stars"`	`FixedStarPosition` list	`stars=[...]`, `tier=1
`AntisciaCalculator`	`"Antiscia"`	positions (`ANTISCION`/`CONTRA_ANTISCION`) + `metadata["antiscia"]`	`orb=1.5`, `include_contra=True`

components/dignity.py::determine_sect(positions) -> "day"|"night" is the sect helper (Sun above/below horizon). Arabic Parts use day: ASC + P2 − P1, night: ASC + P1 − P2.

from stellium.components import ArabicPartsCalculator, MidpointCalculator
chart = (ChartBuilder.from_native(native)
    .add_component(ArabicPartsCalculator(parts_to_calculate=["Part of Fortune"]))
    .add_component(MidpointCalculator(calculate_all=True))
    .calculate())
fortune = chart.get_component_result("Arabic Parts")

2. Analysis (`analysis/`) — requires `pandas` (`pip install -e ".[analysis]"`)¶

Bulk/statistical work over many charts.

BatchCalculator (batch.py) — calculate many charts efficiently. Factories: from_registry(category=..., verified=..., data_quality=...), from_natives(list), from_iterable(stream). Fluent .with_house_systems(...), .with_aspects(), .add_analyzer(...), .with_progress(cb). Run .calculate() (generator) or .calculate_all().
frames.py — charts_to_dataframe(charts), positions_to_dataframe(charts), aspects_to_dataframe(charts, include_declination=False).
stats.py — ChartStats(charts): .element_distribution(), .sign_distribution("Sun"), .aspect_frequency(), .retrograde_frequency(), .pattern_frequency(), .cross_tab(a, b), .summary().
queries.py — ChartQuery(charts): chainable .where_sun(sign=...), .where_moon(phase=...), .where_planet(name, retrograde=...), .where_aspect(a, b, kind, orb_max=...), .where_pattern(...), .where_element_dominant(...), .where_sect(...) → .results()/.count()/ .first()/.to_dataframe().
vector.py — ChartVectorizer().encode(chart) -> np.ndarray, similarity(a, b) (cosine).
export.py — export_csv/json/parquet(charts, path, schema="charts"|"positions"|"aspects").

3. File IO (`io/`)¶

Parse external sources into list[Native] (re-exported from stellium):

CSV — parse_csv(path, mapping=None, delimiter=","), read_csv(path, name=..., date=..., location=...), CSVColumnMapping for explicit column mapping. Auto-detects common headers if no mapping.
AAF — parse_aaf(path) (Astrodienst Astrological Format).
DataFrame — parse_dataframe(df), read_dataframe(df, ...), dataframe_from_natives(natives).

4. Caching (`utils/cache.py`, `utils/cache_utils.py`)¶

File-based pickle cache with subdirs ephemeris, geocoding, general.

from stellium.utils.cache import cached

@cached(cache_type="ephemeris")          # cache_type ∈ {"ephemeris","geocoding","general"}
def expensive(...): ...

Cache: .get/.set/.clear(cache_type), .size(), .get_stats(); default expiry 24h.
Management helpers (cache_utils.py): print_cache_info(), clear_ephemeris_cache(), clear_geocoding_cache(), clear_all_cache(), get_cache_stats(). Also exposed via stellium cache CLI.

5. Other utils (`utils/`)¶

time.py — datetime_to_julian_day, julian_day_to_datetime, offset_julian_day.
houses.py — find_house_for_longitude(longitude, cusps) (handles 0/360 wrap).
chart_ruler.py — get_sign_ruler, get_chart_ruler, get_chart_ruler_from_chart.
chart_shape.py — detect_chart_shape(chart) → (Bundle/Bowl/Bucket/ Locomotive/Seesaw/Splay/Splash, metadata).
progressions.py — calculate_progressed_datetime(natal, target, type=...) (secondary/tertiary/minor), solar arc / Naibod helpers.
planetary_crossing.py — find_planetary_crossing, find_return_near_date, find_nth_return (used by returns).

Gotchas¶

Components that store data in metadata return an empty list from get_component_result — read chart.metadata[...] (or the dedicated getter like chart.get_dignities()).
Analysis/IO need optional deps (pandas, and scipy for some stats).
Cache keys are derived from args; changing a function’s signature can invalidate cached values — clear with clear_all_cache() when in doubt.

Components, Analysis, IO & Caching¶

1. Components (components/)¶

2. Analysis (analysis/) — requires pandas (pip install -e ".[analysis]")¶

3. File IO (io/)¶