Description
Calculates observation positions, "tiles", for a given multi-messenger event.
Query Parameters:
| Parameter |
Default |
Type |
Usage |
Required |
Description |
| url_map |
None |
String |
?url_map="Encoded URL" |
True |
Encoded URL to access the localisation map. Only URL from ligo.org are currently accepted. Reference for encoding : https://en.wikipedia.org/wiki/URL_encoding |
| start_obs_time |
None |
String (ISO Format) |
?start_obs_time=2023-01-01T00:00:00+01:00 |
True |
Earliest time to start observations |
| latitude_obs |
None |
Float |
?latitude_obs=-20.00 |
True |
Latitude of the observatory in degree |
| longitude_obs |
None |
Float |
?longitude_obs=10.00 |
True |
Longitude of the observatory in degree |
| altitude_obs |
None |
Float |
?altitude_obs=1855.0 |
True |
Altitude of the observatory in meter |
| fov |
2.0 |
Float |
?fov=2.0 |
False |
The size of the FoV of the instrument in degree |
| max_zenith |
70.0 |
Float |
?max_zenith=70.0 |
False |
Maximum zenith angle allowed for observations in degree |
| sun_horizon |
-18.0 |
Float |
?sun_horizon=-18.0 |
False |
Sun elevation (in degree) under which it is possible to perform observations. Common values: -18° for astronomical twilight (optical), -12° for nautical twilight, 90° for daytime observations (e.g., radio, HAWC, LHAASO). |
| moon_horizon |
-0.5 |
Float |
?moon_horizon=-0.5 |
False |
Moon elevation (in degree) under which the night will be considered dark. Set to 90 for daytime observations (e.g., radio telescopes). |
| maximum_moon_phase |
1.0 |
Float |
?maximum_moon_phase=0.6 |
False |
Maximum illumination fraction of the moon allowed for observations (0.0 = new moon, 1.0 = full moon). Only applies when moon is above moon_horizon. IACTs typically use 0.4-0.85. |
| minimum_moon_separation |
0 |
Float |
?minimum_moon_separation=30.0 |
False |
Minimum separation between the pointing and the moon in degree (only apply if moon is above moon_horizon) |
| maximum_moon_separation |
180 |
Float |
?maximum_moon_separation=140.0 |
False |
Maximum separation between the pointing and the moon in degree (only apply if moon is above moon_horizon) |
| max_nb_pointing |
20 |
Int |
?max_nb_pointing=200 |
False |
Maximum number of tiles in the schedule |
| max_nb_obs_night |
1 |
Int |
?max_nb_obs_night=1 |
False |
Number of nights for which it is allowed to schedule observations |
| pointing_obs_time |
30 |
Float |
?pointing_obs_time=30.0 |
False |
Observation time for each tile (in minute) |
| min_pointing_obs_time |
10 |
Float |
?min_pointing_obs_time=10.0 |
False |
Minimum observation time required for a tile (in minute) |
| max_distance_3D |
250 |
Float |
?max_distance_3D=250.0 |
False |
The 3D galaxy-targeting algorithm is used if the event distance + 2σ is below this value (in Mpc). For nearby GW events, this enables galaxy-catalog-based scheduling. Should not exceed 500 Mpc. |
| containment_fraction_explored |
0.9 |
Float |
?containment_fraction_explored=0.9 |
False |
Tiles will be searched only within the sky region corresponding to this containment fraction of the probability map (e.g., 0.9 = 90% credible region). |
| min_probability_tile |
2e-9 |
Float |
?min_probability_tile=0.01 |
False |
A tile will be valid only if the covered probability exceeds this value. Higher values (e.g., 0.01) focus on high-probability regions only. |
| name_tilling |
None |
String |
?name_tilling=my_fabulous_tilling |
False |
Name to give to the tiling operation |
| name_event |
None |
String |
?name_event=my_fabulous_event |
False |
Name of the event to be analyse (only impacting the name given by the API, not the tiling solution) |
Response fields:
| Field |
Type |
Description |
| _id |
String |
unique ID for the schedule |
| Field |
Type |
Description |
| url_map |
String |
Encoded URL to access the localisation map. Only URL from gracedb.ligo.org, heasarc.gsfc.nasa.gov or roc.icecube.wisc.edu are currently accepted. Reference for encoding : https://en.wikipedia.org/wiki/URL_encoding |
| start_obs_time |
String (ISO Format) |
Earliest time to start observations |
| latitude_obs |
Float |
Latitude of the observatory in degree |
| longitude_obs |
Float |
Longitude of the observatory in degree |
| altitude_obs |
Float |
Altitude of the observatory in meter |
| fov |
Float |
The size of the FoV of the instrument in degree |
| max_zenith |
Float |
Maximum zenith angle allowed for observations in degree |
| sun_horizon |
Float |
Sun elevation (in degree) under which it is possible to perform observation. Example:-18 for astronomical night, 90 for daylight observations |
| moon_horizon |
Float |
Moon elevation (in degree) under which, night will be considered dark |
| maximum_moon_phase |
Float |
Maximum illumination fraction of the moon possible for observations, the value should be between 0 and 1 (only apply if moon is above moon_horizon) |
| minimum_moon_separation |
Float |
Minimum separation between the pointing and the moon in degree (only apply if moon is above moon_horizon) |
| maximum_moon_separation |
Float |
Maximum separation between the pointing and the moon in degree (only apply if moon is above moon_horizon) |
| max_nb_pointing |
Int |
Maximum number of tiles in the schedule |
| max_nb_obs_night |
Int |
Number of nights for which it is allowed to schedule observations |
| pointing_obs_time |
Float |
Observation time for each tile (in minute) |
| min_pointing_obs_time |
Float |
Minimum observation time required for a tile (in minute) |
| name_tilling |
String |
Name to give to the tiling operation |
| Field |
Type |
Description |
| tilename |
String |
identifier for the current scheduling tile [tile_xxx] |
| ra |
Float |
Right ascension of the position to observe [deg] |
| dec |
Float |
Declination of the position to observe [deg] |
| ra_hms |
String |
Right ascension of the position to observe in HMS format |
| dec_dms |
String |
Declination of the position to observe in DMS format |
| obs_time_utc |
String |
Best time to start observations; format: YYYY-MM-DDThh:mm:ss |
| prob_fov |
float |
Estimated probabilities for the events to be within this field of view |
Usage example:
https://tilepy.com/tiling?url_map=https%3A%2F%2Fgracedb.ligo.org%2Fapi%2Fsuperevents%2FS230528ay%2Ffiles%2Folib.multiorder.fits%2C1&start_obs_time=2023-05-28&latitude_obs=-23.27&longitude_obs=16.5&altitude_obs=1835
Associated JSON response
{
"_id": "ca95ec1b1083752d019362e65f56c82a9b017d5d",
"tilepy_settings": {
"moonGrey": 65.0,
"targetType": "GW",
"useGreytime": true,
"minSlewing": 2.0,
"online": false,
"minimumProbCutForCatalogue": 1e-09,
"minProbcut": 2e-09,
"doPlot": false,
"secondRound": false,
"zenithWeighting": 0.75,
"reducedNside": 256,
"HRnside": 512,
"mangrove": false,
"event_name": "S230528ay",
"name_tilling": "1686835415629113",
"url_map": "https://gracedb.ligo.org/api/superevents/S230528ay/files/olib.multiorder.fits,1",
"start_obs_time": "2023-05-28T00:00:00",
"latitude_obs": -23.27,
"longitude_obs": 16.5,
"altitude_obs": 1835.0,
"sun_horizon": -18.0,
"moon_horizon": -0.5,
"maximum_moon_phase": 100.0,
"minimum_moon_separation": 0.0,
"maximum_moon_separation": 180.0,
"max_zenith": 70,
"fov": 2.0,
"max_nb_pointing": 20,
"max_nb_obs_night": 1,
"pointing_obs_time": 30.0,
"min_pointing_obs_time": 10.0,
"maximum_distance_3D": 500.0,
"containment_fraction_explored": 0.9
},
"schedule": {
"tile_000": {
"dec": -7.1808,
"dec_dms": "-07:10:50.88",
"obs_time_utc": "2023-09-20T19:36:43",
"prob_fov": 0.3382,
"ra": 1.9336,
"ra_hms": "00:07:44.064"
},
"tile_001": {
"dec": -10.8069,
"dec_dms": "-10:48:24.84",
"obs_time_utc": "2023-09-20T20:06:43",
"prob_fov": 0.2165,
"ra": 2.9883,
"ra_hms": "00:11:57.192"
},
"tile_002": {
"dec": -3.5833,
"dec_dms": "-03:34:59.88",
"obs_time_utc": "2023-09-20T20:36:43",
"prob_fov": 0.2159,
"ra": 0.8789,
"ra_hms": "00:03:30.936"
},
"tile_003": {
"dec": -14.1695,
"dec_dms": "-14:10:10.2",
"obs_time_utc": "2023-09-20T21:06:43",
"prob_fov": 0.0753,
"ra": 4.3945,
"ra_hms": "00:17:34.68"
},
"tile_004": {
"dec": -0.5968,
"dec_dms": "-00:35:48.48",
"obs_time_utc": "2023-09-20T21:36:43",
"prob_fov": 0.0446,
"ra": 0.1758,
"ra_hms": "00:00:42.192"
},
....
}
}
