Uncertain times
A chart is calculated for a single timestamp, yet birth records and historical
sources rarely pin down the exact minute. Birth certificates often round to
the quarter hour, biographies may record a date with no time, and ancient
observations carry clock errors of several minutes. The chartStability
function scans a time window around your target timestamp and reports which
chart facts hold across the entire window and when any changing facts shift.
The Uncertain Time instrument runs the same scan interactively in your browser, plotting a timeline track for every fact that changes.
import { Engine, chartStability, julianDay } from "caelus";
import { embeddedData } from "caelus/data-embedded";
const engine = new Engine(embeddedData);
// Born 10 June 1990 in Tampa, "about 2:30 in the afternoon" (18:30 UT).
const jd = julianDay(1990, 6, 10, 18, 30);
const { facts, summary } = chartStability(engine, jd, {
lat: 27.95, lonEast: -82.46,
halfWidthSeconds: 900,
});
summary; // { facts: 61, stable: 60 }
facts.filter((f) => !f.stable); // the true node's house, and nothing elseWith a 15-minute window on either side of the nominal time, 60 of the chart's 61 facts stay fixed. Only the house placement of the true lunar node changes, shifting from the fifth house to the fourth at 18:43 UT.
Supported chart facts
In chartStability, a fact is a single discrete statement derived from a chart.
The function tracks six kinds:
| Kind | Subject | Value |
|---|---|---|
angle_sign | asc or mc | The angle's zodiac sign |
sect | chart | "day" or "night" |
sign | A planet or point | The body's zodiac sign |
house | A planet or point | The body's house number, 1 to 12 |
retrograde | A planet | true or false |
aspect | A pair, "sun-moon" | The active aspect name, or null |
Each returned fact includes its value at the nominal timestamp, a stable
flag, the share of the window during which that value holds, and segments,
which splits the window into contiguous intervals of each value. Every boundary
between segments marks a transition timestamp resolved to roughly one-second
precision.
Scanning an entire day without a birth time
Pass a half-width of twelve hours (43200 seconds) to test the full calendar
day when only a date is known:
const day = chartStability(engine, jd, {
lat: 27.95, lonEast: -82.46, halfWidthSeconds: 43200,
});
day.summary; // { facts: 64, stable: 42 }Across the full 24-hour span for this same chart, 42 of 64 facts remain constant: every body stays in the same sign, every planet keeps the same motion direction, and 20 of the 26 active aspects remain within orb. Both angles, the chart sect, and all thirteen house placements change over the day, which is why charts without a birth time are typically read without house cusps. This full-day scan takes roughly 1.6 seconds in Node.js.
If you omit lat and lonEast, chartStability skips location-dependent
calculations (angles, houses, and sect) and evaluates only signs, retrograde
states, and aspects.
Visualizing uncertainty on the chart wheel
ChartWheel in caelus-wheel can display the uncertainty range directly on
a chart diagram. Its uncertainty prop accepts an array of charts sampled
across the time window in chronological order and draws an arc showing how far
each body and angle travels.
import { Engine, julianDay } from "caelus";
import { embeddedData } from "caelus/data-embedded";
import { ChartWheel } from "caelus-wheel";
const engine = new Engine(embeddedData);
const jd = julianDay(1990, 6, 10, 18, 30);
const at = (minutes: number) =>
engine.chartAt(jd + minutes / 1440, 27.95, -82.46);
export default function Wheel() {
// an hour either way, sampled every half hour
const samples = [-60, -30, 0, 30, 60].map(at);
return <ChartWheel chart={at(0)} uncertainty={{ samples }} />;
}
Planetary range arcs appear just inside the zodiac ring, while Ascendant and Midheaven arcs sit near the outer rim (with the Ascendant outermost). Arcs that cross a sign boundary render thicker and display a square marker at the boundary. Two boundary samples are usually enough for planets, whereas the angles rotate roughly 15° per hour and require samples every 30 minutes across multi-hour windows (closing into complete circles over a 24-hour day). The Uncertain Time instrument draws these arcs for any window you configure.
Ancient dates and ΔT uncertainty
When you omit halfWidthSeconds, chartStability defaults to a window radius
equal to the one-sigma uncertainty of ΔT at the chart's epoch. For modern
dates, that uncertainty is under a second, so all facts stay stable by
default. For a chart in 100 CE, ΔT uncertainty reaches 155 seconds, enough to
shift the Ascendant by two-thirds of a degree, and chartStability reports
which facts that clock margin puts at risk. The same uncertainty triggers the
delta_t_uncertain warning on standard charts and appears in the epochSigma
block of canonical output.
Position uncertainty for a single body
To measure longitude uncertainty for an individual body rather than discrete
chart facts, call positionUncertainty. It returns ephemeris model error and
clock-induced error as separate numbers so they stay distinguishable:
import { positionUncertainty, julianDay } from "caelus";
positionUncertainty(engine, "moon", julianDay(1500, 6, 1, 12, 0, 0, "julian"));
// { modelBoundArcsec: 3, deltaTSigmaSeconds: 15.0, clockSigmaArcsec: 7.5, ... }
modelBoundArcsec is the body's worst-case error measured against JPL Horizons
across the validated date range, or null when the timestamp falls outside
that range (positions are still calculated outside the span, without a
published accuracy guarantee). clockSigmaArcsec measures the one-sigma spread
caused by ΔT uncertainty, equal to the body's angular speed multiplied by
deltaTSigmaSeconds.
| Timestamp | Body | Model bound | ΔT sigma | Clock uncertainty |
|---|---|---|---|---|
| 2000 | Moon | 3″ | 0.06 s | 0.03″ |
| 1500 | Moon | 3″ | 15 s | 7.5″ |
| 1500 | Saturn | 1″ | 15 s | 0.08″ |
| 100 | Moon | none published | 155 s | 76″ |
| 100 | Saturn | none published | 155 s | 0.19″ |
| 1000 BCE | Moon | none published | 1,440 s | 711″ |
| 1000 BCE | Saturn | none published | 1,440 s | 1.8″ |
In 1500 CE, the Moon's 3″ ephemeris model bound is already smaller than the 7.5″ spread caused by clock uncertainty. By 1000 BCE, the Moon's position varies by nearly twelve arcminutes while Saturn shifts by less than two arcseconds.
MCP integration
AI clients can run this same scan via the chart_stability tool. It accepts a
timestamp, uncertainty_minutes, and optional coordinates, returning the list
of stable facts alongside transition timestamps for any unstable ones. Setup
instructions are in the MCP guide.
Options
| Option | Default | Description |
|---|---|---|
lat, lonEast | none | Observer coordinates in degrees (supply both or omit both). |
halfWidthSeconds | ΔT one-sigma | Half-width of the time window in seconds. |
houseSystem | "placidus" | House system identifier, as in chartAt. |
zodiac | "tropical" | Zodiac reference frame, as in chartAt. |
orbs | default orbs | Optional per-aspect orb overrides. |
stepSeconds | 120 | Initial sampling step in seconds before boundary bisection. |
Limits
- Because the scan samples every two minutes by default, a fact that flips and reverts within a single step can be missed (most likely when a body sits right on a quadrant house cusp at high latitudes).
- Time windows do not account for uncertainty in geographic coordinates.
- Aspects are tracked as binary states (in orb or out of orb); an aspect whose exactness tightens or loosens while remaining within orb is reported as stable.