Coverage – ephemerista.analysis.coverage

The coverage.py module.

This module provides the Coverage class for conducting coverage analyses.

class ephemerista.analysis.coverage.Coverage(*, scenario, startTime=None, endTime=None)

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.

analyze(ensemble=None, visibility=None)

Run the coverage analysis.

Return type:

CoverageResults

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ephemerista.analysis.coverage.CoverageResults(*, type='coverage', areas, coveragePercent, maxTimeGaps, scenario=None, ensemble=None, minTimeGaps, avgTimeGaps, numDiscretizedPolygons, discretizedPolygons=None, discretizedCoveragePercent=None, discretizedMaxTimeGaps=None)

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.

classmethod from_coverage_results(coverage_results, scenario, ensemble=None)

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

  • ensemble (Ensemble | None) – Optional ensemble for plotting ground tracks

Returns:

Aggregated results for areas

Return type:

CoverageResults

model_config: ClassVar[ConfigDict] = {'alias_generator': <function to_camel>, 'populate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

plot(data_to_plot='coverage_percent', map_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, plot_ground_tracks=False, **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', map_style='open-street-map', zoom=2, opacity=0.7, polygon_indices=None, plot_ground_tracks=False, **kwargs)

Plot the coverage results using Plotly.

Return type:

Figure

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.

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:

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

ephemerista.analysis.coverage.PolygonFeatureCollection

alias of FeatureCollection[Feature[Polygon, dict]]

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]]