Analysis API

The Analysis API allows you to query the almanac for data products, events, and contact windows.

Reporting Scalars

Use report_scalars to generate time-series data for analysis or plotting.

almanac.report_scalars(report, time_series)

Expects a ReportScalars object containing a list of expressions and a StateSpec.

Parameters:

• report: A ReportScalars instance defined with:
  • state_spec: The context (Target, Observer, Frame) to evaluate against.
  • scalars: A list of ScalarExpr items.
• time_series: A hifitime::TimeSeries defining the start, end, and step.

Returns:

A dictionary (or map) where keys are Epochs and values are maps of { "Alias": Value }.

    target_frame = analysis.FrameSpec.Loaded(Frames.EME2000)
    observer_frame = analysis.FrameSpec.Loaded(Frames.MOON_J2000)

    state = analysis.StateSpec(
        target_frame=target_frame,
        observer_frame=observer_frame,
        ab_corr=None,
    )

    # Define all scalars to be calculated
    scalars = [
        analysis.ScalarExpr.Element(analysis.OrbitalElement.SemiMajorAxis),
        analysis.ScalarExpr.Element(analysis.OrbitalElement.Eccentricity),
        analysis.ScalarExpr.Element(analysis.OrbitalElement.Rmag),
        analysis.ScalarExpr.BetaAngle(),
        analysis.ScalarExpr.SolarEclipsePercentage(eclipsing_frame=Frames.VENUS_J2000),
    ]

    # Add optional aliases (Tuple of (Scalar, Alias))
    scalars_with_aliases = [(s, None) for s in scalars]

    # Build the final report object
    report = analysis.ReportScalars(scalars_with_aliases, state)

    # Generate the report data
    series = TimeSeries(
        Epoch("2025-01-01 00:00:00 UTC"),
        Epoch("2025-01-02 12:00:00 UTC"),
        Unit.Day * 0.5,
        inclusive=True,
    )
    data = almanac.report_scalars(report, series)

Finding Events

Use report_events to find specific instants (points in time).

almanac.report_events(state, event, start, end)

Finds discrete events such as:

• Orbital Events: Apoapsis, Periapsis.
• Min/Max: Time of maximum elevation, minimum range.
• Crossings: Time when altitude crosses 100km.

Returns:

A list of EventDetails objects, each containing:

• epoch: The precise time of the event.
• value: The value of the scalar at that time.
• orbit: The full spacecraft state at that time.

    # Define an event: Sun Angle < 90.0 degrees (Sunset)
    sun_has_set = analysis.Event(
        analysis.ScalarExpr.SunAngle(observer_id=-85), # LRO ID
        Condition.LessThan(90.0),
        Unit.Second * 0.5,
        ab_corr=None,
    )

    # Predefined events are also available
    apolune = Event.apoapsis()
    perilune = Event.periapsis()

    # Find distinct events (points in time)
    apo_events = almanac.report_events(lro_state_spec, apolune, start_epoch, end_epoch)

Finding Intervals (Arcs)

Use report_event_arcs to find durations.

almanac.report_event_arcs(state, event, start, end)

Finds time intervals where a condition is continuously true.

• Visibility: "When can I see the station?"
• Battery: "When am I in sunlight?"
• Geometry: "When is the Earth-Sun-Probe angle < 90?"

Returns:

A list of EventArc objects, each containing:

• start: The EventDetails of the start (Rising edge).
• end: The EventDetails of the end (Falling edge).

    eclipse = Event.total_eclipse(Frames.MOON_J2000)

    # Find durations (arcs)
    sunset_arcs = almanac.report_event_arcs(
        lro_state_spec, sun_has_set, start_epoch, end_epoch
    )

    eclipse_arcs = almanac.report_event_arcs(
        lro_state_spec, eclipse, start_epoch, start_epoch + period * 3
    )

Returns:

A list of EventArc objects, each containing:

• start: The EventDetails of the start (Rising edge).
• end: The EventDetails of the end (Falling edge).

The EventArc provides the following helpers:

• duration: the duration of the event, as a hifitime Duration
• start_epoch, end_epoch: the epochs of the start and end of the event
• midpoint_epoch: the half-way point in the event, useful if you need to check for some calculation that happens undoubtedly during the event itself.