Events API

read_events

planetary_coverage.read_events(fname, **kwargs)

Read events file.

Parameters

• fname (str or pathlib.Path) – File name to parse

• **kwargs – Parsing properties.

Returns

Parsed events list from the provided file.

Return type

CsvEventFile, EvfEventFile, ItlEventFile or OrbitEventsFile

Raises

• FileNotFoundError – If the filename provided does not exist.

• IOError – When it’s not possible to parse the provided file.

Note

The function will try to guess the layout of the file based on the filename extension.

See also

planetary_coverage.events.CsvEventsFile, planetary_coverage.events.EvfEventsFile, planetary_coverage.events.ItlEventsFile, planetary_coverage.events.OrbitEventsFile

Event

class planetary_coverage.events.Event(key, *args, **kwargs)

Bases: planetary_coverage.events.event.AbstractEvent

Single time event object.

property start: numpy.datetime64

Event start time.

property stop: numpy.datetime64

Event stop time (same as start time).

trim(*, before=None, after=None, by_event=None)

Discard the event if outside the time boundaries.

Parameters

• before (str, datetime.datetime or numpy.datetime64) – Start time window to consider.

• after (str, datetime.datetime or numpy.datetime64) – Stop time window to consider.

• by_event (AbstractEvent or AbstractEventsCollection) – Event(s) that can be used as an time window range.

Returns

• Event – Same event if the event is inside the time window considered.

• None – If the event is outside the time window considered.

EventWindow

class planetary_coverage.events.EventWindow(key, *args, **kwargs)

Bases: planetary_coverage.events.event.AbstractEvent

Window time event object.

property start: numpy.datetime64

Event start time.

property stop: numpy.datetime64

Event stop time.

trim(*, before=None, after=None, by_event=None)

Trim the event with time boundaries.

Parameters

• before (str, datetime.datetime or numpy.datetime64) – Start time window to consider.

• after (str, datetime.datetime or numpy.datetime64) – Stop time window to consider.

• by_event (AbstractEvent or AbstractEventsCollection) – Event(s) that can be used as an time window range.

Returns

• EventWindow – Same event if the event is inside the time window considered.

• EventWindow – A trimmed event if the event cross one or both boundaries.

• None – If the event is outside the time window considered.

EventsDict

class planetary_coverage.events.EventsDict(events, **kwargs)

Bases: planetary_coverage.events.event.AbstractEventsCollection, collections.UserDict

List of events items with different keys.

Warning

The iteration is performed on the values and not the dict keys.

keys()

Dictionary keys.

get_by_slice(key) → list

Get events by slice.

get_by_int(key: int)

Get event by int.

append(event)

Append a new event to the dict.

find(*regex, as_dict=False)

Find the events matching a regex expression.

Parameters

• *regex (str) – Search regex expression key(s).

• as_dict (bool, optional) – When a match exists returns the results as an EventsDict.

Returns

Event(s) matching the provided regex expression(s).

Return type

Event, EventWindow, EventsList or EventsDict

Raises

KeyError – If none of the provided key was found.

Note

When multiple keys are provided, the duplicates will be discarded.

startswith(*keys, as_dict=False)

Find the events starting with a given key

Parameters

• *keys (str) – Search expression key(s).

• as_dict (bool, optional) – When a match exists returns the results as an EventsDict.

See also

find

endswith(*keys, as_dict=False)

Find the events ending with a given key

Parameters

• *keys (str) – Search expression key(s).

• as_dict (bool, optional) – When a match exists returns the results as an EventsDict.

See also

find

trim(*, before=None, after=None, by_event=None)

Trim the events dict within time boundaries.

Parameters

• before (str, datetime.datetime or numpy.datetime64) – Start time window to consider.

• after (str, datetime.datetime or numpy.datetime64) – Stop time window to consider.

• by_event (AbstractEvent or AbstractEventsCollection) – Event(s) that can be used as an time window range.

Returns

• EventsDict – Same events if the event is inside the time window considered.

• EventsDict – Trimmed events if the event cross one or both boundaries.

• None – The events is outside the time window considered.

EventsList

class planetary_coverage.events.EventsList(initlist=None)

Bases: planetary_coverage.events.event.AbstractEventsCollection, collections.UserList

List of events with the same key.

property key

Events key.

property crema_names: list

Crema names when present in contextual info field.

property obs_names: list

Observation names when present in contextual info field.

trim(*, before=None, after=None, by_event=None)

Trim the events list within time boundaries.

Parameters

• before (str, datetime.datetime or numpy.datetime64) – Start time window to consider.

• after (str, datetime.datetime or numpy.datetime64) – Stop time window to consider.

• by_event (AbstractEvent or AbstractEventsCollection) – Event(s) that can be used as an time window range.

Returns

• EventsList – Same events if the event is inside the time window considered.

• EventsList – Trimmed events if the event cross one or both boundaries.

• None – The events is outside the time window considered.

CsvEventsFile

class planetary_coverage.events.CsvEventsFile(fname, primary_key='name', header=None)

Bases: planetary_coverage.events.event.AbstractEventsFile

CSV events file object.

Parameters

• fname (str or pathlib.Path) – Input CSV event filename.

• primary_key (str, optional) – Header primary key (default: name)

• header (str, optional) – Optional header definition (to be appended at the beginning of the file).

property csv

Formatted CSV content.

EvfEventsFile

class planetary_coverage.events.EvfEventsFile(fname)

Bases: planetary_coverage.events.event.AbstractEventsFile

EVF event file object.

EVF are in MAPPS format.

Parameters

fname (str or pathlib.Path) – EVF filename to parse.

ItlEventsFile

class planetary_coverage.events.ItlEventsFile(fname, evf=None)

Bases: planetary_coverage.events.event.AbstractEventsFile

ITL event file object.

Instrument timeline.

Parameters

• fname (str or pathlib.Path) – ITL filename to parse.

• evf (str or pathlib.Path) – Supporting EVF events file (for relative timelines).

datetime(time)

Absolute datetime for an event.

property observations

List of observation windows.

OrbitEventsFile

class planetary_coverage.events.OrbitEventsFile(fname)

Bases: planetary_coverage.events.event.AbstractEventsFile

Orbit event file object.

Parameters

fname (str or pathlib.Path) – ORB filename to parse.

AbstractEvent

class planetary_coverage.events.event.AbstractEvent(key, *args, **kwargs)

Bases: collections.UserDict

Single time event object.

property start: numpy.datetime64

Event start time.

property stop: numpy.datetime64

Event stop time.

property start_date

Event start date.

property stop_date

Event stop date.

contains(pts)

Check if points are inside the temporal windows.

Parameters

pts (numpy.ndarray) – List of temporal UTC point(s): utc or [utc_0, …]. If an object with utc attribute/property is provided, the intersection will be performed on these points.

Returns

Return True if the point is inside the pixel corners, and False overwise.

Return type

numpy.ndarray

Note

If the point is on the edge of the window it will be included.

trim(*, before=None, after=None, by_event=None)

Trim the event with time boundaries.

Parameters

• before (str, datetime.datetime or numpy.datetime64) – Start time window to consider.

• after (str, datetime.datetime or numpy.datetime64) – Stop time window to consider.

• by_event (AbstractEvent or AbstractEventsCollection) – Event(s) that can be used as an time window range.

Returns

• AbstractEvent – Same event if the event is inside the time window considered.

• AbstractEvent – A trimmed event if the event cross one or both boundaries.

• None – If the event is outside the time window considered.

AbstractEventsCollection

class planetary_coverage.events.event.AbstractEventsCollection

Bases: object

Abstract collection of events.

property starts: list

Event start times.

property stops: list

Event stop times.

property windows: list

Event windows.

property start: numpy.datetime64

Global events start time.

property stop: numpy.datetime64

Global events stop time.

property start_date

global events start date.

property stop_date

Global events stop date.

contains(pts)

Check if points are inside any temporal window.

Parameters

pts (numpy.ndarray) – List of temporal UTC point(s): utc or [utc_0, …]. If an object with utc attribute/property is provided, the intersection will be performed on these points.

Returns

Return True if the point is inside the pixel corners, and False overwise.

Return type

numpy.ndarray

Note

If the point is on the edge of the window it will be included.

before(date_stop, strict=False, as_dict=False)

Select all the events before the given date.

after(date_start, strict=False, as_dict=False)

Select all the events after the given date.

between(date_start, date_stop, strict=False, as_dict=False)

Select all the events between the given dates.

Danger

The parenthesis in the comparison are mandatory here. Comparison operator chains (a < b < c) will break due to short-circuit chain evaluation (a < b and b < c) where only a < b if the result is not False and b < c otherwise, not the intersection ((a < b) & (b < c)).

trim(*, before=None, after=None, by_event=None)

Trim the events within time boundaries.

Parameters

• before (str, datetime.datetime or numpy.datetime64) – Start time window to consider.

• after (str, datetime.datetime or numpy.datetime64) – Stop time window to consider.

• by_event (AbstractEvent or AbstractEventsCollection) – Event(s) that can be used as an time window range.

Returns

• AbstractEventsCollection – Same events if the event is inside the time window considered.

• AbstractEventsCollection – Trimmed events if the event cross one or both boundaries.

• None – The events is outside the time window considered.

AbstractEventsFile

class planetary_coverage.events.event.AbstractEventsFile(fname, primary_key, header=None)

Bases: planetary_coverage.events.event.EventsDict

Abstract Events File object.

Parameters

• fname (str or pathlib.Path) – Input event filename.

• primary_key (str, optional) – Header primary key (default: name)

• header (str, optional) – Optional header definition (to be appended at the beginning of the file).

property fname

Events filename.

timedelta()

planetary_coverage.events.timedelta(step)

Parse step as numpy.timedelta64 object.

The value must be a int followed by an optional space and a valid unit.

Examples of valid units:

• ms, msec, millisecond

• s, sec, second

• m, min, minute

• h, hour

• D, day

• M, month

• Y, year

Parameters

step (str) – Step to parse.

Returns

Parsed numpy.timedelta64 step.

Return type

numpy.timedelta64

Raises

ValueError – If the provided step format or unit is invalid.