sora.prediction

Prediction Functions

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

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 –

• 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.

Return type

list

sora.prediction.core.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')

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

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.

• 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.

PredictionTable Cbject

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

An Astropy Table object modified for Prediction purposes.

Row

alias of PredictRow

classmethod from_praia(filename, name, **kwargs)

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

A PredictionTable object.

Return type

sora.prediction.PredictionTable

keep_from_selected_images(path='.')

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.

plot_occ_map(**kwargs)

Parameters

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

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

• path (str) – Path to a directory where to save map.

• resolution (int, default=2) –

• resolution. (Cartopy feature) –

• "10m"; (- 1 means a resolution of) –

• "50m"; (- 2 a resolution of) –

• "100m". (- 3 a resolution of) –

• 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.

• 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.

Note

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 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.

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 to save table.