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.

• BufferError – 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: AbstractEvent

Single time event object.

property start: datetime64

Event start time.

property stop: 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: AbstractEvent

Window time event object.

property start: datetime64

Event start time.

property stop: 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: AbstractEventsCollection, 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: AbstractEventsCollection, 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: 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).

• versionadded: (..) – 1.2.0: CSV reader now support uncommented header.

property csv

Formatted CSV content.

EvfEventsFile

class planetary_coverage.events.EvfEventsFile(fname)

Bases: 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: 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: 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: UserDict

Single time event object.

property start: datetime64

Event start time.

property stop: 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: datetime64

Global events start time.

property stop: 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: 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.