prediction() function and the PredictionTable Class
The prediction module within SORA was created to predict stellar occultation, organize the prediction and plot the occultation maps. The documentation here contains the details about every step.
This Jupyter-Notebook was designed as a tutorial for how to work with the prediction module. Any further question, please contact the core team: Altair Ramos Gomes Júnior, Bruno Eduardo Morgado, Gustavo Benedetti Rossi, and Rodrigo Carlos Boufleur.
All functions have their Docstring containing its main purpose and the needed parameters (physical description and formats). Please, do not hesitate to use it.
0. Index
1. Predicting stellar occultation
To predict a stellar occultation, the function prediction()
must be used. It will need a Body
Object and the time interval for the search. The function will generate the ephemeris within the given interval (with a default step of 60 seconds between positions, that may be changed by the user) and download the star coordinates from VizieR. The function is able to download stars from Gaia-DR2, Gaia-EDR3 and Gaia-DR3. The user must select the one desired by the keys “gaiadr2”, “gaiaedr3”
or “gaiadr3” (default in v0.3). For every star, it checks the closest ephemeris. An occultation is identified if the distance is smaller than the radius of the Earth plus the radius of the object (given in Body
) plus the error of the ephemeris (multiplied by a sigma factor given by the user). In the next step, the coordinate of the star is propagated to date using proper motion and parallax. It results in the occultation parameters, such as the Closest Approach distance, the Position
Angle, Velocity, etc.
The function returns a PredictionTable
with all the information.
[1]:
from sora.prediction import prediction
SORA version: 0.3
[2]:
prediction?
Signature:
prediction(
time_beg,
time_end,
body=None,
ephem=None,
mag_lim=None,
catalogue='gaiadr3',
step=60,
divs=1,
sigma=1,
radius=None,
verbose=True,
reference_center='geocenter',
)
Docstring:
Predicts stellar occultations.
Parameters
----------
time_beg : `str`, `astropy.time.Time`, required
Initial time for prediction.
time_end : `str`, `astropy.time.Time`, required
Final time for prediction.
body : `sora.Body`, `str`, default=None
Object that will occult the stars. It must be a Body object or its name
to search in the Small Body Database.
ephem : `sora.Ephem`, default=None
object ephemeris. It must be an Ephemeris object.
If using a EphemHorizons object, please use 'divs' to make division
at most a month, or a timeout error may be raised by the Horizon query.
mag_lim : `int`, `float`, `dict`, default=None
Faintest magnitude allowed in the search. If the catalogue has more
than one band defined in the catalogue object, the magnitude limit can
be done for a specific band or a set of band. Ex: ``mag_lim={'V': 15}``,
which will only download stars with V<=15 or ``mag_lim={'V': 15, 'B': 14}``
which will download stars with V<=15 AND B<=14.
catalogue : `str`, `VizierCatalogue`
The catalogue to download data. It can be ``'gaiadr2'``, ``'gaiaedr3'``,
``'gaiadr3'``, or a VizierCatalogue object. default='gaiadr3'
step : `int`, `float`, default=60
Step, in seconds, of ephem times for search
divs : `int`, default=1
Number of regions the ephemeris will be split for better search of
occultations.
sigma : `int`, `float`, default=1
Ephemeris error sigma for search off-Earth.
radius : `int`, `float`, default=None
The radius of the body. It is important if not defined in body or ephem.
verbose : `bool`, default=True
To show what is being done at the moment.
reference_center : `str`, `sora.Observer`, `sora.Spacecraft`
A SORA observer object or a string 'geocenter'.
The occultation parameters will be calculated in respect
to this reference as center of projection. If a Spacecraft
is used, please use smaller step since the search will be based
on the target size and ephemeris error only.
Important
---------
When instantiating with "body" and "ephem", the user may call the function
in 3 ways:
1 - With "body" and "ephem".
2 - With only "body". In this case, the "body" parameter must be a Body
object and have an ephemeris associated (see Body documentation).
3 - With only "ephem". In this case, the "ephem" parameter must be one of
the Ephem Classes and have a name (see Ephem documentation) to search
for the body in the Small Body Database.
Returns
-------
: `sora.prediction.PredictionTable`
PredictionTable with the occultation params for each event.
File: ~/Documentos/códigos/SORA/sora/prediction/core.py
Type: function
Importing and defining the Body
to be used.
As showed in the docstring of the prediction()
function, the user can give a Body
object, an Ephem
object, or both (given their restrictions). Please refer to the Body
tutorial for further explanation.
Important Note: The files “de438_small.bsp” and “Chariklo.bsp” are modified files for the purpose of this guideline. If the user wants to predict for different object or epoch, proper files should be provided.
[3]:
from sora.body import Body
from sora.ephem import EphemKernel
chariklo = Body(name='Chariklo')
ephem = EphemKernel(spkid='2010199', kernels=['input/bsp/Chariklo.bsp', 'input/bsp/de438_small.bsp'], error_ra=0.01, error_dec=0.01)
# here I'm using Body and Ephem so I'm able to give the errors in RA and DEC.
chariklo.ephem = ephem
Obtaining data for Chariklo from SBDB
[4]:
pred = prediction(body=chariklo, time_beg='2017-06-20 00:00:00', time_end='2017-07-01 00:00:00', mag_lim=18, divs=3)
Ephemeris was split in 3 parts for better search of stars
Searching occultations in part 1/3
Generating Ephemeris between 2017-06-20 00:00:00.000 and 2017-06-23 15:59:00.000 ...
Downloading stars ...
15 GaiaDR3 stars downloaded
Identifying occultations ...
Searching occultations in part 2/3
Generating Ephemeris between 2017-06-23 16:00:00.000 and 2017-06-27 07:59:00.000 ...
Downloading stars ...
11 GaiaDR3 stars downloaded
Identifying occultations ...
Searching occultations in part 3/3
Generating Ephemeris between 2017-06-27 08:00:00.000 and 2017-06-30 23:59:00.000 ...
Downloading stars ...
18 GaiaDR3 stars downloaded
Identifying occultations ...
8 occultations found.
Important
The default prediction is made considering the geocenter as center of reference. However, the prediction can also be made for a specific observer. In this case, it is important to note that the search considers only the size of the object and ephemeris error. If the object is very small, consider using a time step
for initial prediction smaller, or using a different radius
to avoid losing a promising event. Notice the occultation parameters (closest appoach time and distance, …) are
referred to the observer.
[5]:
from sora import Observer
outeniqua = Observer(name='Outeniqua', lon='+16 49 17.710', lat='-21 17 58.170', height=1416,
ephem=['input/bsp/Chariklo.bsp', 'input/bsp/de438_small.bsp'])
obs_pred = prediction(body=chariklo, time_beg='2017-06-20 00:00:00', time_end='2017-07-01 00:00:00', step=10,
mag_lim=18, divs=3, reference_center=outeniqua)
Ephemeris was split in 3 parts for better search of stars
Searching occultations in part 1/3
Generating Ephemeris between 2017-06-20 00:00:00.000 and 2017-06-23 15:59:50.000 ...
Downloading stars ...
10 GaiaDR3 stars downloaded
Identifying occultations ...
Searching occultations in part 2/3
Generating Ephemeris between 2017-06-23 16:00:00.000 and 2017-06-27 07:59:50.000 ...
Downloading stars ...
8 GaiaDR3 stars downloaded
Identifying occultations ...
Searching occultations in part 3/3
Generating Ephemeris between 2017-06-27 08:00:00.000 and 2017-06-30 23:59:50.000 ...
Downloading stars ...
15 GaiaDR3 stars downloaded
Identifying occultations ...
1 occultations found.
[6]:
obs_pred[0]
[6]:
Epoch | ICRS Star Coord at Epoch | Geocentric Object Position | C/A | P/A | Vel | Dist | G | long | loct | M-G-T | S-G-T | GaiaDR3 Source ID |
---|---|---|---|---|---|---|---|---|---|---|---|---|
arcsec | deg | km / s | AU | mag | deg | hh:mm | deg | deg | ||||
object | object | object | float64 | float64 | float64 | float64 | float64 | float64 | str5 | float64 | float64 | str19 |
2017-06-22 21:21:25.600 | 18 55 15.65251 -31 31 21.67062 | 18 55 15.65251 -31 31 21.67688 | 0.006 | 179.52 | -22.36 | 14.659 | 14.224 | 52 | 00:50 | 149 | 166 | 6760223758801661440 |
[7]:
pred['2017-06-22 21']
[7]:
Epoch | ICRS Star Coord at Epoch | Geocentric Object Position | C/A | P/A | Vel | Dist | G | long | loct | M-G-T | S-G-T | GaiaDR3 Source ID |
---|---|---|---|---|---|---|---|---|---|---|---|---|
arcsec | deg | km / s | AU | mag | deg | hh:mm | deg | deg | ||||
object | object | object | float64 | float64 | float64 | float64 | float64 | float64 | str5 | float64 | float64 | str19 |
2017-06-22 21:18:48.200 | 18 55 15.65251 -31 31 21.67062 | 18 55 15.65249 -31 31 21.62190 | 0.049 | 359.72 | -22.00 | 14.659 | 14.224 | 53 | 00:50 | 149 | 166 | 6760223758801661440 |
2. The PredictionTable
The resulting variable of the prediction function is a PredictionTable
Object. The PredictionTable
Class was created to have all the information about the occultations predicted, plot occultation maps and save the table in other formats.
The PredictionTable
is a class that inherits all methods from Astropy.table.Table
. All the functions present in Astropy.table.Table
should work for PredictionTable
.
More information about it at https://docs.astropy.org/en/stable/table/
if the user asks to print the prediction, a summary of the table is shown.
[8]:
print(pred)
Epoch ICRS Star Coord at Epoch ... GaiaDR3 Source ID
...
----------------------- ------------------------------ ... -------------------
2017-06-21 09:57:43.440 18 55 36.17454 -31 31 19.03261 ... 6760228702284187264
2017-06-22 02:58:37.480 18 55 26.31652 -31 31 20.38440 ... 6760228839723992320
2017-06-22 21:18:48.200 18 55 15.65251 -31 31 21.67062 ... 6760223758801661440
2017-06-23 21:34:37.660 18 55 01.48119 -31 31 22.44257 ... 6760223513963694208
2017-06-24 10:13:39.980 18 54 54.06755 -31 31 22.36732 ... 6760226503261782656
2017-06-25 10:55:09.320 18 54 39.55296 -31 31 21.69987 ... 6760225163236852864
2017-06-26 08:14:35.540 18 54 26.97503 -31 31 20.51255 ... 6760226060885482624
2017-06-26 20:46:07.140 18 54 19.56971 -31 31 20.43382 ... 6760225712991422208
to print the complete table, we must use:
[9]:
pred.pprint_all()
Epoch ICRS Star Coord at Epoch Geocentric Object Position C/A P/A Vel Dist G long loct M-G-T S-G-T GaiaDR3 Source ID
arcsec deg km / s AU mag deg hh:mm deg deg
----------------------- ------------------------------ ------------------------------ ------ ------ ------ ------- ------ ---- ----- ----- ----- -------------------
2017-06-21 09:57:43.440 18 55 36.17454 -31 31 19.03261 18 55 36.17500 -31 31 19.60516 0.573 179.41 -21.84 14.663 15.254 225 00:56 128 165 6760228702284187264
2017-06-22 02:58:37.480 18 55 26.31652 -31 31 20.38440 18 55 26.31674 -31 31 20.74213 0.358 179.55 -21.92 14.661 17.929 329 00:53 138 166 6760228839723992320
2017-06-22 21:18:48.200 18 55 15.65251 -31 31 21.67062 18 55 15.65249 -31 31 21.62190 0.049 359.72 -22.00 14.659 14.224 53 00:50 149 166 6760223758801661440
2017-06-23 21:34:37.660 18 55 01.48119 -31 31 22.44257 18 55 01.48116 -31 31 22.22700 0.216 359.91 -22.10 14.657 17.818 48 00:46 162 167 6760223513963694208
2017-06-24 10:13:39.980 18 54 54.06755 -31 31 22.36732 18 54 54.06755 -31 31 22.28669 0.081 0.01 -22.15 14.656 17.928 218 00:43 167 168 6760226503261782656
2017-06-25 10:55:09.320 18 54 39.55296 -31 31 21.69987 18 54 39.55291 -31 31 21.89148 0.192 180.23 -22.23 14.654 16.955 206 00:39 164 168 6760225163236852864
2017-06-26 08:14:35.540 18 54 26.97503 -31 31 20.51255 18 54 26.97476 -31 31 20.99937 0.487 180.41 -22.30 14.653 17.603 245 00:35 154 169 6760226060885482624
2017-06-26 20:46:07.140 18 54 19.56971 -31 31 20.43382 18 54 19.56985 -31 31 20.23484 0.199 0.51 -22.33 14.652 17.702 57 00:33 147 169 6760225712991422208
M-G-T stands for Moon-Geocenter-Target, the on-sky angle between the star and the moon
S-G-T stands for Sun-Geocenter-Target, the on-sky angle between the star and the sun
The PredictionTable
can be exported to PRAIA format file
In this case, some information, such as the Gaia-DR2 Source ID, S-G-T and M-G-T, are lost.
[10]:
pred.to_praia?
Signature: pred.to_praia(filename)
Docstring:
Writes PredictionTable to PRAIA format.
Parameters
----------
filename : `str`
Name of the file to save table.
File: ~/Documentos/códigos/SORA/sora/prediction/table.py
Type: method
[11]:
pred.to_praia('output/Chariklo_occs.table')
# Check your folder named output
The PredictionTable
can also generate the files in the Occult Watcher feed format
These are two files, named ‘LOG.dat’ and ‘tableOccult_update.txt’. The occult watcher designation for the object must be informed. For instance, for the satellite Himalia, the designation is “P5M06”. If mode='append'
the prediction will be appended to an existing file. If mode='restart'
, the file will be overwritted.
[12]:
pred.to_ow?
Signature: pred.to_ow(ow_des, mode='append')
Docstring:
Writes PredictionTable to OccultWatcher feeder update file format.
Tables will be saved in two files: "tableOccult_update.txt" and "LOG.dat"
Parameters
----------
ow_des : `str`
Occult Watcher designation for the object.
mode : `str`, default='append'
Use ``'append'`` to append table to already existing file and
``'restart'`` to overwrite existing file.
File: ~/Documentos/códigos/SORA/sora/prediction/table.py
Type: method
[13]:
pred.to_ow('1997CU26')
Using the functions from Astropy.table.Table
, the data can be exported to many other formats using the funtion ‘write’
The formats allowed can be seen in https://docs.astropy.org/en/stable/io/unified.html#built-in-readers-writers. This includes latex and csv.
[14]:
pred.write('output/prediction.tex', overwrite=True)
# Check your folder named output
3. Using PredictionTable
The PredictionTable
was not created to be instantiated directly by the user. It was designed to be an insteresting output object from the prediction function. However, a PredictionTable
can be instantiated from a PRAIA occultation table. For this, a PredictionTable
method must be called directly as shown below.
[15]:
from sora.prediction import PredictionTable
[16]:
PredictionTable.from_praia?
Signature: PredictionTable.from_praia(filename, name, **kwargs)
Docstring:
Creates a PredictionTable Table reading from a PRAIA table.
Parameters
----------
filename : `str`
Path to the PRAIA table file.
name : `str`
Name of the Object of the prediction.
radius : `int`, `float`, optional
Object radius, in km.
If not given it's searched in online database.
When not found online, the default is set to zero.
Returns
-------
: `sora.prediction.PredictionTable`
A PredictionTable object.
File: ~/Documentos/códigos/SORA/sora/prediction/table.py
Type: method
[17]:
pred_1 = PredictionTable.from_praia(filename='output/Chariklo_occs.table', name='Chariklo')
Obtaining data for chariklo from SBDB
[18]:
pred_1.pprint_all()
Epoch ICRS Star Coord at Epoch Geocentric Object Position C/A P/A Vel Dist G long loct M-G-T S-G-T Source ID
arcsec deg km / s AU mag deg hh:mm deg deg
----------------------- ------------------------------ ------------------------------ ------ ------ ------ ------- ------ ---- ----- ----- ----- ----------
2017-06-21 09:57:43.400 18 55 36.17450 -31 31 19.03260 18 55 36.17500 -31 31 19.60520 0.573 179.41 -21.84 14.660 15.204 225 00:56 128 165
2017-06-22 02:58:37.400 18 55 26.31650 -31 31 20.38440 18 55 26.31670 -31 31 20.74210 0.358 179.55 -21.92 14.660 17.900 329 00:53 138 166
2017-06-22 21:18:48.200 18 55 15.65250 -31 31 21.67060 18 55 15.65250 -31 31 21.62190 0.049 359.72 -22.00 14.660 14.197 53 00:50 149 166
2017-06-23 21:34:37.600 18 55 01.48120 -31 31 22.44260 18 55 01.48120 -31 31 22.22700 0.216 359.91 -22.10 14.660 17.792 48 00:46 162 167
2017-06-24 10:13:39.900 18 54 54.06750 -31 31 22.36730 18 54 54.06750 -31 31 22.28670 0.081 0.01 -22.15 14.660 17.889 218 00:43 167 168
2017-06-25 10:55:09.300 18 54 39.55300 -31 31 21.69990 18 54 39.55290 -31 31 21.89150 0.192 180.23 -22.23 14.650 16.985 206 00:39 164 168
2017-06-26 08:14:35.500 18 54 26.97500 -31 31 20.51260 18 54 26.97480 -31 31 20.99940 0.487 180.41 -22.30 14.650 17.582 245 00:35 154 169
2017-06-26 20:46:07.100 18 54 19.56970 -31 31 20.43380 18 54 19.56980 -31 31 20.23480 0.199 0.51 -22.33 14.650 17.680 57 00:33 147 169
To remove some occultations the User can use two functions. The first is the PredictionTable.remove_occ().
[19]:
pred_1.remove_occ?
Signature: pred_1.remove_occ(date)
Docstring:
Removes stellar occultations from table.
Parameters
----------
date : `str`, `list`
Date or list of dates of the occultation to be removed.
The dates mut be as shown in the 'Epoch' column. If the date is not
complete, the function will select all occultations that matches the
given string. For instance, ``date='2020-06'`` will remove all
occultations from the month of June 2020.
File: ~/Documentos/códigos/SORA/sora/prediction/table.py
Type: method
[20]:
pred_1.remove_occ('2017-06-21 09:57')
[21]:
pred_1.pprint_all()
Epoch ICRS Star Coord at Epoch Geocentric Object Position C/A P/A Vel Dist G long loct M-G-T S-G-T Source ID
arcsec deg km / s AU mag deg hh:mm deg deg
----------------------- ------------------------------ ------------------------------ ------ ------ ------ ------- ------ ---- ----- ----- ----- ----------
2017-06-22 02:58:37.400 18 55 26.31650 -31 31 20.38440 18 55 26.31670 -31 31 20.74210 0.358 179.55 -21.92 14.660 17.900 329 00:53 138 166
2017-06-22 21:18:48.200 18 55 15.65250 -31 31 21.67060 18 55 15.65250 -31 31 21.62190 0.049 359.72 -22.00 14.660 14.197 53 00:50 149 166
2017-06-23 21:34:37.600 18 55 01.48120 -31 31 22.44260 18 55 01.48120 -31 31 22.22700 0.216 359.91 -22.10 14.660 17.792 48 00:46 162 167
2017-06-24 10:13:39.900 18 54 54.06750 -31 31 22.36730 18 54 54.06750 -31 31 22.28670 0.081 0.01 -22.15 14.660 17.889 218 00:43 167 168
2017-06-25 10:55:09.300 18 54 39.55300 -31 31 21.69990 18 54 39.55290 -31 31 21.89150 0.192 180.23 -22.23 14.650 16.985 206 00:39 164 168
2017-06-26 08:14:35.500 18 54 26.97500 -31 31 20.51260 18 54 26.97480 -31 31 20.99940 0.487 180.41 -22.30 14.650 17.582 245 00:35 154 169
2017-06-26 20:46:07.100 18 54 19.56970 -31 31 20.43380 18 54 19.56980 -31 31 20.23480 0.199 0.51 -22.33 14.650 17.680 57 00:33 147 169
The second function is the PredictionTable.keep_from_selected_images()
this function will check the names in the saved images and eliminate the occultations without the map. This functions allows that after the user deleted the maps of the unwanted occultation it will eliminate the respective rows in the PredictionTable
.
[22]:
pred_1.keep_from_selected_images?
Signature: pred_1.keep_from_selected_images(path='.')
Docstring:
Keeps predictions which images were not deleted in given path.
This function uses the name of the images to identify predictions.
The name must be the automatic one generated by plot_occ_map().
The format of the image is not relevant.
Parameters
----------
path : `str`
Path where images are located.
File: ~/Documentos/códigos/SORA/sora/prediction/table.py
Type: method
4. Plotting occultation maps
SORA is also able to generate an occultation map. The only required parameters are the occultation parameters. The function also has many inputs to configure the plot.
The first time the function is called, cartopy will download some data referring to the features presented in the map, such as the country and state division, lakes, rivers, etc.
[23]:
from sora.prediction import plot_occ_map
[24]:
plot_occ_map?
Signature:
plot_occ_map(
name,
radius,
coord,
time,
ca,
pa,
vel,
dist,
mag=0,
longi=0,
**kwargs,
)
Docstring:
Plots the map of the occultation.
Parameters
----------
name : `str`
Name of the object.
radius : `int`, `float`
Radius of the object, in km.
coord : `str`, `astropy.coordinates.SkyCoord`
Coordinates of the star (``"hh mm ss.sss dd mm ss.sss"`` or
``"hh.hhhhhhhh dd.dddddddd"``).
time : `str`, `astropy.time.Time`
Instant of Closest Approach (iso or isot format).
ca : `int`, `float`
Closest Approach Distance, in arcsec.
pa : `int`, `float`
Position Angle at C/A, in degrees.
vel : `int`, `float`
Velocity of the event, in km/s.
dist : `int`, `float`
Object distance at C/A, in AU.
mag : `int`, `float`, default=0
Mag* = Normalized magnitude to vel=20km/s.
longi : `int`, `float`, default=0
East longitude of sub-planet point, deg, positive towards East.
nameimg : `str`
Change the name of the imaged saved.
path : `str`
Path to a directory where to save map.
resolution : `int`, default=2
Cartopy feature resolution.
- ``1`` means a resolution of "10m";
- ``2`` a resolution of "50m";
- ``3`` a resolution of "100m".
states : `bool`
If True, plots the states borders of the countries. The states
of some countries will only be shown depending on the resolution.
zoom : `int`, `float`
Zooms in or out of the map.
centermap_geo : `list`, default=None
Center the map given coordinates in longitude and latitude. It must be
a list with two numbers.
centermap_delta : `list`, default=None
Displace the center of the map given displacement in X and Y, in km.
It must be a list with two numbers.
centerproj : `list`
Rotates the Earth to show occultation with the center projected at a
given longitude and latitude. It must be a list with two numbers.
labels : `bool`, default=True
Plots text above and below the map with the occultation parameters.
meridians : `int`, default=30
Plots lines representing the meridians for given interval, in degrees.
parallels : `int`, default=30
Plots lines representing the parallels for given interval, in degrees.
sites : `dict`
Plots site positions in map. It must be a python dictionary where the
key is the `name` of the site, and the value is a list with `longitude`,
`latitude`, `delta_x`, `delta_y` and `color`. `delta_x` and `delta_y`
are displacement, in km, from the point position of the site in the map
and the `name`. `color` is the color of the point.
site_name : `bool`
If True, it prints the name of the sites given, else it plots only the points.
site_box_alpha : `int`, `float`, default=0
Sets the transparency of a box surrounding each station name. 0 equals to
transparent, and 1 equals to opaque.
countries : `dict`
Plots the names of countries. It must be a python dictionary where the
key is the name of the country and the value is a list with longitude
and latitude of the lower left part of the text.
offset : `list`
Applies an offset to the ephemeris, calculating new CA and instant of
CA. It is a pair of `delta_RA*cosDEC` and `delta_DEC`.
mapstyle : `int`, default=1
Define the color style of the map. ``'1'`` is the default black
and white scale. ``'2'`` is a colored map.
error : `int`, `float`
Ephemeris error in mas. It plots a dashed line representing radius + error.
ercolor : `str`
Changes the color of the lines of the error bar.
ring : `int`, `float`
Plots a dashed line representing the location of a ring. It is given
in km, from the center.
rncolor : `str`
Changes the color of ring lines.
atm : `int`, `float`
Plots a dashed line representing the location of an atmosphere. It is
given in km, from the center.
atcolor : `str`
Changes the color of atm lines.
chord_delta : `list`
List with distances from center to plot chords.
chord_geo : `2d-list`
List with pairs of coordinates to plot chords.
chcolor : `str`, default='grey'
Color of the line of the chords.
heights : `list`
It plots a circular dashed line showing the locations where the observer
would observe the occultation at a given height above the horizons.
This must be a list.
hcolor : `str`
Changes the color of the height lines.
mapsize : `list`, default= [46.0, 38.0]
The size of figure, in cm. It must be a list with two values.
cpoints : `int`, `float`, default=60
Interval for the small points marking the center of shadow, in seconds.
ptcolor : `str`
Change the color of the center points.
alpha : `float`, default=0.2
The transparency of the night shade, where 0.0 is full transparency and
1.0 is full black.
fmt : `str`, default:'png'
The format to save the image. It is parsed directly by `matplotlib.pyplot`.
dpi : `int`, default=100
Resolution in "dots per inch". It defines the quality of the image.
lncolor : `str`
Changes the color of the line that represents the limits of the shadow
over Earth.
outcolor :`str`
Changes the color of the lines that represents the limits of the shadow
outside Earth.
scale : `int`, `float`
Arbitrary scale for the size of the name of the site.
cscale : `int`, `float`
Arbitrary scale for the name of the country.
sscale : `int`, `float`
Arbitrary scale for the size of point of the site.
pscale : `int`, `float`
Arbitrary scale for the size of the points that represent the center of
the shadow.
arrow : `bool`
If True, it plots the arrow with the occultation direction.
Important
---------
Required parameters to plot an occultation map: 'name', 'radius', 'coord',
'time', 'ca', 'pa', 'vel', and 'dist'.
Note
----
The parameters 'mag' and 'longi' are optional and only printed in label.
All other remaining parameters can be used to further customize the Map
configuration.
When producing the map, only one of 'centermap_geo' or 'centermap_delta'
options can be used at a time.
File: ~/Documentos/códigos/SORA/sora/prediction/occmap.py
Type: function
To make it easier to plot the predictions, the ``PredictionTable.plot_occ_map()`` function can be called which automatically fills the required parameters.
To plot the map for all the predictions
[25]:
pred.plot_occ_map(path='output/')
10199 Chariklo_2017-06-21T09_57_43.440.png generated
10199 Chariklo_2017-06-22T02_58_37.480.png generated
10199 Chariklo_2017-06-22T21_18_48.200.png generated
10199 Chariklo_2017-06-23T21_34_37.660.png generated
10199 Chariklo_2017-06-24T10_13_39.980.png generated
10199 Chariklo_2017-06-25T10_55_09.320.png generated
10199 Chariklo_2017-06-26T08_14_35.540.png generated
10199 Chariklo_2017-06-26T20_46_07.140.png generated
To plot the map for only one prediction, just give an item to the PredictionTable
object.
[26]:
pred[0].plot_occ_map(path='output/')
10199 Chariklo_2017-06-21T09_57_43.440.png generated
The PredictionTable
can also be plotted by giving the date of the occultation. All the occultations that matches the date will be plotted.
The date can be as constrained as the user wants, and must match the text that appears in the ‘Epoch’ column.
[27]:
pred['2017-06-26'].plot_occ_map()
10199 Chariklo_2017-06-26T08_14_35.540.png generated
10199 Chariklo_2017-06-26T20_46_07.140.png generated
5. Occultation parameters
Finally, a function is implemented in the prediction module which calculates the occultation parameters. For this function, it must be passed a Star
Object, an Ephem
Object (it can be any of the Ephem
classes) and a time. The time does not need to be precise, but it must be close within 60 minutes from the Closest Approach time.
[28]:
from sora.prediction import occ_params
[29]:
occ_params?
Signature:
occ_params(
star,
ephem,
time,
n_recursions=5,
max_tdiff=None,
reference_center='geocenter',
)
Docstring:
Calculates the parameters of the occultation, as instant, CA, PA.
Parameters
----------
star : `sora.Star`
The coordinate of the star in the same reference frame as the ephemeris.
It must be a Star object.
ephem : `sora.Ephem*`
Object ephemeris. It must be an Ephemeris object.
time : `astropy.time.Time`
Time close to occultation epoch to calculate occultation parameters.
n_recursions : `int`, default=5
The number of attempts to try obtain prediction parameters in case the
event is outside the previous range of time.
max_tdiff : `int`, default=None
Maximum difference from given time it will attempt to identify the
occultation, in minutes. If given, 'n_recursions' is ignored.
reference_center : `str`, `sora.Observer`, `sora.Spacecraft`
A SORA observer object or a string 'geocenter'.
The occultation parameters will be calculated in respect
to this reference as center of projection.
Returns
-------
Oredered list : `list`
- Instant of CA (Time): Instant of Closest Approach.
- CA (arcsec): Distance of Closest Approach.
- PA (deg): Position Angle at Closest Approach.
- vel (km/s): Velocity of the occultation.
- dist (AU): the object geocentric distance.
File: ~/Documentos/códigos/SORA/sora/prediction/core.py
Type: function
[30]:
from sora.star import Star
s = Star(code='6760225712991422208', verbose=False)
[31]:
tca, ca, pa, vel, dist = occ_params(star=s, ephem=chariklo.ephem, time='2017-06-26 20:40')
print('Time of the CA: {} UTC'.format(tca))
print('Closest Approach: {:.3f}'.format(ca))
print('Position Angle: {:.3f}'.format(pa))
print('Shadow Velocity: {:.3f}'.format(vel))
print('Object Distance: {:.5f}'.format(dist))
Time of the CA: 2017-06-26 20:46:07.140 UTC
Closest Approach: 0.199 arcsec
Position Angle: 0.511 deg
Shadow Velocity: -22.333 km / s
Object Distance: 14.65229 AU
This Jupyter-Notebook was designed as a tutorial for how to work with the prediction()
function and PredictionTable
Class. More information about the other classes, please refer to their specif Jupyter-Notebook. Any further question, please contact the core team: Altair Ramos Gomes Júnior, Bruno Eduardo Morgado, Gustavo Benedetti Rossi, and Rodrigo Carlos Boufleur.
The End