Skip to content

need_timeline

need_timeline #

need_timeline — how much each moment still needs capturing, by the clock.

PEAK_PROMINENCE = 0.1 module-attribute #

How far a peak must rise above its surroundings to be marked.

PEAK_SPACING = timedelta(minutes=20) module-attribute #

The closest two marked peaks may stand.

need_timeline(axes, instants, need, now=None) #

need by clock time, its peaks marked with their time, the moments before now faded.

Times read in the zone the instants carry.

day = cgr.scheduling.forecast.daylight(site, now)
suns = cgr.scheduling.forecast.solar_position(site, day)
guidance.need_timeline(figure.axes, list(day), 1.0 - shadow.coverage(suns, taken), now=now)

Parameters:

Name Type Description Default
axes Axes

The chart to draw on.

required
instants Sequence[datetime]

Evenly spaced aware instants, in order.

required
need ndarray

0–1 at each instant.

required
now datetime | None

The present, when it falls among instants.

None
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/guidance/need_timeline.py
def need_timeline(
    axes: Axes,
    instants: Sequence[datetime],
    need: np.ndarray,
    now: datetime | None = None,
) -> None:
    """``need`` by clock time, its peaks marked with their time, the moments before ``now`` faded.

    Times read in the zone the ``instants`` carry.

    ```python
    day = cgr.scheduling.forecast.daylight(site, now)
    suns = cgr.scheduling.forecast.solar_position(site, day)
    guidance.need_timeline(figure.axes, list(day), 1.0 - shadow.coverage(suns, taken), now=now)
    ```

    Args:
        axes: The chart to draw on.
        instants: Evenly spaced aware instants, in order.
        need: 0–1 at each instant.
        now: The present, when it falls among ``instants``.
    """
    from matplotlib.dates import AutoDateLocator, DateFormatter, date2num

    zone = instants[0].tzinfo
    x = date2num(list(instants))
    axes.fill_between(x, need, color=NEEDED, alpha=0.3, linewidth=0)
    axes.plot(x, need, color=NEEDED, label="Still needed")
    step = instants[1] - instants[0] if len(instants) > 1 else PEAK_SPACING
    peaks, _ = scipy.signal.find_peaks(
        need,
        prominence=PEAK_PROMINENCE,
        distance=max(1, round(PEAK_SPACING / step)),
    )
    for index in peaks:
        axes.annotate(
            instants[index].strftime("%-I:%M %p"),
            (x[index], need[index]),
            xytext=(0, 10),
            textcoords="offset points",
            ha="center",
            fontsize=14,
        )
    if now is not None and instants[0] < now < instants[-1]:
        moment = float(date2num(now))
        axes.axvspan(x[0], moment, color="white", alpha=0.6, zorder=4, linewidth=0)
        axes.axvline(moment, color=INK, linewidth=2, zorder=5, label="Now")
    axes.set_xlim(x[0], x[-1])
    axes.set_ylim(0.0, 1.15)
    axes.set_yticks([0.0, 1.0], ["Covered", "Needed"])
    axes.xaxis.set_major_locator(AutoDateLocator(tz=zone, maxticks=8))
    axes.xaxis.set_major_formatter(DateFormatter("%-I %p", tz=zone))