Source code for orbitalpv.data

"""Data-loading, connector, and deterministic demonstration helpers."""

from collections.abc import Sequence
from pathlib import Path

import pandas as pd

from space_pv_connectors import (
    ArxivConnector,
    BirdsEPSConnector,
    CelesTrakConnector,
    DataverseConnector,
    DiscosConnector,
    DonkiConnector,
    FlyingLaptopConnector,
    GHSLSettlementConnector,
    GroundImage,
    HorizonsConnector,
    LisirdConnector,
    N2YOConnector,
    NoaaSwpcConnector,
    NtrsConnector,
    OpenStreetMapEnergyConnector,
    OpsSatADConnector,
    PdsConnector,
    PsaConnector,
    PVSite,
    ResearchResponse,
    Sentinel2GroundConnector,
    SettlementRaster,
    ZenodoConnector,
    load_birds_eps_workbook,
    load_flying_laptop_power,
    load_goes_integral_particle_flux,
    load_ground_image,
    load_opssat_segments,
    load_pv_site,
    load_settlement_raster,
    load_table,
    make_demo_telemetry,
    normalize_birds_like,
    read_ground_image,
)
from space_pv_connectors.gp_cache import GPCache, GPSnapshot, GPUnavailableError
from space_pv_connectors.swpc import normalize_solar_activity


[docs] def fetch_celestrak_omm( catnr: int, *, cache_path: str | Path = "data/cache/gp.sqlite3" ) -> dict[str, object]: """Fetch a CelesTrak OMM record, reusing a persistent two-hour cache. Use ``CelesTrakConnector.fetch_gp_cached`` when source timestamps, stale warnings and checksums are needed alongside the orbital elements. """ with CelesTrakConnector() as connector: snapshot = connector.fetch_gp_cached(cache_path, catnr=catnr) if snapshot.cache_stale or snapshot.warning: raise GPUnavailableError(snapshot.warning or "GP snapshot refresh is overdue") records = snapshot.records if not records: raise LookupError(f"No CelesTrak OMM record found for NORAD {catnr}") return records[0]
[docs] def fetch_birds_eps( satellite: str, destination: str | Path, *, campaign_year: int | None = None, ) -> pd.DataFrame: """Download and normalize real on-orbit BIRDS EPS telemetry. ``campaign_year`` explicitly dates sheet names that omit a year, without overriding fully dated sheets. Numeric clocks retain their elapsed seconds; calendar-anchored timestamps do not establish the true acquisition time. See :func:`load_birds_eps_workbook` for metadata and excluded test sheets. """ with BirdsEPSConnector() as connector: return connector.download_frame( satellite, destination, normalized=True, campaign_year=campaign_year )
[docs] def fetch_flying_laptop_power( month: str, destination: str | Path, *, time_min: str | pd.Timestamp | None = None, time_max: str | pd.Timestamp | None = None, ) -> pd.DataFrame: """Download a Flying Laptop month and normalize its measured array V/I. Power is computed from each documented voltage/current pair. UTC packet timestamps and four array identities are preserved. Bounds are inclusive at ``time_min`` and exclusive at ``time_max``. For offline reuse, call :func:`load_flying_laptop_power` on the downloaded archive. """ with FlyingLaptopConnector(timeout_s=120.0) as connector: return connector.download_frame(month, destination, time_min=time_min, time_max=time_max)
[docs] def fetch_opssat_segments( destination: str | Path, *, channels: Sequence[str] | None = None, split: str | None = None, refresh: bool = False, ) -> pd.DataFrame: """Fetch checksum-verified original OPS-SAT telemetry and expert labels. Values retain their published scale; the source supplies no engineering unit declaration. Segment IDs and the provider's train/test split remain intact. Photodiode measurements are not panel electrical power. """ with OpsSatADConnector() as connector: return connector.download_frame( destination, channels=channels, split=split, refresh=refresh )
__all__ = [ "ArxivConnector", "BirdsEPSConnector", "CelesTrakConnector", "DataverseConnector", "DiscosConnector", "DonkiConnector", "FlyingLaptopConnector", "GHSLSettlementConnector", "GPCache", "GPSnapshot", "GroundImage", "HorizonsConnector", "LisirdConnector", "N2YOConnector", "NoaaSwpcConnector", "NtrsConnector", "OpenStreetMapEnergyConnector", "OpsSatADConnector", "PVSite", "PdsConnector", "PsaConnector", "ResearchResponse", "Sentinel2GroundConnector", "SettlementRaster", "ZenodoConnector", "fetch_birds_eps", "fetch_celestrak_omm", "fetch_flying_laptop_power", "fetch_opssat_segments", "load_birds_eps_workbook", "load_flying_laptop_power", "load_goes_integral_particle_flux", "load_ground_image", "load_opssat_segments", "load_pv_site", "load_settlement_raster", "load_table", "make_demo_telemetry", "normalize_birds_like", "normalize_solar_activity", "read_ground_image", ]