sora.prediction

Prediction Functions

sora.prediction.core.occ_params(star, ephem, time, n_recursions=5, max_tdiff=None, reference_center='geocenter')

Calculates the main parameters of a stellar occultation.

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 (str, astropy.time.Time) – Time close to occultation epoch to calculate occultation parameters.

• n_recursions (int, default=5) – The number of attempts to obtain prediction parameters in case the event is outside the previous range of time.

• max_tdiff (int, float, optional) – 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, default=’geocenter’) – A SORA observer object, spacecraft object, or a string such as 'geocenter'. The occultation parameters are calculated with respect to this reference as the center of projection.

Returns:

tca, ca, pa, vel, dist – Instant of closest approach, closest-approach distance, position angle, shadow velocity, and object distance.

Return type:

tuple

sora.prediction.core.prediction(time_beg, time_end, body=None, ephem=None, mag_lim=None, catalogue='gaiadr3_linea', step=60, divs=1, sigma=1, radius=None, verbose=True, reference_center='geocenter')

Predicts stellar occultations.

Parameters:

• time_beg (str, astropy.time.Time) – Initial time for prediction.

• time_end (str, astropy.time.Time) – Final time for prediction.

• body (sora.Body, str, optional) – 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, optional) – Object ephemeris. It must be an Ephemeris object. If using an EphemHorizons object, please use ‘divs’ to make divisions 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 set for a specific band or a set of bands. 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, Catalogue, default=’gaiadr3_linea’) – The catalogue to download data. It can be 'gaiadr2', 'gaiaedr3', 'gaiadr3', 'gaiadr3_linea', or a Catalogue object.

• step (int, float, default=60) – Step, in seconds, of ephemeris 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, optional) – The radius of the body. It is important if not defined in body or ephem.

• verbose (bool, default=True) – If True, prints progress information.

• reference_center (str, sora.Observer, sora.Spacecraft, default=’geocenter’) – A SORA observer object, spacecraft object, or a string such as 'geocenter'. The occultation parameters are calculated with respect to this reference as the 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.

Notes

When instantiating with “body” and “ephem”, the user may call the function in three 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:

prediction_table – PredictionTable with the occultation params for each event.

Return type:

sora.prediction.PredictionTable

Plot Occultation Map

sora.prediction.occmap.plot_occ_map(name, radius, coord, time, ca, pa, vel, dist, mag=0, longi=0, **kwargs)

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.

• band (str, default=’G’) – Photometric band name used in the map labels.

• nameimg (str, optional) – Change the name of the saved image.

• path (str, default=’.’) – Path to a directory where to save map.

• resolution (int, default=2) – Cartopy feature resolution. 1 means a resolution of “10m”; 2 means “50m”; and 3 means “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, default=1) – 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 by a displacement in X and Y, in km. It must be a list with two numbers.

• centerproj (list, optional) – 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, str, optional) – 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, color and marker. 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. marker is the symbols used for each station following matplotlib.pyplot properties.

• site_name (bool) – If True, plots the names of the given sites. Otherwise, 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, str, optional) – 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, default=[0.0, 0.0]) – 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, optional) – 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.

• nscale (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, default=True) – If True, it plots the arrow with the occultation direction.

Notes

Required parameters to plot an occultation map: ‘name’, ‘radius’, ‘coord’, ‘time’, ‘ca’, ‘pa’, ‘vel’, and ‘dist’.

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.

PredictionTable Cbject

class sora.prediction.PredictionTable(*args, **kwargs)

Astropy Table object modified for prediction purposes.

Row

alias of PredictRow

classmethod from_praia(filename, name, **kwargs)

Creates a PredictionTable by reading 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 is searched in online database. When not found online, the default is set to zero.

Returns:

table – A PredictionTable object.

Return type:

sora.prediction.PredictionTable

keep_from_selected_images(path='.')

Keeps predictions whose images were not deleted in a 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, default=’.’) – Path where images are located.

plot_occ_map(**kwargs)

Plots an occultation map for this prediction row.

Parameters:

• radius (int, float, optional) – The radius of the shadow. If not given it uses saved value.

• nameimg (str, optional) – Change the name of the image saved.

• path (str, default=’.’) – Path to a directory where to save map.

• resolution (int, default=2) – Cartopy feature resolution. 1 means a resolution of “10m”; 2 means “50m”; and 3 means “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 by a displacement in X and Y, in km. It must be a list with two numbers.

• centerproj (list, optional) – 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, str, optional) – 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, color and marker. 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. marker is the symbols used for each station following matplotlib.pyplot properties.

• site_name (bool) – If True, plots the names of the given sites. Otherwise, plots only the points.

• countries (dict, str, optional) – 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, default=[0.0, 0.0]) – 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, optional) – 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.

• nscale (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, default=True) – If True, it plots the arrow with the occultation direction.

Notes

Only one of centermap_geo and centermap_delta can be given.

remove_occ(date)

Removes stellar occultations from table.

Parameters:

date (str, list) – Date or list of dates of the occultation to be removed. The dates must be as shown in the ‘Epoch’ column. If the date is not complete, the function will select all occultations that match the given string. For instance, date='2020-06' will remove all occultations from the month of June 2020.

to_ow(ow_des, mode='append')

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.

to_praia(filename)

Writes PredictionTable to PRAIA format.

Parameters:

filename (str) – Name of the file where the table will be saved.