Data connectors#

class space_pv_connectors.ArxivConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

One explicit paper per request; reuse cache and observe arXiv rate limits.

The original Atom bytes are cached with SHA-256, URL and retrieval time. This connector does not extract or promote scientific claims from PDFs. Downloading an accessible paper does not grant redistribution rights.

Parameters:
paper(paper_id, *, cache_path=None, refresh=False)[source]#

Fetch pinned metadata, or validate and read its existing local cache.

Parameters:
Return type:

ResearchResponse

download_paper(paper_id, destination, *, max_bytes=20000000)[source]#

Download a selected version with a checksum receipt; no bulk crawl.

Parameters:
Return type:

DownloadReceipt

class space_pv_connectors.BirdsEPSConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Connector for the public BIRDS on-orbit EPS dataset.

Parameters:
download(satellite, destination)[source]#

Download one satellite workbook from the upstream BIRDS repository.

Parameters:
Return type:

DownloadReceipt

download_frame(satellite, destination, *, normalized=True, campaign_year=None)[source]#

Download and load a BIRDS EPS workbook.

campaign_year supplies the year only for campaign sheet names that omit it; see load_birds_eps_workbook() for the time convention.

Parameters:
  • satellite (str)

  • destination (str | Path)

  • normalized (bool)

  • campaign_year (int | None)

Return type:

DataFrame

class space_pv_connectors.DataverseConnector(*, base_url='https://darus.uni-stuttgart.de', timeout_s=30.0)[source]#

Public Dataverse search and versioned dataset access; defaults to DaRUS.

Another public installation can be selected with base_url. Dataset and file licenses are provider-specific. Private/restricted data are not fetched.

Parameters:
search(query, *, start=0, page_size=25, cache_path=None, refresh=False)[source]#

Search public datasets; start is a zero-based record offset.

Parameters:
Return type:

ResearchResponse

dataset(persistent_id, *, version=':latest-published', cache_path=None, refresh=False)[source]#

Fetch published dataset metadata; pin version='1.0' for reproducibility.

Parameters:
Return type:

ResearchResponse

download_file(persistent_id, filename, destination, *, version=':latest-published', max_bytes=100000000)[source]#

Download the original public file and verify its dataset checksum.

Parameters:
Return type:

DownloadReceipt

class space_pv_connectors.DiscosConnector(*, token, timeout_s=30.0)[source]#

ESA DISCOS v2 metadata; free registration and an explicit token required.

DISCOS IDs and NORAD catalog numbers are different identifiers. This API supplies object/launch metadata, not ephemerides or universal PV ratings.

Parameters:
objects(*, filter_expression=None, page=1, page_size=100, cache_path=None, refresh=False)[source]#

Get one page of objects using the provider’s filter syntax.

Parameters:
  • filter_expression (str | None)

  • page (int)

  • page_size (int)

  • cache_path (str | Path | None)

  • refresh (bool)

Return type:

ResearchResponse

object(discos_id, *, cache_path=None, refresh=False)[source]#

Retrieve one object by its DISCOS internal ID.

Parameters:
Return type:

ResearchResponse

by_norad(norad_id, *, cache_path=None, refresh=False)[source]#

Search the NORAD satno field; preserve an empty or ambiguous result.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.DonkiConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA CCMC DONKI event catalog, accessed directly without a NASA API key.

Uses the September 2026 CCMC endpoint, not the retired kauai host. Events are research context, not spacecraft-specific dose or causation evidence. Follow CCMC’s attribution and publication rules for event studies.

Parameters:
events(event_type, *, start, stop, cache_path=None, refresh=False)[source]#

Get an explicit UTC date window (provider endDate is inclusive).

The raw empty response may be null or an empty list. Event links and associated instruments/spacecraft are kept, without assigning them to other missions.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.DownloadReceipt(source: 'str', url: 'str', retrieved_at: 'str', sha256: 'str', bytes: 'int', path: 'str | None' = None)[source]#
Parameters:
class space_pv_connectors.FlyingLaptopConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Retrieve CC BY 4.0 Flying Laptop monthly archives from DaRUS.

The archive contains many housekeeping packets. The normalizer reads only packet 4900, whose calibrated array currents and voltages have documented units of A and V. Downloads retain a checksum-bearing provenance sidecar.

Parameters:
download_month(month, destination)[source]#

Download one YYYY-MM archive after checking its catalog checksum.

Parameters:
Return type:

DownloadReceipt

download_frame(month, destination, *, time_min=None, time_max=None)[source]#

Download a month and normalize the requested UTC time interval.

Parameters:
Return type:

DataFrame

class space_pv_connectors.GHSLSettlementConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Retrieve JRC GHS-SMOD context while preserving its edition and epoch.

The official R2023A V2.0 global ZIP is downloaded once and reused; the 2015 archive is about 29 MB. Only a bounded native-resolution window is read into memory. The ZIP size is capped before and during downloading, and its member is validated before Rasterio opens it.

Original R2019A downloads are no longer served at the official URL as of October 2026. Use edition='R2019A', source_path=... with a retained native historical GeoTIFF. No fallback to a different edition occurs.

Parameters:
fetch_settlement(*, bbox, cache_path, source_cache_dir=None, source_path=None, edition='R2023A', epoch=2015, refresh=False, offline=False, max_download_bytes=67108864, max_pixels=1000000)[source]#

Return a native crop for WGS84 (west, south, east, north).

offline permits an existing validated crop or local source, and prevents HTTP calls. refresh replaces a crop from the same source; archived versioned source files remain cached. A local source_path is hashed and its edition/epoch are caller declarations recorded in provenance; filenames alone cannot verify those declarations.

Parameters:
Return type:

SettlementRaster

class space_pv_connectors.GroundImage(data, crs, transform, bounds, scene_id, asset_key, source_url, asset_metadata, bbox_wgs84, item_metadata, nodata_values, retrieved_at)[source]#

A native-resolution rectangular crop, retaining raw pixel semantics.

data has shape (bands, rows, columns); True mask entries mean missing data. transform holds affine (a, b, c, d, e, f) coefficients and bounds is (left, bottom, right, top) in crs. Pixel-aligned bounds can extend slightly beyond the requested bbox_wgs84.

visual is a rendered RGB product, not calibrated reflectance. scl is a categorical scene-classification product, not a power or irradiance measurement. No cloud masking is applied implicitly.

Parameters:
reflectance()[source]#

Return raw * scale + offset using explicit STAC band metadata.

Only assets declaring the reflectance role are accepted. Missing data remain masked before calibration; negative reflectance values are retained. The raw data is never modified. For example, Collection 1 commonly declares scale 0.0001 and offset -0.1, so dividing every product by 10000 without its offset would be wrong.

Return type:

MaskedArray

save_geotiff(destination, *, overwrite=False)[source]#

Save raw pixels, georeferencing, calibration and provenance.

The .meta.json sidecar includes the complete source STAC item, asset metadata, requested/actual bounds and the output SHA-256. The checksum identifies this derived crop, not the original full tile. A GeoTIFF internal mask is used when all band masks agree. Distinct band masks are retained through a shared nodata value when possible; unsupported mask combinations raise rather than discard information.

Parameters:
Return type:

DownloadReceipt

class space_pv_connectors.HorizonsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Public NASA/JPL ephemerides for supported targets, including spacecraft.

Returns the original JSON envelope containing the ephemeris text, headers, units and API signature. Vectors use ICRF axes, TDB time, geometric (no light-time) corrections and AU/day units. No spacecraft attitude or PV output is implied. Target coverage is determined by JPL.

Parameters:
vectors(target, *, start, stop, step='1 d', center='500@10', cache_path=None, refresh=False)[source]#

Retrieve geometric vectors; default center is the Sun’s center.

Dates are YYYY-MM-DD in TDB, with both endpoints requested. The provider may omit the final instant if the step does not land on it. Negative spacecraft IDs (e.g. '-61' for Juno) avoid ambiguous name matches.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.LisirdConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Retrieve bounded, measured TSIS-1/SORCE irradiance datasets.

The LaTiS jsond response carries parameter order and units. Cache files contain the original JSON bytes plus a .meta.json sidecar binding the response to its dataset, time range and SHA-256. Reusing a different query with the same cache path raises an error instead of returning stale data. Data access is public; retain LASP/instrument-team attribution and consult the product release notes for the version used.

Parameters:
total_solar_irradiance(dataset_id='tsis_tsi_24hr', *, time_min, time_max, cache_path=None)[source]#

Return measured daily or six-hourly TSI in W/m².

The interval is [time_min, time_max) in UTC, applied to the nominal averaging-bin timestamp. At-1-AU and actual-Earth-distance irradiances remain separate. Source zero fill values become NaN; missing intervals are not interpolated. valid_measurement requires both irradiances to be finite and positive. provisional_flag is preserved when present and is not interpreted as a missing-value flag.

Parameters:
Return type:

DataFrame

spectral_irradiance(dataset_id='tsis_ssi_24hr', *, time_min, time_max, cache_path=None)[source]#

Return measured TSIS-1 SIM spectra as wavelength-resolved rows.

Wavelength is in nm, irradiance in W/m²/nm, and the time interval is end-exclusive. All source quality bits are retained as quality_flag; quality_good conservatively selects zero-flag bins. Flagged bins remain in the frame. Do not integrate across missing or rejected spectral intervals or assume this 200–2400 nm product covers all TSI. At most 31 days may be requested per call to bound response size.

Parameters:
Return type:

DataFrame

class space_pv_connectors.N2YOConnector(*, api_key=None, timeout_s=30)[source]#

N2YO REST v1. Keep API keys on the server, outside browser bundles.

Positions are provider predictions, not satellite GPS telemetry. The free service documents 1,000 position calls/hour and at most 300 samples/call. No retries are made here. Bulk tracking should use cached GP + local SGP4. https://www.n2yo.com/api/

Parameters:
  • api_key (str | None)

  • timeout_s (float)

positions(norad_id, *, observer_lat, observer_lon, observer_alt_m=0, seconds=60)[source]#

Return the provider’s timestamped position JSON, including provenance.

sataltitude in the provider payload is km; observer altitude is m. Element epoch is not supplied by this endpoint and remains unknown.

Parameters:
Return type:

dict[str, Any]

class space_pv_connectors.NaifKernelConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Download explicitly selected NASA NAIF SPICE kernels with provenance receipt.

Parameters:
class space_pv_connectors.NoaaSwpcConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NOAA Space Weather Prediction Center JSON feed connector.

Parameters:
solar_wind_magnetic_field()[source]#

Return native real-time solar-wind magnetic-field records (L1).

Preserve provider coordinates, spacecraft identity and quality fields. This is upstream solar-wind context, not a local spacecraft field model.

Return type:

Any

solar_activity(product, *, cache_path=None, refresh=False)[source]#

Return UTC X-ray, Kp or alert records with source provenance.

Products are xrays (primary GOES, rolling six hours), kp (estimated planetary Kp), and alerts (provider bulletin text). Original fields are retained. A cache is a frozen snapshot until explicitly refreshed; inspect timestamp/retrieved_at for freshness. X-rays are band-limited irradiance, not total sunlight or PV power.

Parameters:
Return type:

DataFrame

goes_integral_particle_flux(particle, *, role='primary', period='7-day', cache_path=None, refresh=False)[source]#

Fetch measured GOES integral proton or electron flux.

period selects a rolling 6-hour, 1-day, 3-day or 7-day observation feed. This is not a historical-date API. role is primary or secondary; the actual GOES number is retained for each record.

A cache stores the original response with a JSON provenance sidecar. Subsequent calls reuse that exact snapshot unless refresh=True. A mismatched request or checksum raises instead of silently using data for another channel. Electron flux can be contaminated during energetic proton events; this feed does not supply a per-record contamination flag.

Parameters:
Return type:

DataFrame

class space_pv_connectors.NtrsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA Technical Reports Server: public metadata and available documents.

No account is needed. A search hit can be metadata-only. Preserve each record’s copyright/distribution fields; public access is not a blanket license to redistribute every paper. Design goals in papers are not flight performance measurements.

Parameters:
search(query, *, offset=0, page_size=25, cache_path=None, refresh=False)[source]#

Search one page; offset is the zero-based record offset.

Parameters:
Return type:

ResearchResponse

citation(citation_id, *, cache_path=None, refresh=False)[source]#

Get metadata, original download links and access/copyright details.

Parameters:
Return type:

ResearchResponse

download_document(citation_id, filename, destination, *, max_bytes=100000000)[source]#

Download an explicitly selected, publicly available original file.

Parameters:
Return type:

DownloadReceipt

class space_pv_connectors.OpenStreetMapEnergyConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Retrieve small-area raw solar/wind features with original OSM structure.

generator:source and plant:source select the paper’s input features without requiring a second power tag. For older tagging, the query also includes power_source on power=generator or power=plant objects. This additional legacy selection is explicit and is not an exact replay of the paper’s 2020 search. solar can include solar thermal: inspect the source’s method/type tags before treating features as photovoltaic arrays.

The result is Overpass JSON, not GeoJSON. Nodes, way-node references, all tags, relation member roles and available geometry are preserved. The query requests full geometry rather than clipping outlines at the bounding box. A way/relation can therefore extend beyond the requested region. Nested relation references remain references and may need additional resolution. No polygon merging, geometry repair, capacity parsing or clustering occurs.

The current snapshot and source timestamp are retained. The optional cache stores original response bytes and a .meta.json sidecar containing the query, retrieval time, license and SHA-256. Public Overpass availability and rate limits apply; global extraction belongs in a regional/planet workflow.

Parameters:
fetch_energy_features(*, bbox, sources=('solar', 'wind'), cache_path=None, refresh=False)[source]#

Return the raw source-tagged nodes, ways and relations for a region.

Parameters:
  • bbox (sequence of float) – (west, south, east, north) in WGS84 longitude/latitude degrees. At most one square degree is allowed. Antimeridian-crossing regions must be split into separate boxes. This is a feature-selection box, not an exact polygon-intersection test or an output-geometry clip.

  • sources (sequence of str) – Any nonempty subset of ("solar", "wind"). Input order and duplicate values do not change the query or cache identity.

  • cache_path (str or pathlib.Path, optional) – Original Overpass JSON cache. An existing cache must match both the complete query and its recorded checksum; mismatches raise errors.

  • refresh (bool) – Fetch a new snapshot and replace the cache only after a valid, complete response has been received. Defaults to offline cache reuse.

Returns:

Original decoded Overpass object, including elements and source metadata such as osm3s.timestamp_osm_base when provided. An empty elements list is a valid result; provider errors are never converted into an empty dataset.

Return type:

dict

class space_pv_connectors.OpsSatADConnector(*, timeout_s=120.0)[source]#

Download the original telemetry CSV from the fixed OPSSAT-AD v2 release.

Data are CC BY 4.0, DOI 10.5281/zenodo.15108715. The 19 MB CSV contains measured magnetometer and photodiode channels, rather than the separate handcrafted-feature table. No credentials are required.

The source does not include engineering-unit declarations. Values are preserved in their published scale, without interpreting photodiodes as solar-panel current, irradiance, or generated electrical power.

Parameters:

timeout_s (float)

download(destination)[source]#

Download, verify, and preserve the source CSV and a provenance sidecar.

Parameters:

destination (str | Path)

Return type:

DownloadReceipt

download_frame(destination, *, channels=None, split=None, refresh=False)[source]#

Load selected channels/split, reusing only checksum-verified cached data.

channels is a sequence of source IDs, such as ["CADC0892"]. split is "train", "test", or None for both. Filtering keeps the source segment identifiers and the published benchmark split. A corrupt or different local file raises instead of silently replacing it.

Parameters:
Return type:

DataFrame

class space_pv_connectors.PVSite(name, bbox_wgs84, scenes, item, images, osm)[source]#

Source imagery and mapped solar features for one inspection area.

images contains native-grid GroundImage objects keyed by STAC asset name. item is the selected scene from the bounded scenes search, and osm is the original Overpass response. Each image keeps its own resolution, mask and calibration; the map and image dates can differ.

The name is a display label, not a verified inventory record. Solar-tagged OSM features still need method-tag inspection before identifying them as photovoltaic. Neither this object nor its loader infers plant boundaries, panel area, capacity, generation or completeness of OSM mapping.

Parameters:
summary()[source]#

Return JSON-serializable dates, search limits and native-grid facts.

Pixel sizes use the units of the asset CRS. OSM counts describe raw objects, not unique plants; SCL counts describe source quality classes, not panel labels. Masked pixels are excluded from SCL counts.

Return type:

dict[str, Any]

class space_pv_connectors.PdsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA PDS Search API: mission product metadata, labels and data links.

Archive coverage is incomplete. Retain labels to interpret product units and calibration; a search hit is not necessarily a power measurement.

Parameters:
search(query, *, limit=25, sort=None, search_after=None, cache_path=None, refresh=False)[source]#

Search using PDS q expressions; cursor pagination requires sort.

Example: '(product_class eq "Product_Bundle")'. Use provider field names and operators, not SQL. The documented keywords parameter is not exposed: it was silently ignored by the live service in the access check.

Parameters:
  • query (str)

  • limit (int)

  • sort (str | None)

  • search_after (str | None)

  • cache_path (str | Path | None)

  • refresh (bool)

Return type:

ResearchResponse

product(identifier, *, cache_path=None, refresh=False)[source]#

Resolve a PDS LID or versioned LIDVID to its product metadata.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.PsaConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

ESA Planetary Science Archive TAP/EPN-TAP read-only ADQL queries.

JSON responses retain column names, units, types and data access links. max_records bounds a response; reaching it may indicate truncation. The service does not provide universal spacecraft EPS telemetry.

Parameters:
query(adql, *, max_records=100, cache_path=None, refresh=False)[source]#

Run a SELECT ADQL query; results are bounded, not a complete archive.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.ResearchResponse(data, receipt, request_url, documentation)[source]#

Provider metadata and the receipt for its original response bytes.

request_url includes non-secret query parameters; authentication headers are never serialized. JSON connectors retain provider units, licenses, pagination, versions and uncertainty fields. The arXiv connector documents its Atom-to-metadata normalization and can cache original XML bytes. Neither representation is a validated engineering or PV specification.

Parameters:
class space_pv_connectors.SatnogsDbConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

SatNOGS DB metadata and TLE API; telemetry endpoints require authentication.

Public satellite metadata does not imply anonymous telemetry access. The current telemetry endpoint returns HTTP 401 without credentials.

Parameters:
telemetry(**filters)[source]#

Retrieve decoded/raw telemetry records using SatNOGS API filter parameters.

Parameters:

filters (str | int | float | bool)

Return type:

dict[str, Any] | list[dict[str, Any]]

class space_pv_connectors.Sentinel2GroundConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Search Sentinel-2 Collection 1 and retrieve ground-image assets.

Search needs only the base installation. Windowed reading needs the optional ground extra (Rasterio). STAC item metadata stays intact, including each asset’s native resolution, calibration and nodata values. The provider’s scene-wide cloud percentage is not an AOI cloud mask.

Parameters:
search(*, bbox, time_min, time_max, max_cloud_cover=20.0, max_items=20, cache_path=None, refresh=False)[source]#

Return a bounded STAC FeatureCollection, clearest scenes first.

bbox is west/south/east/north in WGS84 degrees. Time bounds are inclusive UTC instants, as in STAC; a date alone means midnight. max_items caps unique items, not pages. context.limit_reached flags a filled cap: this result must not be assumed exhaustive.

POST/GET pagination is followed with its declared body/merge semantics. Cached snapshots preserve full item metadata and a SHA-256 sidecar binding the file to this query. A changed query or damaged snapshot raises an error; refresh=True explicitly replaces the snapshot.

Parameters:
Return type:

dict[str, Any]

static read_image(item, *, bbox, asset='visual', max_pixels=4000000)[source]#

Read a native-resolution COG window; see read_ground_image().

Parameters:
Return type:

GroundImage

download_asset(item, asset, destination, *, max_bytes=1000000000, overwrite=False)[source]#

Stream a complete asset to disk with a checksum/provenance sidecar.

Full Sentinel-2 bands can be hundreds of MB. Prefer read_image for farm-sized areas. The size ceiling is enforced while streaming, and a failed request never replaces an existing destination.

Parameters:
Return type:

DownloadReceipt

class space_pv_connectors.SettlementRaster(data, crs, transform, bounds, bbox_wgs84, epoch, edition, provenance)[source]#

A native 1 km categorical GHSL crop and its source provenance.

data is a two-dimensional masked integer array. These classes describe settlement context at epoch; they do not describe current PV land use or validate an individual rooftop, ground-mounted plant or water boundary. The original grid is retained, unlike the paper’s Eckert IV reprojection.

Parameters:
sample_points(lon_lat)[source]#

Sample WGS84 points without interpolation; unknown flags are None.

Supplying farm centroids implements a clearly defined centroid lookup. It does not calculate the fraction of an entire farm covered by water or urban cells. Outside-crop, masked and unknown-code results remain explicit rather than being counted as rural/non-water observations.

Parameters:

lon_lat (Sequence[Sequence[float]])

Return type:

list[dict[str, Any]]

save(destination, *, overwrite=False)[source]#

Write raw classes and internal nodata mask with a SHA-256 sidecar.

Parameters:
Return type:

None

class space_pv_connectors.SpaceTrackConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Authenticated Space-Track GP/GP-history connector.

Credentials should be supplied by environment/secrets management, never committed.

Parameters:
latest_gp_cached(norad_cat_id, *, cache_path)[source]#

Reuse current OMM for two hours; authenticate first on a cache miss.

Shares the same persistent snapshot/provenance contract as CelesTrak. This conservative interval also satisfies Space-Track’s hourly GP limit.

Parameters:
Return type:

GPSnapshot

gp_history(norad_cat_id, *, start, end, cache_dir, max_records=100000)[source]#

Fetch and cache a bounded, complete EPOCH interval in chronological order.

Space-Track requests that GP history be downloaded once and reused from disk. A mandatory cache prevents repeated calls for an identical interval. start and end are inclusive, timezone-aware element epochs, not publication dates. Authentication is required for a cache miss. Queries over one year should use provider bulk/year files instead.

Source: https://www.space-track.org/documentation

Parameters:
Return type:

list[dict[str, Any]]

class space_pv_connectors.SscWebConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA Satellite Situation Center metadata and ephemeris-service connector.

Parameters:
class space_pv_connectors.ZenodoConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Discover published research datasets and download open files anonymously.

Restricted files remain restricted. Each record supplies its own license; no deposit, publication or authenticated write endpoints are used.

Parameters:
search(query, *, page=1, page_size=25, cache_path=None, refresh=False)[source]#

Search one page using Zenodo query syntax (anonymous maximum: 25).

Parameters:
Return type:

ResearchResponse

record(record_id, *, cache_path=None, refresh=False)[source]#

Read a specific record/version, including DOI, license and file checksums.

Parameters:
Return type:

ResearchResponse

download_file(record_id, filename, destination, *, max_bytes=100000000)[source]#

Select a public file by exact name and verify its provider checksum.

Parameters:
Return type:

DownloadReceipt

space_pv_connectors.load_birds_eps_workbook(path, *, normalized=True, campaign_year=None)[source]#

Load a downloaded BIRDS EPS workbook into the canonical panel schema.

Parameters:
  • path (str or pathlib.Path) – Downloaded upstream XLSX workbook.

  • normalized (bool, default True) – Return panel-level flight telemetry. The known undated TSURU sheets Test1 w batt and Test2 wo batt are excluded from this mode. False returns raw rows from every nonempty sheet, including tests.

  • campaign_year (int, optional) – Explicit year for campaign sheet dates that omit it. For example, the TSURU 2021 flight campaigns require campaign_year=2021. A year already stated in a sheet name is always preserved. No current-year assumption is made; an omitted year raises an actionable error.

Return type:

DataFrame

Notes

Calibrated numeric Time Stamp values are elapsed seconds. The returned timestamp anchors these to midnight on campaign_date for ordering; this is not a known absolute UTC acquisition time. The original clock is retained in elapsed_seconds and the convention in timestamp_basis. campaign_date_basis records whether a year was supplied by the caller. Rows without a valid elapsed clock or voltage/current pair are omitted.

space_pv_connectors.load_flying_laptop_power(path, *, time_min=None, time_max=None)[source]#

Read calibrated solar-array V, I and computed power from a local archive.

time_min is inclusive and time_max exclusive; naive bounds are UTC. Timestamps are the source’s Unix epoch milliseconds in UTC, identifying packet generation. The source documents up to 400 ms of additional sensor acquisition delay. Missing/invalid readings remain missing and are omitted per voltage/current pair; signed sensor values are not clipped.

Four panel identifiers are preserved: right, left, center and test. Here test is the spacecraft’s experimental array channel, not a separate ground-test recording. Power is computed as V times I; no independently transmitted power measurement is implied.

The reader streams only matching packet 4900 members, never extracting archive paths to disk. A downloaded provenance sidecar, when present, is verified against the local archive. Source metadata is returned in attrs.

Parameters:
Return type:

DataFrame

space_pv_connectors.load_goes_integral_particle_flux(path, *, particle)[source]#

Read an original SWPC integral-flux JSON snapshot without network access.

Raw fields are retained. Negative, nonfinite or missing flux values become NaN in flux_cm2_s_sr and are flagged by is_valid_flux. Integral energy channels overlap and must not be added together. Satellite identity is taken from every measurement, since primary proton/electron sources can differ.

Parameters:
Return type:

DataFrame

space_pv_connectors.load_ground_image(path, *, max_pixels=4000000)[source]#

Load a saved native crop after verifying its pixels and provenance.

Read the GeoTIFF and .meta.json written by GroundImage.save_geotiff(). The SHA-256, byte count, source identity, native grid, nodata and calibration must agree. The metadata’s original path is informational, so snapshots can move between computers. Unverified external mask/PAM files are rejected.

max_pixels counts all band samples and is enforced before reading the pixels. Raw values, per-band masks and the complete source STAC item are retained; this function never makes network requests or applies calibration.

Parameters:
Return type:

GroundImage

space_pv_connectors.load_opssat_segments(path, *, channels=None, split=None)[source]#

Read original OPSSAT-AD telemetry without resampling or merging segments.

Every source column is retained. timestamp becomes a UTC datetime; value stays on its original published scale. Missing/nonfinite values are retained and marked by is_valid_value; no fill value or physical unit is invented. value_unit explicitly records that units are absent from the source CSV.

Use the source’s numeric anomaly field for the expert annotation. The textual label column contains "anomaly" even for nominal segments in v2, so it must not be treated as a classification result. train is the fixed benchmark split, not a chronological split.

A local subset may be loaded for offline analysis. The returned attrs contain its checksum and whether it matches the complete pinned release.

Parameters:
Return type:

DataFrame

space_pv_connectors.load_pv_site(*, bbox, time_min, time_max, cache_dir, name='PV site', cache_prefix='site', max_cloud_cover=20.0, max_items=10, scene_id=None, assets=('visual', 'red', 'scl'), offline=False, refresh=False, timeout_s=60.0, max_pixels=4000000)[source]#

Load or retrieve imagery and OSM inputs for a small PV inspection area.

Search Sentinel-2 Collection 1, select the first (lowest scene-cloud-cover) returned item by default, load native crops, and retrieve raw solar-tagged OSM features. A supplied scene_id must occur in the bounded search. Search intersection does not guarantee full raster coverage; the underlying crop reader raises for tile-edge areas rather than mosaicking implicitly.

bbox is WGS84 (west, south, east, north) and must satisfy the OSM connector’s one-square-degree limit. Time bounds are inclusive UTC instants. Scene-wide cloud cover is not a local cloud mask. Inspect quality classes and site.scenes['context']['limit_reached'] when selecting inputs.

The cache contains {prefix}-scenes.json, {prefix}-osm.json and {prefix}-{asset}.tif, each with its provenance sidecar. Existing caches must match the request, SHA-256, selected scene, asset metadata and grid. Only missing files are retrieved; incomplete or inconsistent caches raise. refresh=True explicitly retrieves replacement snapshots and crops. A refresh is not a transaction across all files: if it fails, retry with refresh enabled or use a new cache prefix. Mixed snapshots fail validation.

offline=True requires every source file and sidecar before any loading begins, blocks HTTP fallback, and cannot be combined with refresh=True. max_pixels limits band samples per asset, not the sum across assets. Install orbital-pv[ground] for GeoTIFF support; plotting is separate.

Parameters:
Return type:

PVSite

space_pv_connectors.load_settlement_raster(path, *, max_pixels=1000000)[source]#

Restore and verify a saved GHSL crop entirely offline.

Parameters:
Return type:

SettlementRaster

space_pv_connectors.parse_arxiv_atom(content, paper_id)[source]#

Parse one exact-version Atom entry; never silently substitute latest.

Parameters:
Return type:

dict[str, object]

space_pv_connectors.read_ground_image(item, *, bbox, asset='visual', max_pixels=4000000)[source]#

Read a WGS84 area from one HTTPS GeoTIFF asset at native resolution.

bbox is (west, south, east, north) in longitude/latitude degrees. The crop covers the transformed bounding rectangle, rounded outward to source pixels; it is not an exact polygon clip. The selected tile must cover the entire crop. Select another tile or mosaic explicitly when an area crosses a tile edge.

max_pixels limits the total band samples (bands * rows * columns) before pixel data are read. COG range reads retrieve the intersecting compressed blocks, which can be larger than the requested pixel window. Different assets retain their native grids (e.g. RGB 10 m, SCL 20 m). No reprojection, resampling, reflectance scaling or cloud mask occurs.

Parameters:
Return type:

GroundImage

Ground satellite imagery#

Ground imagery from the public Earth Search Sentinel-2 STAC API.

The default Collection 1 product supplies native-resolution COG assets without an account. Imagery supports inspection of terrestrial energy installations; it is not an estimate of generated power or a reproduction of Dunnett (2020). Source: Element84/earth-search.

class space_pv_connectors.ground_imagery.Sentinel2GroundConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Search Sentinel-2 Collection 1 and retrieve ground-image assets.

Search needs only the base installation. Windowed reading needs the optional ground extra (Rasterio). STAC item metadata stays intact, including each asset’s native resolution, calibration and nodata values. The provider’s scene-wide cloud percentage is not an AOI cloud mask.

Parameters:
search(*, bbox, time_min, time_max, max_cloud_cover=20.0, max_items=20, cache_path=None, refresh=False)[source]#

Return a bounded STAC FeatureCollection, clearest scenes first.

bbox is west/south/east/north in WGS84 degrees. Time bounds are inclusive UTC instants, as in STAC; a date alone means midnight. max_items caps unique items, not pages. context.limit_reached flags a filled cap: this result must not be assumed exhaustive.

POST/GET pagination is followed with its declared body/merge semantics. Cached snapshots preserve full item metadata and a SHA-256 sidecar binding the file to this query. A changed query or damaged snapshot raises an error; refresh=True explicitly replaces the snapshot.

Parameters:
Return type:

dict[str, Any]

static read_image(item, *, bbox, asset='visual', max_pixels=4000000)[source]#

Read a native-resolution COG window; see read_ground_image().

Parameters:
Return type:

GroundImage

download_asset(item, asset, destination, *, max_bytes=1000000000, overwrite=False)[source]#

Stream a complete asset to disk with a checksum/provenance sidecar.

Full Sentinel-2 bands can be hundreds of MB. Prefer read_image for farm-sized areas. The size ceiling is enforced while streaming, and a failed request never replaces an existing destination.

Parameters:
Return type:

DownloadReceipt

Native-grid subsets of public ground-imaging Cloud Optimized GeoTIFFs.

Rasterio is optional and is imported only when reading or writing an image. Pixels retain their source values, resolution and nodata mask. This module does not infer farm boundaries, resample bands or classify cloudy pixels.

class space_pv_connectors.ground_raster.GroundImage(data, crs, transform, bounds, scene_id, asset_key, source_url, asset_metadata, bbox_wgs84, item_metadata, nodata_values, retrieved_at)[source]#

A native-resolution rectangular crop, retaining raw pixel semantics.

data has shape (bands, rows, columns); True mask entries mean missing data. transform holds affine (a, b, c, d, e, f) coefficients and bounds is (left, bottom, right, top) in crs. Pixel-aligned bounds can extend slightly beyond the requested bbox_wgs84.

visual is a rendered RGB product, not calibrated reflectance. scl is a categorical scene-classification product, not a power or irradiance measurement. No cloud masking is applied implicitly.

Parameters:
reflectance()[source]#

Return raw * scale + offset using explicit STAC band metadata.

Only assets declaring the reflectance role are accepted. Missing data remain masked before calibration; negative reflectance values are retained. The raw data is never modified. For example, Collection 1 commonly declares scale 0.0001 and offset -0.1, so dividing every product by 10000 without its offset would be wrong.

Return type:

MaskedArray

save_geotiff(destination, *, overwrite=False)[source]#

Save raw pixels, georeferencing, calibration and provenance.

The .meta.json sidecar includes the complete source STAC item, asset metadata, requested/actual bounds and the output SHA-256. The checksum identifies this derived crop, not the original full tile. A GeoTIFF internal mask is used when all band masks agree. Distinct band masks are retained through a shared nodata value when possible; unsupported mask combinations raise rather than discard information.

Parameters:
Return type:

DownloadReceipt

space_pv_connectors.ground_raster.load_ground_image(path, *, max_pixels=4000000)[source]#

Load a saved native crop after verifying its pixels and provenance.

Read the GeoTIFF and .meta.json written by GroundImage.save_geotiff(). The SHA-256, byte count, source identity, native grid, nodata and calibration must agree. The metadata’s original path is informational, so snapshots can move between computers. Unverified external mask/PAM files are rejected.

max_pixels counts all band samples and is enforced before reading the pixels. Raw values, per-band masks and the complete source STAC item are retained; this function never makes network requests or applies calibration.

Parameters:
Return type:

GroundImage

space_pv_connectors.ground_raster.read_ground_image(item, *, bbox, asset='visual', max_pixels=4000000)[source]#

Read a WGS84 area from one HTTPS GeoTIFF asset at native resolution.

bbox is (west, south, east, north) in longitude/latitude degrees. The crop covers the transformed bounding rectangle, rounded outward to source pixels; it is not an exact polygon clip. The selected tile must cover the entire crop. Select another tile or mosaic explicitly when an area crosses a tile edge.

max_pixels limits the total band samples (bands * rows * columns) before pixel data are read. COG range reads retrieve the intersecting compressed blocks, which can be larger than the requested pixel window. Different assets retain their native grids (e.g. RGB 10 m, SCL 20 m). No reprojection, resampling, reflectance scaling or cloud mask occurs.

Parameters:
Return type:

GroundImage

Cached PV site inputs#

Reusable, provenance-checked inputs for inspecting terrestrial PV sites.

class space_pv_connectors.ground_site.PVSite(name, bbox_wgs84, scenes, item, images, osm)[source]#

Source imagery and mapped solar features for one inspection area.

images contains native-grid GroundImage objects keyed by STAC asset name. item is the selected scene from the bounded scenes search, and osm is the original Overpass response. Each image keeps its own resolution, mask and calibration; the map and image dates can differ.

The name is a display label, not a verified inventory record. Solar-tagged OSM features still need method-tag inspection before identifying them as photovoltaic. Neither this object nor its loader infers plant boundaries, panel area, capacity, generation or completeness of OSM mapping.

Parameters:
summary()[source]#

Return JSON-serializable dates, search limits and native-grid facts.

Pixel sizes use the units of the asset CRS. OSM counts describe raw objects, not unique plants; SCL counts describe source quality classes, not panel labels. Masked pixels are excluded from SCL counts.

Return type:

dict[str, Any]

space_pv_connectors.ground_site.load_pv_site(*, bbox, time_min, time_max, cache_dir, name='PV site', cache_prefix='site', max_cloud_cover=20.0, max_items=10, scene_id=None, assets=('visual', 'red', 'scl'), offline=False, refresh=False, timeout_s=60.0, max_pixels=4000000)[source]#

Load or retrieve imagery and OSM inputs for a small PV inspection area.

Search Sentinel-2 Collection 1, select the first (lowest scene-cloud-cover) returned item by default, load native crops, and retrieve raw solar-tagged OSM features. A supplied scene_id must occur in the bounded search. Search intersection does not guarantee full raster coverage; the underlying crop reader raises for tile-edge areas rather than mosaicking implicitly.

bbox is WGS84 (west, south, east, north) and must satisfy the OSM connector’s one-square-degree limit. Time bounds are inclusive UTC instants. Scene-wide cloud cover is not a local cloud mask. Inspect quality classes and site.scenes['context']['limit_reached'] when selecting inputs.

The cache contains {prefix}-scenes.json, {prefix}-osm.json and {prefix}-{asset}.tif, each with its provenance sidecar. Existing caches must match the request, SHA-256, selected scene, asset metadata and grid. Only missing files are retrieved; incomplete or inconsistent caches raise. refresh=True explicitly retrieves replacement snapshots and crops. A refresh is not a transaction across all files: if it fails, retry with refresh enabled or use a new cache prefix. Mixed snapshots fail validation.

offline=True requires every source file and sidecar before any loading begins, blocks HTTP fallback, and cannot be combined with refresh=True. max_pixels limits band samples per asset, not the sum across assets. Install orbital-pv[ground] for GeoTIFF support; plotting is separate.

Parameters:
Return type:

PVSite

Ground renewable-energy features#

Ground energy features from OpenStreetMap’s public Overpass API.

The primary source-tag selection follows Dunnett et al. (2020), https://doi.org/10.1038/s41597-020-0469-8. The raw extract is not a reproduction of their historical database, spatial clustering, or capacity estimates. OpenStreetMap data are © OpenStreetMap contributors, licensed under ODbL: https://www.openstreetmap.org/copyright.

class space_pv_connectors.ground_osm.OpenStreetMapEnergyConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Retrieve small-area raw solar/wind features with original OSM structure.

generator:source and plant:source select the paper’s input features without requiring a second power tag. For older tagging, the query also includes power_source on power=generator or power=plant objects. This additional legacy selection is explicit and is not an exact replay of the paper’s 2020 search. solar can include solar thermal: inspect the source’s method/type tags before treating features as photovoltaic arrays.

The result is Overpass JSON, not GeoJSON. Nodes, way-node references, all tags, relation member roles and available geometry are preserved. The query requests full geometry rather than clipping outlines at the bounding box. A way/relation can therefore extend beyond the requested region. Nested relation references remain references and may need additional resolution. No polygon merging, geometry repair, capacity parsing or clustering occurs.

The current snapshot and source timestamp are retained. The optional cache stores original response bytes and a .meta.json sidecar containing the query, retrieval time, license and SHA-256. Public Overpass availability and rate limits apply; global extraction belongs in a regional/planet workflow.

Parameters:
fetch_energy_features(*, bbox, sources=('solar', 'wind'), cache_path=None, refresh=False)[source]#

Return the raw source-tagged nodes, ways and relations for a region.

Parameters:
  • bbox (sequence of float) – (west, south, east, north) in WGS84 longitude/latitude degrees. At most one square degree is allowed. Antimeridian-crossing regions must be split into separate boxes. This is a feature-selection box, not an exact polygon-intersection test or an output-geometry clip.

  • sources (sequence of str) – Any nonempty subset of ("solar", "wind"). Input order and duplicate values do not change the query or cache identity.

  • cache_path (str or pathlib.Path, optional) – Original Overpass JSON cache. An existing cache must match both the complete query and its recorded checksum; mismatches raise errors.

  • refresh (bool) – Fetch a new snapshot and replace the cache only after a valid, complete response has been received. Defaults to offline cache reuse.

Returns:

Original decoded Overpass object, including elements and source metadata such as osm3s.timestamp_osm_base when provided. An empty elements list is a valid result; provider errors are never converted into an empty dataset.

Return type:

dict

Historical settlement context#

Native GHSL settlement classes for terrestrial PV inventory context.

The paper’s urban categories are codes 21, 22, 23 and 30; water is code 10. R2023A is a newer processing edition, even when its epoch is 2015. It is not the historical R2019A input used by Dunnett et al. (2020). A local R2019A raster can be supplied explicitly; editions are never substituted silently.

Sources: https://doi.org/10.1038/s41597-020-0469-8 and the JRC GHSL manuals, https://human-settlement.emergency.copernicus.eu/documents/GHSL_Data_Package_2019.pdf and https://human-settlement.emergency.copernicus.eu/ghs_smod2023.php.

class space_pv_connectors.ground_ghsl.SettlementRaster(data, crs, transform, bounds, bbox_wgs84, epoch, edition, provenance)[source]#

A native 1 km categorical GHSL crop and its source provenance.

data is a two-dimensional masked integer array. These classes describe settlement context at epoch; they do not describe current PV land use or validate an individual rooftop, ground-mounted plant or water boundary. The original grid is retained, unlike the paper’s Eckert IV reprojection.

Parameters:
sample_points(lon_lat)[source]#

Sample WGS84 points without interpolation; unknown flags are None.

Supplying farm centroids implements a clearly defined centroid lookup. It does not calculate the fraction of an entire farm covered by water or urban cells. Outside-crop, masked and unknown-code results remain explicit rather than being counted as rural/non-water observations.

Parameters:

lon_lat (Sequence[Sequence[float]])

Return type:

list[dict[str, Any]]

save(destination, *, overwrite=False)[source]#

Write raw classes and internal nodata mask with a SHA-256 sidecar.

Parameters:
Return type:

None

space_pv_connectors.ground_ghsl.load_settlement_raster(path, *, max_pixels=1000000)[source]#

Restore and verify a saved GHSL crop entirely offline.

Parameters:
Return type:

SettlementRaster

class space_pv_connectors.ground_ghsl.GHSLSettlementConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Retrieve JRC GHS-SMOD context while preserving its edition and epoch.

The official R2023A V2.0 global ZIP is downloaded once and reused; the 2015 archive is about 29 MB. Only a bounded native-resolution window is read into memory. The ZIP size is capped before and during downloading, and its member is validated before Rasterio opens it.

Original R2019A downloads are no longer served at the official URL as of October 2026. Use edition='R2019A', source_path=... with a retained native historical GeoTIFF. No fallback to a different edition occurs.

Parameters:
fetch_settlement(*, bbox, cache_path, source_cache_dir=None, source_path=None, edition='R2023A', epoch=2015, refresh=False, offline=False, max_download_bytes=67108864, max_pixels=1000000)[source]#

Return a native crop for WGS84 (west, south, east, north).

offline permits an existing validated crop or local source, and prevents HTTP calls. refresh replaces a crop from the same source; archived versioned source files remain cached. A local source_path is hashed and its edition/epoch are caller declarations recorded in provenance; filenames alone cannot verify those declarations.

Parameters:
Return type:

SettlementRaster

BIRDS EPS#

class space_pv_connectors.birds.BirdsEPSConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Connector for the public BIRDS on-orbit EPS dataset.

Parameters:
download(satellite, destination)[source]#

Download one satellite workbook from the upstream BIRDS repository.

Parameters:
Return type:

DownloadReceipt

download_frame(satellite, destination, *, normalized=True, campaign_year=None)[source]#

Download and load a BIRDS EPS workbook.

campaign_year supplies the year only for campaign sheet names that omit it; see load_birds_eps_workbook() for the time convention.

Parameters:
  • satellite (str)

  • destination (str | Path)

  • normalized (bool)

  • campaign_year (int | None)

Return type:

DataFrame

space_pv_connectors.birds.load_birds_eps_workbook(path, *, normalized=True, campaign_year=None)[source]#

Load a downloaded BIRDS EPS workbook into the canonical panel schema.

Parameters:
  • path (str or pathlib.Path) – Downloaded upstream XLSX workbook.

  • normalized (bool, default True) – Return panel-level flight telemetry. The known undated TSURU sheets Test1 w batt and Test2 wo batt are excluded from this mode. False returns raw rows from every nonempty sheet, including tests.

  • campaign_year (int, optional) – Explicit year for campaign sheet dates that omit it. For example, the TSURU 2021 flight campaigns require campaign_year=2021. A year already stated in a sheet name is always preserved. No current-year assumption is made; an omitted year raises an actionable error.

Return type:

DataFrame

Notes

Calibrated numeric Time Stamp values are elapsed seconds. The returned timestamp anchors these to midnight on campaign_date for ordering; this is not a known absolute UTC acquisition time. The original clock is retained in elapsed_seconds and the convention in timestamp_basis. campaign_date_basis records whether a year was supplied by the caller. Rows without a valid elapsed clock or voltage/current pair are omitted.

CelesTrak#

Flying Laptop measured arrays#

Calibrated on-orbit solar-array telemetry from the Flying Laptop mission.

class space_pv_connectors.flying_laptop.FlyingLaptopConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Retrieve CC BY 4.0 Flying Laptop monthly archives from DaRUS.

The archive contains many housekeeping packets. The normalizer reads only packet 4900, whose calibrated array currents and voltages have documented units of A and V. Downloads retain a checksum-bearing provenance sidecar.

Parameters:
download_month(month, destination)[source]#

Download one YYYY-MM archive after checking its catalog checksum.

Parameters:
Return type:

DownloadReceipt

download_frame(month, destination, *, time_min=None, time_max=None)[source]#

Download a month and normalize the requested UTC time interval.

Parameters:
Return type:

DataFrame

space_pv_connectors.flying_laptop.load_flying_laptop_power(path, *, time_min=None, time_max=None)[source]#

Read calibrated solar-array V, I and computed power from a local archive.

time_min is inclusive and time_max exclusive; naive bounds are UTC. Timestamps are the source’s Unix epoch milliseconds in UTC, identifying packet generation. The source documents up to 400 ms of additional sensor acquisition delay. Missing/invalid readings remain missing and are omitted per voltage/current pair; signed sensor values are not clipped.

Four panel identifiers are preserved: right, left, center and test. Here test is the spacecraft’s experimental array channel, not a separate ground-test recording. Power is computed as V times I; no independently transmitted power measurement is implied.

The reader streams only matching packet 4900 members, never extracting archive paths to disk. A downloaded provenance sidecar, when present, is verified against the local archive. Source metadata is returned in attrs.

Parameters:
Return type:

DataFrame

OPS-SAT annotated measurements#

Original, annotated OPS-SAT telemetry segments from the pinned OPSSAT-AD v2 release.

class space_pv_connectors.opssat.OpsSatADConnector(*, timeout_s=120.0)[source]#

Download the original telemetry CSV from the fixed OPSSAT-AD v2 release.

Data are CC BY 4.0, DOI 10.5281/zenodo.15108715. The 19 MB CSV contains measured magnetometer and photodiode channels, rather than the separate handcrafted-feature table. No credentials are required.

The source does not include engineering-unit declarations. Values are preserved in their published scale, without interpreting photodiodes as solar-panel current, irradiance, or generated electrical power.

Parameters:

timeout_s (float)

download(destination)[source]#

Download, verify, and preserve the source CSV and a provenance sidecar.

Parameters:

destination (str | Path)

Return type:

DownloadReceipt

download_frame(destination, *, channels=None, split=None, refresh=False)[source]#

Load selected channels/split, reusing only checksum-verified cached data.

channels is a sequence of source IDs, such as ["CADC0892"]. split is "train", "test", or None for both. Filtering keeps the source segment identifiers and the published benchmark split. A corrupt or different local file raises instead of silently replacing it.

Parameters:
Return type:

DataFrame

space_pv_connectors.opssat.load_opssat_segments(path, *, channels=None, split=None)[source]#

Read original OPSSAT-AD telemetry without resampling or merging segments.

Every source column is retained. timestamp becomes a UTC datetime; value stays on its original published scale. Missing/nonfinite values are retained and marked by is_valid_value; no fill value or physical unit is invented. value_unit explicitly records that units are absent from the source CSV.

Use the source’s numeric anomaly field for the expert annotation. The textual label column contains "anomaly" even for nominal segments in v2, so it must not be treated as a classification result. train is the fixed benchmark split, not a chronological split.

A local subset may be loaded for offline analysis. The returned attrs contain its checksum and whether it matches the complete pinned release.

Parameters:
Return type:

DataFrame

LASP measured irradiance#

Measured total and spectral solar irradiance from LASP LISIRD.

These calibrated Level-3 science products measure incoming sunlight; they are not solar-array electrical-output telemetry. Source: https://lasp.colorado.edu/lisird/ and https://lasp.colorado.edu/tsis/data/.

class space_pv_connectors.lisird.LisirdConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Retrieve bounded, measured TSIS-1/SORCE irradiance datasets.

The LaTiS jsond response carries parameter order and units. Cache files contain the original JSON bytes plus a .meta.json sidecar binding the response to its dataset, time range and SHA-256. Reusing a different query with the same cache path raises an error instead of returning stale data. Data access is public; retain LASP/instrument-team attribution and consult the product release notes for the version used.

Parameters:
total_solar_irradiance(dataset_id='tsis_tsi_24hr', *, time_min, time_max, cache_path=None)[source]#

Return measured daily or six-hourly TSI in W/m².

The interval is [time_min, time_max) in UTC, applied to the nominal averaging-bin timestamp. At-1-AU and actual-Earth-distance irradiances remain separate. Source zero fill values become NaN; missing intervals are not interpolated. valid_measurement requires both irradiances to be finite and positive. provisional_flag is preserved when present and is not interpreted as a missing-value flag.

Parameters:
Return type:

DataFrame

spectral_irradiance(dataset_id='tsis_ssi_24hr', *, time_min, time_max, cache_path=None)[source]#

Return measured TSIS-1 SIM spectra as wavelength-resolved rows.

Wavelength is in nm, irradiance in W/m²/nm, and the time interval is end-exclusive. All source quality bits are retained as quality_flag; quality_good conservatively selects zero-flag bins. Flagged bins remain in the frame. Do not integrate across missing or rejected spectral intervals or assume this 200–2400 nm product covers all TSI. At most 31 days may be requested per call to bound response size.

Parameters:
Return type:

DataFrame

Space-Track#

class space_pv_connectors.space_track.SpaceTrackConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Authenticated Space-Track GP/GP-history connector.

Credentials should be supplied by environment/secrets management, never committed.

Parameters:
latest_gp_cached(norad_cat_id, *, cache_path)[source]#

Reuse current OMM for two hours; authenticate first on a cache miss.

Shares the same persistent snapshot/provenance contract as CelesTrak. This conservative interval also satisfies Space-Track’s hourly GP limit.

Parameters:
Return type:

GPSnapshot

gp_history(norad_cat_id, *, start, end, cache_dir, max_records=100000)[source]#

Fetch and cache a bounded, complete EPOCH interval in chronological order.

Space-Track requests that GP history be downloaded once and reused from disk. A mandatory cache prevents repeated calls for an identical interval. start and end are inclusive, timezone-aware element epochs, not publication dates. Authentication is required for a cache miss. Queries over one year should use provider bulk/year files instead.

Source: https://www.space-track.org/documentation

Parameters:
Return type:

list[dict[str, Any]]

SatNOGS#

class space_pv_connectors.satnogs.SatnogsDbConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

SatNOGS DB metadata and TLE API; telemetry endpoints require authentication.

Public satellite metadata does not imply anonymous telemetry access. The current telemetry endpoint returns HTTP 401 without credentials.

Parameters:
telemetry(**filters)[source]#

Retrieve decoded/raw telemetry records using SatNOGS API filter parameters.

Parameters:

filters (str | int | float | bool)

Return type:

dict[str, Any] | list[dict[str, Any]]

NASA / NOAA services#

class space_pv_connectors.sscweb.SscWebConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA Satellite Situation Center metadata and ephemeris-service connector.

Parameters:
class space_pv_connectors.naif.NaifKernelConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Download explicitly selected NASA NAIF SPICE kernels with provenance receipt.

Parameters:
class space_pv_connectors.swpc.NoaaSwpcConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NOAA Space Weather Prediction Center JSON feed connector.

Parameters:
solar_wind_magnetic_field()[source]#

Return native real-time solar-wind magnetic-field records (L1).

Preserve provider coordinates, spacecraft identity and quality fields. This is upstream solar-wind context, not a local spacecraft field model.

Return type:

Any

solar_activity(product, *, cache_path=None, refresh=False)[source]#

Return UTC X-ray, Kp or alert records with source provenance.

Products are xrays (primary GOES, rolling six hours), kp (estimated planetary Kp), and alerts (provider bulletin text). Original fields are retained. A cache is a frozen snapshot until explicitly refreshed; inspect timestamp/retrieved_at for freshness. X-rays are band-limited irradiance, not total sunlight or PV power.

Parameters:
Return type:

DataFrame

goes_integral_particle_flux(particle, *, role='primary', period='7-day', cache_path=None, refresh=False)[source]#

Fetch measured GOES integral proton or electron flux.

period selects a rolling 6-hour, 1-day, 3-day or 7-day observation feed. This is not a historical-date API. role is primary or secondary; the actual GOES number is retained for each record.

A cache stores the original response with a JSON provenance sidecar. Subsequent calls reuse that exact snapshot unless refresh=True. A mismatched request or checksum raises instead of silently using data for another channel. Electron flux can be contaminated during energetic proton events; this feed does not supply a per-record contamination flag.

Parameters:
Return type:

DataFrame

space_pv_connectors.swpc.load_goes_integral_particle_flux(path, *, particle)[source]#

Read an original SWPC integral-flux JSON snapshot without network access.

Raw fields are retained. Negative, nonfinite or missing flux values become NaN in flux_cm2_s_sr and are flagged by is_valid_flux. Integral energy channels overlap and must not be added together. Satellite identity is taken from every measurement, since primary proton/electron sources can differ.

Parameters:
Return type:

DataFrame

space_pv_connectors.swpc.normalize_solar_activity(payload, product)[source]#

Normalize native SWPC snapshots without network access.

Negative/nonfinite flux and Kp outside 0–9 are flagged and masked in canonical columns, while raw source fields remain available for auditing. Empty lists represent no records, never fabricated quiet conditions.

Parameters:
Return type:

DataFrame

Free spacecraft research APIs#

Free spacecraft metadata, technical literature, archives and geometry APIs.

These connectors return provider facts with provenance. They do not infer PV ratings, parse technical papers into accepted catalogue records, or turn space weather events into spacecraft radiation doses. Searches return one bounded page; retain provider totals/links and request subsequent pages explicitly.

class space_pv_connectors.research.DataverseConnector(*, base_url='https://darus.uni-stuttgart.de', timeout_s=30.0)[source]#

Public Dataverse search and versioned dataset access; defaults to DaRUS.

Another public installation can be selected with base_url. Dataset and file licenses are provider-specific. Private/restricted data are not fetched.

Parameters:
search(query, *, start=0, page_size=25, cache_path=None, refresh=False)[source]#

Search public datasets; start is a zero-based record offset.

Parameters:
Return type:

ResearchResponse

dataset(persistent_id, *, version=':latest-published', cache_path=None, refresh=False)[source]#

Fetch published dataset metadata; pin version='1.0' for reproducibility.

Parameters:
Return type:

ResearchResponse

download_file(persistent_id, filename, destination, *, version=':latest-published', max_bytes=100000000)[source]#

Download the original public file and verify its dataset checksum.

Parameters:
Return type:

DownloadReceipt

class space_pv_connectors.research.DiscosConnector(*, token, timeout_s=30.0)[source]#

ESA DISCOS v2 metadata; free registration and an explicit token required.

DISCOS IDs and NORAD catalog numbers are different identifiers. This API supplies object/launch metadata, not ephemerides or universal PV ratings.

Parameters:
objects(*, filter_expression=None, page=1, page_size=100, cache_path=None, refresh=False)[source]#

Get one page of objects using the provider’s filter syntax.

Parameters:
  • filter_expression (str | None)

  • page (int)

  • page_size (int)

  • cache_path (str | Path | None)

  • refresh (bool)

Return type:

ResearchResponse

object(discos_id, *, cache_path=None, refresh=False)[source]#

Retrieve one object by its DISCOS internal ID.

Parameters:
Return type:

ResearchResponse

by_norad(norad_id, *, cache_path=None, refresh=False)[source]#

Search the NORAD satno field; preserve an empty or ambiguous result.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.research.DonkiConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA CCMC DONKI event catalog, accessed directly without a NASA API key.

Uses the September 2026 CCMC endpoint, not the retired kauai host. Events are research context, not spacecraft-specific dose or causation evidence. Follow CCMC’s attribution and publication rules for event studies.

Parameters:
events(event_type, *, start, stop, cache_path=None, refresh=False)[source]#

Get an explicit UTC date window (provider endDate is inclusive).

The raw empty response may be null or an empty list. Event links and associated instruments/spacecraft are kept, without assigning them to other missions.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.research.HorizonsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Public NASA/JPL ephemerides for supported targets, including spacecraft.

Returns the original JSON envelope containing the ephemeris text, headers, units and API signature. Vectors use ICRF axes, TDB time, geometric (no light-time) corrections and AU/day units. No spacecraft attitude or PV output is implied. Target coverage is determined by JPL.

Parameters:
vectors(target, *, start, stop, step='1 d', center='500@10', cache_path=None, refresh=False)[source]#

Retrieve geometric vectors; default center is the Sun’s center.

Dates are YYYY-MM-DD in TDB, with both endpoints requested. The provider may omit the final instant if the step does not land on it. Negative spacecraft IDs (e.g. '-61' for Juno) avoid ambiguous name matches.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.research.NtrsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA Technical Reports Server: public metadata and available documents.

No account is needed. A search hit can be metadata-only. Preserve each record’s copyright/distribution fields; public access is not a blanket license to redistribute every paper. Design goals in papers are not flight performance measurements.

Parameters:
search(query, *, offset=0, page_size=25, cache_path=None, refresh=False)[source]#

Search one page; offset is the zero-based record offset.

Parameters:
Return type:

ResearchResponse

citation(citation_id, *, cache_path=None, refresh=False)[source]#

Get metadata, original download links and access/copyright details.

Parameters:
Return type:

ResearchResponse

download_document(citation_id, filename, destination, *, max_bytes=100000000)[source]#

Download an explicitly selected, publicly available original file.

Parameters:
Return type:

DownloadReceipt

class space_pv_connectors.research.PdsConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA PDS Search API: mission product metadata, labels and data links.

Archive coverage is incomplete. Retain labels to interpret product units and calibration; a search hit is not necessarily a power measurement.

Parameters:
search(query, *, limit=25, sort=None, search_after=None, cache_path=None, refresh=False)[source]#

Search using PDS q expressions; cursor pagination requires sort.

Example: '(product_class eq "Product_Bundle")'. Use provider field names and operators, not SQL. The documented keywords parameter is not exposed: it was silently ignored by the live service in the access check.

Parameters:
  • query (str)

  • limit (int)

  • sort (str | None)

  • search_after (str | None)

  • cache_path (str | Path | None)

  • refresh (bool)

Return type:

ResearchResponse

product(identifier, *, cache_path=None, refresh=False)[source]#

Resolve a PDS LID or versioned LIDVID to its product metadata.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.research.PsaConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

ESA Planetary Science Archive TAP/EPN-TAP read-only ADQL queries.

JSON responses retain column names, units, types and data access links. max_records bounds a response; reaching it may indicate truncation. The service does not provide universal spacecraft EPS telemetry.

Parameters:
query(adql, *, max_records=100, cache_path=None, refresh=False)[source]#

Run a SELECT ADQL query; results are bounded, not a complete archive.

Parameters:
Return type:

ResearchResponse

class space_pv_connectors.research.ZenodoConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Discover published research datasets and download open files anonymously.

Restricted files remain restricted. Each record supplies its own license; no deposit, publication or authenticated write endpoints are used.

Parameters:
search(query, *, page=1, page_size=25, cache_path=None, refresh=False)[source]#

Search one page using Zenodo query syntax (anonymous maximum: 25).

Parameters:
Return type:

ResearchResponse

record(record_id, *, cache_path=None, refresh=False)[source]#

Read a specific record/version, including DOI, license and file checksums.

Parameters:
Return type:

ResearchResponse

download_file(record_id, filename, destination, *, max_bytes=100000000)[source]#

Select a public file by exact name and verify its provider checksum.

Parameters:
Return type:

DownloadReceipt

Provenance and bounded downloads shared by the research API connectors.

class space_pv_connectors.research_http.ResearchResponse(data, receipt, request_url, documentation)[source]#

Provider metadata and the receipt for its original response bytes.

request_url includes non-secret query parameters; authentication headers are never serialized. JSON connectors retain provider units, licenses, pagination, versions and uncertainty fields. The arXiv connector documents its Atom-to-metadata normalization and can cache original XML bytes. Neither representation is a validated engineering or PV specification.

Parameters:

Tabular utilities#

GP snapshot cache#

Persistent GP snapshots with a cross-process download lock and circuit breaker.

class space_pv_connectors.gp_cache.GPSnapshot(records: 'list[dict[str, Any]]', source: 'str', retrieved_at: 'datetime', sha256: 'str', cache_stale: 'bool' = False, warning: 'str | None' = None)[source]#
Parameters:
exception space_pv_connectors.gp_cache.GPUnavailableError[source]#

No usable snapshot is available; callers must not substitute demo data.

class space_pv_connectors.gp_cache.GPCache(path)[source]#

Cache provider queries for at least two hours, including across restarts.

SQLite serializes downloads from processes sharing this local file. Any HTTP or malformed-response error pauses the entire provider until an operator calls resume(). Existing snapshots remain available with an explicit warning; the orbit layer separately rejects old element epochs.

Share one cache per deployment, on a local filesystem. Multiple hosts need a single ingestion service, not independent caches behind the same IP.

Parameters:

path (str | Path)

resume(source)[source]#

Resume downloads after a human investigates a provider failure.

Parameters:

source (str)

Return type:

None

N2YO positions#

Optional server-side N2YO calculated-position connector.

class space_pv_connectors.n2yo.N2YOConnector(*, api_key=None, timeout_s=30)[source]#

N2YO REST v1. Keep API keys on the server, outside browser bundles.

Positions are provider predictions, not satellite GPS telemetry. The free service documents 1,000 position calls/hour and at most 300 samples/call. No retries are made here. Bulk tracking should use cached GP + local SGP4. https://www.n2yo.com/api/

Parameters:
  • api_key (str | None)

  • timeout_s (float)

positions(norad_id, *, observer_lat, observer_lon, observer_alt_m=0, seconds=60)[source]#

Return the provider’s timestamped position JSON, including provenance.

sataltitude in the provider payload is km; observer altitude is m. Element epoch is not supplied by this endpoint and remains unknown.

Parameters:
Return type:

dict[str, Any]

Array procurement inputs#

Load auditable array-trade inputs using the shared tabular connector.

space_pv_connectors.procurement.load_array_offers(path)[source]#

Load CSV/Excel/Parquet offers without converting efficiency or units.

Required numeric columns are array-level BOL W/m², EOL retention, kg/m², and procurement currency/m². Currency and EOL duration must be common and documented externally. Source links establish provenance, not validation. Evidence status is measured, imported, modeled, or synthetic; all nonempty text and extra metadata columns are preserved.

Parameters:

path (str | Path)

Return type:

DataFrame

Version-pinned arXiv literature#

Version-pinned arXiv metadata with original-byte provenance and offline cache.

space_pv_connectors.arxiv.parse_arxiv_atom(content, paper_id)[source]#

Parse one exact-version Atom entry; never silently substitute latest.

Parameters:
Return type:

dict[str, object]

class space_pv_connectors.arxiv.ArxivConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

One explicit paper per request; reuse cache and observe arXiv rate limits.

The original Atom bytes are cached with SHA-256, URL and retrieval time. This connector does not extract or promote scientific claims from PDFs. Downloading an accessible paper does not grant redistribution rights.

Parameters:
paper(paper_id, *, cache_path=None, refresh=False)[source]#

Fetch pinned metadata, or validate and read its existing local cache.

Parameters:
Return type:

ResearchResponse

download_paper(paper_id, destination, *, max_bytes=20000000)[source]#

Download a selected version with a checksum receipt; no bulk crawl.

Parameters:
Return type:

DownloadReceipt