ESA events files#

Recently the ESA-SOC published a collection of event files that contains the different phases of the mission, the dates and names of the flybys; as well as some technical information, e.g. the visibility of the DSN stations and the expected downlinks windows.

Caution

These files need to be considered as experimental and their format and location can evolve significantly in the future. Currently they are only provided for the Juice mission (CREMA 3.0, 5.0 and 5.0b23.1) on the SOC core system toolkit.

New in version 1.1.0: Some of the mission are now translated into fk event kernels that can be loaded with the Juice metakernels. See TourConfig for more details.

Event file format#

An event file is a text file (.csv/.evf/.itl/.orb) containing either a single time event, a start or stop time event or an event with both a start and a stop time.

For example, the mission phases file is defined like this:

Hint

All the events have a t_start and a t_end time and the primary key is stored in the Name column.

You can add comments and blank lines in the the csv file, as long as you keep the column header in the first line (or explicitly mention it in read_events(), see below).

column_0	name	t_start	t_end
Jupiter_Phase_1	Approach and first ellipse	2031-01-19T19:14:21	2032-02-08T23:05:31
Jupiter_Phase_2	Energy reduction	2032-02-08T23:05:32	2032-06-25T12:23:23
Jupiter_Phase_3	Europa flybys	2032-06-25T12:23:23	2032-07-24T07:02:19
Jupiter_Phase_4	High-latitude	2032-07-24T07:02:19	2033-08-18T09:43:28
Jupiter_Phase_5	Low energy	2033-08-18T09:43:28	2034-12-19T00:00:00
Jupiter_Phase_all	All Jupiter phases	2031-01-19T19:14:21	2034-12-19T00:00:00
Ganymede_Phase_6_1	GEOa	2034-12-19T00:00:00	2035-01-17T03:00:00
Ganymede_Phase_6_2	GCO5000	2035-01-17T03:00:00	2035-04-16T16:00:00
Ganymede_Phase_6_3	GEOb	2035-04-16T16:00:00	2035-05-13T02:00:00
Ganymede_Phase_6_4	TGCO	2035-05-13T02:00:00	2035-05-21T15:00:00
Ganymede_Phase_6_5	GCO500	2035-05-21T15:00:00	2035-09-29T00:00:00
Ganymede_Phase_all	All Ganymede phases	2034-12-19T00:00:00	2035-09-29T00:00:00
Mission_phase_all	All mission phases	2031-01-19T19:14:21	2035-09-29T00:00:00

In some cases, the events are only defined as single event time:

Note

The primary key (Event name) does not need to be unique and will be grouped together.

Here, the XXX_START and XXX_END events will be paired.

If a pair is incomplete, a warning message will be send to the user at runtime.

event name	event time [utc]	contextual info
VISIBILITY_MALARGUE_START	2031-01-20T08:03:38Z
DOWNLINK_MALARGUE_START	2031-01-20T08:03:38Z
VISIBILITY_GOLDSTONE_START	2031-01-20T13:39:08Z
VISIBILITY_GOLDSTONE_END	2031-01-20T21:19:41Z
IO_TRANSIT_START	2031-01-20T08:44:31Z
IO_TRANSIT_END	2031-01-20T10:55:41Z
DOWNLINK_MALARGUE_END	2031-01-20T17:03:41Z
VISIBILITY_MALARGUE_END	2031-01-20T20:36:11Z
DOWNLINK_MALARGUE_START	2031-01-21T08:00:40Z
VISIBILITY_MALARGUE_START	2031-01-21T08:00:40Z
GANYMEDE_TRANSIT_START	2031-01-21T10:50:31Z
GANYMEDE_TRANSIT_END	2031-01-21T11:58:21Z
DOWNLINK_MALARGUE_END	2031-01-21T17:00:41Z
VISIBILITY_MALARGUE_END	2031-01-21T20:32:41Z
FLYBY_GANYMEDE	2031-07-21T07:14:23Z	Crema name= 1G1;Time= 21-JUL-2031_07:14:23;Altitude above ganymede [km]= 400.00697;Sub-SC lon [deg]= 238.5;Sub-SC lat [deg]= 2.2;Sub-SC phase [deg]= 84.7;Sub-SC loctime [hours]= 17.6;Jup-Moon-Sc angle [deg]= 119.2;Flight direction= -1Y;Moon true anomalie= 109.1;Ground track velocity [km/s]= 7.1;Velocity wrt sub-sc point radial component [km/s]= 0.0;Velocity wrt sub-sc point tangential component [km/s]= 7.1;Energy generated over +-12h around CA [Wh]= 22369.7;Energy generated over +-1h around CA [Wh]= 879.4;Energy for science over +-12h around CA [Wh]= 8302.5;Energy for science over +-1h around CA [Wh]= -252.5;Relative energy amount for science compared to 6E1 +-12 h= 0.945;Relative energy amount for science compared to 6E1 +-1 h= 0.965;Optimum solar array orientation during pushbroom [deg]= -86.0;PEP-NIM FOV obstruction for optimum solar array [percent]= 0.0;Energy for science over +-1h around CA [Wh] with zero NIM obstruction [Wh]= -1129.4;Maximum sc2sun direction angle to YZ plane during pushbroom= 9.7;Malargue visibility= YES;Cebreros visibility= NO;Delta-time to closest perijove [h]= 13.60
PERIJOVE_1PJ	2031-07-21T20:50:23Z	Distance to Jupiter [RJ]= 12.30;Sub-SC lon [deg]= 337.7;Sub-SC lat [deg]= 2.4;Sub-SC phase [deg]= 72.7;Sub-SC loctime [hours]= 16.8;Jupiter angular size [deg]= 9.3;Energy generated over +-50h around CA [Wh]= 97198.3;Energy for science over +-50h around CA [Wh]= 37198.3;Relative generated energy amount for science compared to PJ2= 0.975;Malargue visibility= YES;Delta-time to closest moon Flyby= 13.60 hours after the flyby 1G1
FLYBY_GANYMEDE	2032-02-13T23:04:51Z	Crema name= 2G2;Time= 13-FEB-2032_23:04:51;Altitude above ganymede [km]= 400.04581;Sub-SC lon [deg]= 234.1;Sub-SC lat [deg]= 25.2;Sub-SC phase [deg]= 74.6;Sub-SC loctime [hours]= 16.8;Jup-Moon-Sc angle [deg]= 120.2;Flight direction= 1Y;Moon true anomalie= 115.9;Ground track velocity [km/s]= 5.5;Velocity wrt sub-sc point radial component [km/s]= -0.0;Velocity wrt sub-sc point tangential component [km/s]= 5.5;Energy generated over +-12h around CA [Wh]= 22990.1;Energy generated over +-1h around CA [Wh]= 911.4;Energy for science over +-12h around CA [Wh]= 8923.0;Energy for science over +-1h around CA [Wh]= -220.6;Relative energy amount for science compared to 6E1 +-12 h= 1.016;Relative energy amount for science compared to 6E1 +-1 h= 0.843;Optimum solar array orientation during pushbroom [deg]= -89.0;PEP-NIM FOV obstruction for optimum solar array [percent]= 0.0;Energy for science over +-1h around CA [Wh] with zero NIM obstruction [Wh]= -1130.4;Maximum sc2sun direction angle to YZ plane during pushbroom= 19.2;Malargue visibility= NO;Cebreros visibility= NO;Delta-time to closest perijove [h]= 15.26

When no explicit header is provided in the file. By default we will assume that when it’s the case, the default header should be:

Tip

As you can see below, any custom header can be provided.

name	t_start	t_end	working_group
DL_	2031-01-20T08:03:38Z	2031-01-20T17:03:41Z	GENERIC
DL_	2031-01-21T08:00:40Z	2031-01-21T17:00:41Z	GENERIC
DL_	2031-01-22T07:57:12Z	2031-01-22T16:57:11Z	GENERIC
DL_	2031-01-23T07:54:14Z	2031-01-23T16:54:11Z	GENERIC
DL_	2031-01-24T07:50:46Z	2031-01-24T16:50:51Z	GENERIC
DL_	2031-01-25T07:47:48Z	2031-01-25T16:47:51Z	GENERIC
DL_	2031-01-26T07:44:20Z	2031-01-26T16:44:21Z	GENERIC
DL_	2031-01-27T07:41:22Z	2031-01-27T16:41:21Z	GENERIC
DL_	2031-01-28T07:38:24Z	2031-01-28T16:38:21Z	GENERIC
DL_	2031-01-29T07:34:56Z	2031-01-29T16:35:01Z	GENERIC

MAPPS event file (.evf) are also supported and should follow this pattern:

Note

.evf and .itl files are not currently distributed publicly by the Juice project.

# Example of EVF file for the planetary-coverage documentation
22-JAN-2031_18:54:03    CA_EUROPA      (COUNT =  1)
26-JAN-2031_08:08:00    CA_EUROPA      (COUNT =  2)
29-JAN-2031_21:21:56    CA_EUROPA      (COUNT =  3)

As well as instrument timeline file (.itl):

#-------------------------------------------------------------
# Example of ITL file for the planetary-coverage documentation
#-------------------------------------------------------------

# Timeline version
Version: 1

# Block comment with absolute timing
2032-07-02T04:18:40Z  UVS   OBS_START UVS_SAT_STELL_OCC_A (PRIME=TRUE)
2032-07-02T04:32:00Z  UVS   OBS_END   UVS_SAT_STELL_OCC_A

#==========
# Multi-lines comment block with EVF relative timing (related to `CA_EUROPA.EVF`):
#   29-JAN-2031_21:21:56    CA_EUROPA      (COUNT =  3)
#skip this line (no leading space or tab).
CA_EUROPA (COUNT = 3)  -00:27:00  MAJIS 	OBS_START 		MAJIS_FLYBY_HR_01_001 (PRIME=TRUE)
CA_EUROPA (COUNT = 3)  -00:25:06  MAJIS 	OBS_END 		MAJIS_FLYBY_HR_01_001

# Switch mode absolute block
2031-02-06T00:16:25Z	MAJIS * SWITCH_MODE  	(CURRENT_MODE=SERVICE3 [ENG])

# Switch mode relative block
CA_EUROPA (COUNT = 3)  +04:36:55	MAJIS * SWITCH_MODE  	(CURRENT_MODE=OFF [ENG])

For many space mission, the space agency can provide orbit numbers file (.orb) files than can be used as events files. Usually they are stored in a misc/orbnum/ folder as ancillary kernels files (eg. Juice, Bepi, Cassini…)

 No.     Event UTC PERI       Event SCLK PERI       Orbit Start           Orbit End            SolLon   SolLat   SC Lon   SC Lat      Alt       Inc     Ecc    LonNode  Arg Per    Sol Dist     Semi Axis
=====  ====================  ====================  ====================  ====================  =======  =======  =======  =======  ==========  =======  ======  =======  =======  ============  ===========
2031 JUL 21 20:46:34    1/0288391662.57647  N/A                   2031 NOV 02 02:33:58   267.56    -2.11   340.06     2.42   806508.68    24.48   1.101     6.09   153.67   788073210.9  -8734123.78
2032 FEB 14 14:19:45    1/0306339653.54137  2031 NOV 02 02:33:58  2032 MAR 14 05:22:01   166.97    -1.51   231.43     1.78   841072.16    24.42   0.788     3.52   164.99   776960863.8   4313415.24
2032 APR 11 22:47:53    1/0311294942.33451  2032 MAR 14 05:22:01  2032 APR 26 06:02:38   284.02    -1.31   354.61     0.29   778902.56    25.52   0.687   358.81   180.15   773845024.9   2712784.67
2032 MAY 10 14:44:53    1/0313771562.20434  2032 APR 26 06:02:38  2032 MAY 21 20:13:05   172.88    -1.21   246.50    -0.01   747123.86    25.70   0.644   358.07   186.26   772293776.2   2298334.65
2032 JUN 02 01:35:53    1/0315711422.21023  2032 MAY 21 20:13:05  2032 JUN 10 04:29:47    69.43    -1.13   141.13    -0.01   746701.29    25.70   0.644   358.07   186.24   771083464.1   2298210.38

Parsing an events file#

We recommend to use the generic read_events() function that can parse all ESA events files listed above:

from planetary_coverage import read_events

phases = read_events('Mission_Phases.csv')
timeline = read_events('mission_timeline_event_file_5_0b23_1.csv')
malargue = read_events('segmentation_proposal_Jupiter_Phase_all_crema_5_0b23_1_MALARGUE.csv')
evf = read_events('CA_EUROPA.EVF')
itl = read_events('OTL_EUROPA.ITL', evf='CA_EUROPA.EVF')
orbits = read_events('juice.orb')

If you already know the type of file you want to parse, you can also use CsvEventsFile/EvfEventsFile/ItlEventsFile/OrbitEventsFile parsers:

from planetary_coverage.events import CsvEventsFile

CsvEventsFile('Mission_Phases.csv')

	event	#	t_start	t_stop
0	Approach and first ellipse	-	2031-01-19	2032-02-08
1	Energy reduction	-	2032-02-08	2032-06-25
2	Europa flybys	-	2032-06-25	2032-07-24
3	High-latitude	-	2032-07-24	2033-08-18
4	Low energy	-	2033-08-18	2034-12-19
5	All Jupiter phases	-	2031-01-19	2034-12-19
6	GEOa	-	2034-12-19	2035-01-17
7	GCO5000	-	2035-01-17	2035-04-16
8	GEOb	-	2035-04-16	2035-05-13
9	TGCO	-	2035-05-13	2035-05-21
10	GCO500	-	2035-05-21	2035-09-29
11	All Ganymede phases	-	2034-12-19	2035-09-29
12	All mission phases	-	2031-01-19	2035-09-29

from planetary_coverage.events import EvfEventsFile

EvfEventsFile('CA_EUROPA.EVF')

event	#	t_start	t_stop
CA_EUROPA	3	2031-01-22	2031-01-29

Hint

The parameter evf is required only for relative timelines.

from planetary_coverage.events import ItlEventsFile

ItlEventsFile('OTL_EUROPA.ITL', evf='CA_EUROPA.EVF')

event	#	t_start	t_stop
OBS	2	2031-01-29	2032-07-02
SWITCH_MODE	2	2031-01-30	2031-02-06

from planetary_coverage.events import OrbitEventsFile

OrbitEventsFile('juice.orb')

no.	event utc peri	event sclk peri	orbit start	orbit end	sollon	sollat	sc lon	sc lat	alt	inc	ecc	lonnode	arg per	sol dist	semi axis
1	2031 JUL 21 20:46:34	1/0288391662.57647	N/A	2031 NOV 02 02:33:58	267.56	-2.11	340.06	2.42	806508.68	24.48	1.101	6.09	153.67	788073210.9	-8734123.78
2	2032 FEB 14 14:19:45	1/0306339653.54137	2031 NOV 02 02:33:58	2032 MAR 14 05:22:01	166.97	-1.51	231.43	1.78	841072.16	24.42	0.788	3.52	164.99	776960863.8	4313415.24
3	2032 APR 11 22:47:53	1/0311294942.33451	2032 MAR 14 05:22:01	2032 APR 26 06:02:38	284.02	-1.31	354.61	0.29	778902.56	25.52	0.687	358.81	180.15	773845024.9	2712784.67
4	2032 MAY 10 14:44:53	1/0313771562.20434	2032 APR 26 06:02:38	2032 MAY 21 20:13:05	172.88	-1.21	246.50	-0.01	747123.86	25.70	0.644	358.07	186.26	772293776.2	2298334.65
5	2032 JUN 02 01:35:53	1/0315711422.21023	2032 MAY 21 20:13:05	2032 JUN 10 04:29:47	69.43	-1.13	141.13	-0.01	746701.29	25.70	0.644	358.07	186.24	771083464.1	2298210.38

In all cases, when parsed, you get a collection of Event and EventWindow objects:

phases

	event	#	t_start	t_stop
0	Approach and first ellipse	-	2031-01-19	2032-02-08
1	Energy reduction	-	2032-02-08	2032-06-25
2	Europa flybys	-	2032-06-25	2032-07-24
3	High-latitude	-	2032-07-24	2033-08-18
4	Low energy	-	2033-08-18	2034-12-19
5	All Jupiter phases	-	2031-01-19	2034-12-19
6	GEOa	-	2034-12-19	2035-01-17
7	GCO5000	-	2035-01-17	2035-04-16
8	GEOb	-	2035-04-16	2035-05-13
9	TGCO	-	2035-05-13	2035-05-21
10	GCO500	-	2035-05-21	2035-09-29
11	All Ganymede phases	-	2034-12-19	2035-09-29
12	All mission phases	-	2031-01-19	2035-09-29

Get an event by key#

You can select a given event with its name:

Tip

On Jupyter and IPython environment, you can use the <tab> key to auto-complete: events['<tab> to show the available keys.

gco_500 = phases['GCO500']

gco_500

column_0	Ganymede_Phase_6_5
name	GCO500
t_start	2035-05-21T15:00:00
t_end	2035-09-29T00:00:00
column_4

When multiple event with the same name are detected, they will be grouped in an EventsList:

Tip

The search key is not sensitive to the case.

downlinks = timeline['downlink_malargue']

downlinks

	event name	t_start	t_end
0	DOWNLINK_MALARGUE	2031-01-20T08:03:38Z	2031-01-20T17:03:41Z
1	DOWNLINK_MALARGUE	2031-01-21T08:00:40Z	2031-01-21T17:00:41Z

Hint

In the case of the flybys, they contain a special property (.crema_names) that host they canonic name defined by the SOC:

>>> flybys.crema_names
['1G1', '2G2', ...]

flybys = timeline['FLYBY_GANYMEDE']

flybys

	event name	event time [utc]	Crema name	Time	Altitude above ganymede [km]	Sub-SC lon [deg]	Sub-SC lat [deg]	Sub-SC phase [deg]	Sub-SC loctime [hours]	Jup-Moon-Sc angle [deg]	Flight direction	Moon true anomalie	Ground track velocity [km/s]	Velocity wrt sub-sc point radial component [km/s]	Velocity wrt sub-sc point tangential component [km/s]	Energy generated over +-12h around CA [Wh]	Energy generated over +-1h around CA [Wh]	Energy for science over +-12h around CA [Wh]	Energy for science over +-1h around CA [Wh]	Relative energy amount for science compared to 6E1 +-12 h	Relative energy amount for science compared to 6E1 +-1 h	Optimum solar array orientation during pushbroom [deg]	PEP-NIM FOV obstruction for optimum solar array [percent]	Energy for science over +-1h around CA [Wh] with zero NIM obstruction [Wh]	Maximum sc2sun direction angle to YZ plane during pushbroom	Malargue visibility	Cebreros visibility	Delta-time to closest perijove [h]
0	FLYBY_GANYMEDE	2031-07-21T07:14:23Z	1G1	21-JUL-2031_07:14:23	400.00697	238.5	2.2	84.7	17.6	119.2	-1Y	109.1	7.1	0.0	7.1	22369.7	879.4	8302.5	-252.5	0.945	0.965	-86.0	0.0	-1129.4	9.7	YES	NO	13.60
1	FLYBY_GANYMEDE	2032-02-13T23:04:51Z	2G2	13-FEB-2032_23:04:51	400.04581	234.1	25.2	74.6	16.8	120.2	1Y	115.9	5.5	-0.0	5.5	22990.1	911.4	8923.0	-220.6	1.016	0.843	-89.0	0.0	-1130.4	19.2	NO	NO	15.26

Then, you can select a precise flyby if you want with either its name or its id:

Tip

The value in the contextual info column are also parsed as additional attributes (separated with a ;).

flyby_1G1 = flybys['1G1']  # or flybys[0]

flyby_1G1

event name	FLYBY_GANYMEDE
event time [utc]	2031-07-21T07:14:23Z
Crema name	1G1
Time	21-JUL-2031_07:14:23
Altitude above ganymede [km]	400.00697
Sub-SC lon [deg]	238.5
Sub-SC lat [deg]	2.2
Sub-SC phase [deg]	84.7
Sub-SC loctime [hours]	17.6
Jup-Moon-Sc angle [deg]	119.2
Flight direction	-1Y
Moon true anomalie	109.1
Ground track velocity [km/s]	7.1
Velocity wrt sub-sc point radial component [km/s]	0.0
Velocity wrt sub-sc point tangential component [km/s]	7.1
Energy generated over +-12h around CA [Wh]	22369.7
Energy generated over +-1h around CA [Wh]	879.4
Energy for science over +-12h around CA [Wh]	8302.5
Energy for science over +-1h around CA [Wh]	-252.5
Relative energy amount for science compared to 6E1 +-12 h	0.945
Relative energy amount for science compared to 6E1 +-1 h	0.965
Optimum solar array orientation during pushbroom [deg]	-86.0
PEP-NIM FOV obstruction for optimum solar array [percent]	0.0
Energy for science over +-1h around CA [Wh] with zero NIM obstruction [Wh]	-1129.4
Maximum sc2sun direction angle to YZ plane during pushbroom	9.7
Malargue visibility	YES
Cebreros visibility	NO
Delta-time to closest perijove [h]	13.60

Multiple inputs is also supported:

Tip

The events will be sorted by start time and the duplicates will be discarded.

phases['GCO500', 'GCO5000']

	event	#	t_start	t_stop
0	GCO5000	-	2035-01-17	2035-04-16
1	GCO500	-	2035-05-21	2035-09-29

You can also get all the events starting with a given keyword:

Hint

If only one match is found, the events is directly returned. If you need to the results as an EventsDict you can add the argument: as_dict=True.

timeline.startswith('GANYMEDE')

event name	GANYMEDE_TRANSIT
t_start	2031-01-21T10:50:31Z
t_end	2031-01-21T11:58:21Z

or ending with a given keyword:

timeline.endswith('TRANSIT')

	event	#	t_start	t_stop
0	IO_TRANSIT	-	2031-01-20	2031-01-20
1	GANYMEDE_TRANSIT	-	2031-01-21	2031-01-21

as well as complex regular expression:

Note

The find() function is the default function called by __getitem__ in last resort, if none of the key(s) were found.

timeline.find('^VIS.*E$')  # Starting with 'VIS' and ending with a 'E'

	event	#	t_start	t_stop
0	VISIBILITY_MALARGUE	2	2031-01-20	2031-01-21
1	VISIBILITY_GOLDSTONE	-	2031-01-20	2031-01-20

Orbit numbers#

In the case of orbit numbers file (.orb), you can query the orbit number by index, tuple or slice:

orbits[1]  # Tip: negative index are accepted too

no.	1
event utc peri	2031 JUL 21 20:46:34
event sclk peri	1/0288391662.57647
orbit start	N/A
orbit end	2031 NOV 02 02:33:58
sollon	267.56
sollat	-2.11
sc lon	340.06
sc lat	2.42
alt	806508.68
inc	24.48
ecc	1.101
lonnode	6.09
arg per	153.67
sol dist	788073210.9
semi axis	-8734123.78

orbits[2, 4]

	no.	event utc peri	event sclk peri	orbit start	orbit end	sollon	sollat	sc lon	sc lat	alt	inc	ecc	lonnode	arg per	sol dist	semi axis
0	2	2032 FEB 14 14:19:45	1/0306339653.54137	2031 NOV 02 02:33:58	2032 MAR 14 05:22:01	166.97	-1.51	231.43	1.78	841072.16	24.42	0.788	3.52	164.99	776960863.8	4313415.24
1	4	2032 MAY 10 14:44:53	1/0313771562.20434	2032 APR 26 06:02:38	2032 MAY 21 20:13:05	172.88	-1.21	246.50	-0.01	747123.86	25.70	0.644	358.07	186.26	772293776.2	2298334.65

Note

Orbit events are defined as single Event object (usually on apo-apsis or peri-apsis point). If you need a time window for a complete orbit, you need to select the starting orbit and the ending orbit in the slice.

We assume that the 1st column of the file correspond to the event time. If you need an other parameter, you can query it with the name of the column.

>>> orbits[1]['sc lon']
340.06

orbits[1:2]  # Note: the last element is always included

	no.	event utc peri	event sclk peri	orbit start	orbit end	sollon	sollat	sc lon	sc lat	alt	inc	ecc	lonnode	arg per	sol dist	semi axis
0	1	2031 JUL 21 20:46:34	1/0288391662.57647	N/A	2031 NOV 02 02:33:58	267.56	-2.11	340.06	2.42	806508.68	24.48	1.101	6.09	153.67	788073210.9	-8734123.78
1	2	2032 FEB 14 14:19:45	1/0306339653.54137	2031 NOV 02 02:33:58	2032 MAR 14 05:22:01	166.97	-1.51	231.43	1.78	841072.16	24.42	0.788	3.52	164.99	776960863.8	4313415.24

orbits[1:5:2]  # with step interval

	no.	event utc peri	event sclk peri	orbit start	orbit end	sollon	sollat	sc lon	sc lat	alt	inc	ecc	lonnode	arg per	sol dist	semi axis
0	1	2031 JUL 21 20:46:34	1/0288391662.57647	N/A	2031 NOV 02 02:33:58	267.56	-2.11	340.06	2.42	806508.68	24.48	1.101	6.09	153.67	788073210.9	-8734123.78
1	3	2032 APR 11 22:47:53	1/0311294942.33451	2032 MAR 14 05:22:01	2032 APR 26 06:02:38	284.02	-1.31	354.61	0.29	778902.56	25.52	0.687	358.81	180.15	773845024.9	2712784.67
2	5	2032 JUN 02 01:35:53	1/0315711422.21023	2032 MAY 21 20:13:05	2032 JUN 10 04:29:47	69.43	-1.13	141.13	-0.01	746701.29	25.70	0.644	358.07	186.24	771083464.1	2298210.38

Events filtering#

Tip

You can also use the comparison operators <, <=, >, >=. But you should avoid to chain them (see Danger note below).

The CsvEventsFile, EvfEventsFile, ItlEventsFile, OrbitEventsFile, EventsDict and EventsList can be filtered with any date string with a before(), after() and between() functions:

Hint

If only one match is found, the events is directly returned. If you need to the results as an EventsDict you can add the argument: as_dict=True.

phases.before(2033)  # or: `phases <= 2033`

	event	#	t_start	t_stop
0	Approach and first ellipse	-	2031-01-19	2032-02-08
1	Energy reduction	-	2032-02-08	2032-06-25
2	Europa flybys	-	2032-06-25	2032-07-24

phases.after('2034-06-01', strict=True)  # or: `phases > '2034-06-01'`

	event	#	t_start	t_stop
0	GEOa	-	2034-12-19	2035-01-17
1	All Ganymede phases	-	2034-12-19	2035-09-29
2	GCO5000	-	2035-01-17	2035-04-16
3	GEOb	-	2035-04-16	2035-05-13
4	TGCO	-	2035-05-13	2035-05-21
5	GCO500	-	2035-05-21	2035-09-29

Caution

before() / < / <= perform a comparison with the Event start time.
after() / > / >= perform a comparison with the Event stop time.

timeline.between('2031-06', '2032-03')

	event	#	t_start	t_stop
0	FLYBY_GANYMEDE	2	2031-07-21	2032-02-13
1	PERIJOVE_1PJ	-	2031-07-21	2031-07-21

Danger

Unfortunately, it is not possible to chain the operators without explicit parenthesis. You should NOT do:

'2031-06' <= timeline <= '2032-03'

but you should do:

('2031-06' <= timeline) <= '2032-03'

or:

'2031-06' <= (timeline <= '2032-03')

Trim event(s) time boundaries#

If you need to trim the time boundaries of an Event or a collection of Events, you can use the .trim() function. You will get a copy of the event(s) with the same the primary key and properties but with a trimmed start and stop time. The original events are not edited.

Note

The original datetime format is not conserved and you could observed some discrepancies in the datetime string formatting in the output trimmed event. However, the Event start and stop times will always be returned as numpy.datetime64 objects.

downlinks.trim(before='2031-01-20T12:00:00')

	event name	t_start	t_end
0	DOWNLINK_MALARGUE	2031-01-20T12:00:00	2031-01-20T17:03:41Z
1	DOWNLINK_MALARGUE	2031-01-21T08:00:40Z	2031-01-21T17:00:41Z

If an element is outside the new time boundary, it will be discarded:

downlinks.trim(after='2031-01-21')

	event name	t_start	t_end
0	DOWNLINK_MALARGUE	2031-01-20T08:03:38Z	2031-01-20T17:03:41Z

You can use both keywords at the same time:

downlinks.trim(before='2031-01-20T12:00:00', after='2031-01-21T12:00:00')

	event name	t_start	t_end
0	DOWNLINK_MALARGUE	2031-01-20T12:00:00	2031-01-20T17:03:41Z
1	DOWNLINK_MALARGUE	2031-01-21T08:00:40Z	2031-01-21T12:00:00

or use directly an other event object:

from planetary_coverage.events import EventWindow

event = EventWindow('DUMMY_EVENT', t_start='2031-01-20T12:00:00', t_end='2031-01-21T12:00:00')

downlinks.trim(by_event=event)

	event name	t_start	t_end
0	DOWNLINK_MALARGUE	2031-01-20T12:00:00	2031-01-20T17:03:41Z
1	DOWNLINK_MALARGUE	2031-01-21T08:00:40Z	2031-01-21T12:00:00

Events usage#

All these events objects are compatible with TourConfig and Trajectory objects, for example you can use them to select a time window:

tour[gco_500:'1h']

<SpacecraftTrajectory> Observer: JUICE | Target: GANYMEDE
 - UTC start time: 2035-05-21T15:00:00.000
 - UTC stop time: 2035-09-29T00:00:00.000
 - Nb of pts: 3,130

You can also use an event to defined quickly the associated flyby:

tour.flyby(flyby_1G1)

<SpacecraftFlyby> Observer: JUICE | Target: GANYMEDE
 - Altitude at CA: 400.0 km
 - UTC at CA: 2031-07-21T07:08:09
 - Duration: 1 day, 0:00:00
 - Nb of pts: 2,041

You can also get multiple flyby trajectories at once (here the first 3 flybys above Ganymede defined before):

tour.flyby(flybys)

[<SpacecraftFlyby> Observer: JUICE | Target: GANYMEDE
  - Altitude at CA: 400.0 km
  - UTC at CA: 2031-07-21T07:08:09
  - Duration: 1 day, 0:00:00
  - Nb of pts: 2,041,
 <SpacecraftFlyby> Observer: JUICE | Target: GANYMEDE
  - Altitude at CA: 400.0 km
  - UTC at CA: 2032-02-13T23:03:55
  - Duration: 1 day, 0:00:00
  - Nb of pts: 2,041]

Temporal operation is also supported on the Event and EventWindow objects, for example you can take the trajectory 12 hours around a flyby CA event (with a regular temporal step of 10 minutes):

Hint

A subtraction is performed on the start time and an addition is performed on the stop time.

tour[flyby_1G1 - '12 h':flyby_1G1 + '12 h':'10 mins']

<SpacecraftTrajectory> Observer: JUICE | Target: GANYMEDE
 - UTC start time: 2031-07-20T19:14:23.000
 - UTC stop time: 2031-07-21T19:14:23.000
 - Nb of pts: 145

You can also filter a trajectory with any EventWindow or EventsList. Here we choose to take all the tour (from the beginning to the end of the mission with a temporal step of 1h) and we only show the point during the GCO500 phase.

Caution

Filtering on a large temporal windows is very inefficient. Here the full trajectory contains more than 4,500 points when only 130 are really relevant. You should better use the solution presented above:

tour[gco_500:'1 day']

to get the same result in the more efficient way.

tour['start':'stop':'1 day'] & gco_500

<MaskedSpacecraftTrajectory> Observer: JUICE | Target: GANYMEDE
 - First UTC start time: 2035-05-22T00:00:00.000
 - Last UTC stop time: 2035-06-02T23:59:59.999
 - Nb of pts: 13 (+1,584 masked)
 - Nb of segments: 1

New in version 1.1.0

If a fk events kernel is load into the kernel pool, you can query them directly:

tour['GCO500':'1 day']

<SpacecraftTrajectory> Observer: JUICE | Target: GANYMEDE
 - UTC start time: 2035-05-21T15:00:00.000
 - UTC stop time: 2035-09-29T00:00:00.000
 - Nb of pts: 132

Trajectory filtering with events#

Similarly to the ROI, you can also discard an EventWindow or an EventsList. For example if you want to mask all the downlink period, you can do:

traj_no_downlinks = tour['2031-01-20' : '2031-01-22'] ^ downlinks

traj_no_downlinks

<MaskedSpacecraftTrajectory> Observer: JUICE | Target: GANYMEDE
 - First UTC start time: 2031-01-20T00:00:00.000
 - Last UTC stop time: 2031-01-22T00:00:00.000
 - Nb of pts: 1,802 (+1,080 masked)
 - Nb of segments: 3

We can represent the filtered trajectory parameter, with the 2 masked downlink windows:

_, ax = plt.subplots(figsize=(14, 3))

ax.plot(traj_no_downlinks.utc, traj_no_downlinks.inc, 'o', ms=2)

y0, y1 = ax.get_ylim()
for downlink in downlinks[:2]:
    ax.fill_between([downlink.start, downlink.stop], y0, y1, color='0.95')
    ax.text(downlink.start + (downlink.stop - downlink.start)/2, (y0 + y1) / 2,
            'Downlink\nwindow', ha='center', va='center')

ax.set_ylim(y0, y1)
ax.set_xlabel('UTC datetime in 2031')
ax.set_ylabel('Incidence angle (degree)');

../_images/4d7ca8d98b491f0c266c76b71bf0884f83008735ada7bf507d26b549e975bd46.png

You can also exclude an EventWindow or an EventsList directly in TourConfig or in the Trajectory definition:

Tip

If you know in advance the events that you want to discard, it is recommended to use this method to avoid creating trajectory points that will not be masked later on. Only the relevant points are kept.

TourConfig(
    mk='5.1 150lb_23_1',
    spacecraft='JUICE',
    target='Ganymede',
    exclude=downlinks,
    version='v422_20230130_002',
)['2031-01-20' : '2031-01-22']

<SpacecraftTrajectory> Observer: JUICE | Target: GANYMEDE
 - UTC start time: 2031-01-20T00:00:00.000
 - UTC stop time: 2031-01-22T00:00:00.000
 - Nb of pts: 1,802

ESA events files

Contents

ESA events files#

Event file format#

Parsing an events file#

Get an event by key#

Orbit numbers#

Events filtering#

Trim event(s) time boundaries#

Events usage#

Trajectory filtering with events#