Coverage – ephemerista.analysis.coverage

The coverage.py module.

This module provides the Coverage class for conducting coverage analyses.

pydantic model ephemerista.analysis.coverage.Coverage

Coverage analysis.

Notes

The coverage is computed by computing all passes of the spacecraft over all ground locations of the exterior of each polygon, i.e. the visibility from the min elevation defined in the polygon’s properties.

Doing that for all ground locations of the exterior of each polygon is computationally intensive, but that allows to do an average of the coverage on the polygon. Besides, when the GroundLocations are created in scenarios.py, shared locations between adjacent polygons are merged to avoid duplicate computations.

For instance for a polygon’s exterior composed of 4 points, if two points have spacecraft visibility for a total duration of 340 seconds, and the two other points for 360 seconds, then the average visibility duration of this polygon will be 350 seconds.

Fields:
field end_time: Time | None = None (alias 'endTime')

End time (optional, if None the scenario’s end time is used)

field scenario: Scenario [Required]

The scenario used to analyze the coverage

field start_time: Time | None = None (alias 'startTime')

Start time (optional, if None the scenario’s start time is used)

analyze(ensemble=None, visibility=None)

Run the coverage analysis.

Return type:

CoverageResults

pydantic model ephemerista.analysis.coverage.CoverageResults

Results of coverage analysis aggregated to areas of interest.

This class provides coverage statistics aggregated back to the user’s areas of interest rather than the discretized polygons used for computation. It also optionally includes the discretized polygon data for detailed heatmap visualization.

Fields:
field areas: list[Feature[Polygon, dict]] [Required]
field avg_time_gaps: list[float] [Required] (alias 'avgTimeGaps')
field coverage_percent: list[float] [Required] (alias 'coveragePercent')
field discretized_coverage_percent: list[float] | None = None (alias 'discretizedCoveragePercent')
field discretized_max_time_gaps: list[float] | None = None (alias 'discretizedMaxTimeGaps')
field discretized_polygons: list[Feature[Polygon, dict]] | None = None (alias 'discretizedPolygons')
field max_time_gaps: list[float] [Required] (alias 'maxTimeGaps')
field min_time_gaps: list[float] [Required] (alias 'minTimeGaps')
field num_discretized_polygons: list[int] [Required] (alias 'numDiscretizedPolygons')
field results_type: str = 'coverage' (alias 'type')
classmethod from_coverage_results(coverage_results, scenario)

Create CoverageResults from discretized coverage results.

Parameters:

  • coverage_results (_DiscretizedCoverageResults) – The detailed coverage results from discretized polygons

  • scenario (Scenario) – The scenario containing area mapping information

Returns:

Aggregated results for areas

Return type:

CoverageResults

plot(data_to_plot='coverage_percent', mapbox_style='open-street-map', zoom=0, opacity=0.7, **kwargs)

Plot the coverage results using Plotly.

Return type:

Figure

plot_mpl(*, data_to_plot='coverage_percent', plot_land=True, land_color='lightgray', land_edgecolor='black', land_alpha=0.5, area_indices=None, alpha=0.7, **kwargs)

Plot the area coverage results using Matplotlib.

Parameters:

  • data_to_plot (str) – The column name to plot from the coverage results

  • plot_land (bool) – Whether to plot land masses as a background layer

  • land_color (str) – Fill color for land masses

  • land_edgecolor (str) – Edge color for land masses

  • land_alpha (float) – Transparency of land masses (0-1)

  • area_indices (list[int] | None) – Indices of specific areas to plot. If None, plot all areas.

  • alpha (float) – Transparency of coverage data (0-1). Default 0.7 to allow land outlines to show through.

  • **kwargs – Additional keyword arguments passed to GeoDataFrame.plot()

Returns:

The matplotlib axes object

Return type:

Axes

plot_plotly(data_to_plot='coverage_percent', mapbox_style='open-street-map', zoom=2, opacity=0.7, polygon_indices=None, **kwargs)

Plot the coverage results using Plotly.

Return type:

Figure

to_dataframe()

Convert coverage results to a pandas DataFrame.

Returns:

DataFrame with columns for area information and coverage statistics. Each row represents one area of interest.

Return type:

pd.DataFrame

to_geodataframe(*, use_discretized=False)

Convert to a GeoDataFrame for visualization.

Parameters:

use_discretized (bool) – If True and discretized data is available, return discretized polygons instead of aggregated areas for heatmap visualization.

Return type:

GeoDataFrame

property polygons: list[Feature[Polygon, dict]]

Alias for areas to maintain compatibility.

property revisit_times: list[list]

Alias to maintain compatibility with tests. Returns empty lists for each area.

ephemerista.analysis.coverage.load_geojson_multipolygon(filename, *, min_elevation_deg=0.0)

Load polygons from a GeoJSON file.

Parameters:

min_elevation_deg (float) – Minimum elevation in degrees to compute the visibility between a spacecraft and the ground locations

Return type:

list[Feature[Polygon, dict]]