Skip to content

Visualization

After retrieving, preprocessing, and aggregating your Nighttime Light (NTL) data, the next logical step is to visualize the results to identify patterns, disruptions, or longitudinal trends.

The blackmarble_toolkit includes a convenient visualization module designed specifically for the output of the aggregation step.

Plotting Aggregated Timeseries

The easiest way to plot your results is to use the .plot() method directly on your NTLPipeline object after running .aggregate().

import matplotlib.pyplot as plt

# Assuming you have already run aggregate() on your pipeline:
# aggregated_results = pipeline.aggregate(gdf=regions)

fig = pipeline.plot(
    variable="ntl",
    indexers={"geonameid": "Region_A"}, # (1)!
    moving_average=7,  # (2)!  
    title="NTL Radiance Over Time"
)

plt.show()
  1. Provide specific indexers to reduce down to a single 1D timeseries. You can select regions (e.g. {"geonameid": "Region_A"}) or even exact pixels (e.g. {"x": 10.5, "y": 20.1}).
  2. Optional: apply a 7-day moving average

When called this way, the toolkit will automatically stack each processing step (e.g., raw, cloud-filtered, gap-filled) into its own subplot, allowing you to directly compare how the radiance signal changes at each step of your pipeline.

Standalone Visualization

If you have a list of aggregated xarray.Dataset objects that weren't generated by the pipeline, or if you simply prefer using standalone functions, you can import the plotting function directly:

from blackmarble_toolkit.visualization import plot_multiple_timeseries

fig = plot_multiple_timeseries(
    datasets=aggregated_results,
    variable="ntl",
    moving_average=14,
    start_date="2022-01-01",
    end_date="2022-06-01"
)

For full details on the available parameters (like defining custom subplot titles, adjusting font scaling, or forcing Y-axis bounds), check out the Visualization API Reference.