Releases
SORA v0.3 (2023/Jan/31)
New Features
sora.body
Added get_position() in Body as a shortcut to ephem.get_position(). [#76]
Created new frame submodule: [#74]
Define a new class for the orientation of the body (PlanetocentricFrame), giving its rotation velocity, pole coordinates, and precession parameters as defined by Archinal et al. (2018). With it, we can transform to other reference frames using Astropy.
The definitions of the orientation parameters in Archinal et al. (2018) are hardcoded. The user can overwrite it by providing its own frame.
With the PlanetocentricFrame, we process and rotate the body to find its orientation at any epoch (must consider light time).
Created new shape submodule to: [#74]
Define the new Shape3D class where we can provide to the body a wavefront file with its 3D shape. An image corresponding to the texture can also be provided.
Define the new Ellipsoid class where the 3-dimensional sizes of the ellipsoid are provided to create a 3D object.
Plot the 3D shape on the tangent plane considering the sub-observer coordinates, its pole orientation, and the solar illumination.
Compute the limb of the rotated 3D shape to use it in the fitting process. This limb now requires a dependency on shapely.
sora.lightcurve
Added argument “method” in LightCurve.occ_lcfit() method to allow the use of different fitting procedures. [#75]
Added argument “threads” in LightCurve.occ_lcfit() method to allow shared memory parallel processing. [#75]
Added argument “verbose” in LightCurve.occ_lcfit() method to enable progress bar during fitting procedure. [#75]
sora.occultation
Added argument “method” in Occultation.fit_ellipse() method to allow the use of different fitting procedures. [#75]
Added argument “threads” in Occultation.fit_ellipse() method to allow shared memory parallel processing. [#75]
Added argument “verbose” in Occultation.fit_ellipse() method to enable progress bar during fitting procedure. [#75]
New method fit_shape() is created to fit the occultation chords to the 3D shape. [#74]
An auxiliary fitting function fit_to_limb() was created to fit the chords to a limb provided by the user. [#74]
sora.prediction
sora.star
Added a new class called
VizierCatalogueto allow the definition and usage of any catalogue available on Vizier. [#71]Included the
VizierCataloguein the Star class. [#71]Included the Gaia-DR3 catalogue, released on June 13, 2022, in the catalogue list. [#76]
Defined Gaia-DR3 as the default in the Star class. [#76]
sora.stats
New module dedicated to design model fitting procedures using different techniques. [#75]
API Changes
sora.ephem
id_type for planets and satellites are passed as None instead of major_body, following changes made in Horizons. [#76]
Bug Fixes
sora.ephem
Fixed bug that did not calculated ephemeris for observer when using Horizons if the observer did not have IAU code. [#80]
SORA v0.2.1 (2021/Aug/30)
New Features
sora.body
Added function “Body.to_log()”. [#65]
sora.extra
Added function “ChiSquare.to_log()”. [#65]
sora.observer
Added function “Observer.to_log()”. [#65]
sora.occultation
sora.prediction
Added new parameter “site_box_alpha” to plot map. [#65]
sora.star
API Changes
sora.occultation
Occultation.check_velocities() now calculates the normal velocity considering the ellipse fitted in fit_ellipse replacing the radial velocity. [#66]
sora.star
Added warning for Gaia stars with a high RUWE or Duplicity flag, indicating a possible issue with this star’s astrometry. [#65]
Bug Fixes
Updated versions of dependencies to avoid bug caused by conflict between them [#67]
sora.body
Fixed wrong albedos in satdb. [#66]
sora.ephem
sora.lightcurve
sora.occultation
Fixed bug that overwrote occultation parameters in the LightCurve when added to the ChordList. [#66]
Fixed bug that prevented the user to ignore the chord name as labels when plotting the chords. [#66]
Fixed bug that prevented Occultation instantiation if the size of the star can not be determined [#67]
sora.prediction
SORA v0.2 (2021/Jun/14)
New Features
sora.body
Created new Body Class which downloads the occulting body information from online source. At the moment, it downloads only from the Small-Body DataBase. The Body class will be the manager for all the Body information, such as Ephem, Shape, Ring, etc. [#51]
New Class PhysicalData, which inherits from astropy.units.quantity.Quantity, is created to handle physical data with uncertainty, reference and notes. [#51]
“pole_position_angle” and “apparent_magnitude” functions are now present in Body instead of Ephem.[#51]
Created a hardcoded satellite database to complement missing data of SBDB. It must be replaced in the future. [#61]
sora.ephem
sora.extra
sora.observer
New Spacecraft class developed to handle the geometry of a spacecraft observation. To use it,it is necessary a spkid and ephemeris. Ex: spacecraft = Spacecraft(name=’New Horizons’, spkid=’-98’, ephem=’horizons’). [#63]
The Observer class was updated to have an ephemeris as well. [#63]
Now the observer can be passed as parameter to Ephem*.get_position(observer=observer), Star.get_position(), Body.get_pole_position_angle() and Body.apparent_magnitude(). [#63]
sora.occultation
A shortcut was created in Occultation where the user can pass the coordinate of the star directly to Occultation, the Star object will be created automatically. [#46]
New Chord Class introduced to handle a chord with an Observer and a LightCurve. [#53]
New ChordList Class introduced to handle the list of Chords in an Occultation. [#53]
New function .get_impact_param() that calculates the impact parameter, minimal distance between the chord and the centre position, in Chord and ChordList.[#60]
New function .get_theoretical_times(), that calculates the theoretical times and chord size for a given ellipse in Chord and ChordList. [#60]
New function .check_time_shift() that calculates the offset in time to align the center of the chords in Occultation. [#60]
New parameters sigma_result, that saves the result with an extended error bar, and ellipse_error, that adds a further systematic error to be considered, in Occultation.fit_ellipse(). [#60]
New function filter_negative_chord() that compares the ChiSquare from an Ellipse fitting with the chords and remove the solutions that would cross a negative chord [#60]
New method to calculate the “f” and “g” positions for observers without referring to the geocenter. [#63]
sora.prediction
prediction() now makes use of the user input of the star to calculate faster the occultation parameters. [#48]
prediction() now can make predictions using Gaia-EDR3. A new parameter “catalogue” was created for choosing between Gaia-DR2 and Gaia-EDR3.[#61]
Fixed bug when plotting the heights in the map in a rotated projection. [#54]
prediction() can now predict for any observer. Ex: prediction(…, reference_center=observer). [#63]
sora.star
A new method get_position() was implemented in Star() that will replace geocentric() and barycentric() methods [#63]
API Changes
Update the argument “log” to “verbose” on all modules. [#61]
sora.ephem
“pole_position_angle” and “apparent_magnitude” is passed to Body Class. In Ephem, it will raise a FutureWarning. [#51]
The Ephem classes are now passed through the Body Class which will have priority over Ephem attributes. Parameters such as “spkid”, “radius”, “H” and “G”. [#51]
All Ephem Classes now inherits from BaseEphem, which holds core functionality for all of them. [#51]
sora.lightcurve
sora.observer
Removed the necessity for Observer to have a unique name associated. [#53]
sora.occultation
The new Body Class was implemented in Occultation. For backward compatibility, the previous usage is still possible if the Ephem object have a name. The Body Class is only required if the object is a planet or a planetary satellite. [#51]
Deprecated some functions that were passed to ChordList. [#53]
sora.prediction
prediction() now creates the time array inside each division to avoid memory overflow. [#48]
prediction() now propagates the positions of the stars using only the proper motions before comparing the stars with the ephemeris. [#48]
The new Body Class was implemented in prediction. For backward compatibility, the previous usage is still possible. [#51]
Bug Fixes
sora.lightcurve
Corrected bug in LightCurve model where the size of the star was being interpreted as radius instead of diameter [#60]
sora.prediction
SORA v0.1.2 (2020/Dec/14)
New Features
sora.star
API Changes
sora.star
The star module was moved to its own directory. [#52]
Bug Fixes
sora.star
SORA v0.1.1 (2020/Jul/30)
New Features
sora.config
Module to verify if kwargs are allowed was created. This was included throughout the code. [#8]
sora.extra
Added a parameter that allows the used to plot a dot corresponding the center of the ellipse [#35]
sora.lightcurve
Property LightCurve.time_mean that returns the mean time of the chord (positive) or the mean time of the observation (negative). [#34]
sora.observer
Function Observer.altaz() that calculates the altitude and azimuth for a given target and instant. [#34]
sora.prediction
Four new parameters were added to plot_occ_map(): path: for the user to select a directory where to save the plots; site_name: If True, the name of the sites will be plotted; chord_delta and chord_geo: for the user to plot the path of a chord from distance of the center or passing by some coordinate, respectively. [#35]
Two methods were added to PredictionTable() to help the user to remove bad events from table: keep_from_selected_images() and remove_occ(). [#35]
API Changes
sora.config
sora.ephem
In EphemKernel, code argument was replaced by spkid. When using ‘code’, a FutureWarning is raised stating code as deprecated and will be removed from v1.0. [#26]
sora.lightcurve
In LightCurve.immersion and LightCurve.emersion, an error will rise when these values were not instanciated or fitted. [#34]
Now the user has the possibility to redefine tref, immersion, emersion, initial_time and end_time after instantiated. [#35]
lambda_0 argument was replaced by central_bandpass and delta_lambda by delta_bandpass. When using ‘lambda_0’ or delta_lambda, a FutureWarning is raised stating lambda_0 or delta_lambda as deprecated and will be removed from v1.0. [#36]
sora.occultation
Occultation.new_astrometric_positions() now shows a warning when time is far by more than 1 day from the occultation closest approach. [#21]
Occultation.to_log() and print(Occultation) added the polar radius, equivalent radius, the Sun-Geocenter-Target angle and the Moon-Geocenter-Target angle, geocentric albedo, the altitude and azimuth of the target for each Observer. [#17]
In fit_ellipse(), pos_angle and dpos_angle were deprecated in favor of position_angle and dposition_angle. [#35]
Changed “GCRS” to “Geocentric” in the string representation to avoid confusion about the reference frame. [#35]
sora.prediction
sora.star
Now Star downloads all parameters from Gaia and saves them in the meta_gaia attribute [#35]
Bug Fixes
sora.ephem
sora.lightcurve
Fixed error that appears when the fit was done separately (immersion and emersion times). Now the final model agrees with the fitted values. [#9]
Fixed error when the file with the light curve has three columns. [#19]
Fixed error when the exptime within the LightCurve was set as zero or negative. [#23]
Fixed error in the automatic mode of LightCurve.normalize(). [#34]
Fixed bug that was raised in LightCurve.log() when there were no initial or end times for lightcurves instantiated with immersion and emersion. [#35]
sora.occultation
Corrected error calculation using err = sqrt(star_err^2 + fit_err^2) [#18]
Occultation.plot_occ_map() now uses the fitted ellipse to calculate the projected shadow radius [#22]
Corrected bug that raised an error when calling Occultation.get_map_sites() and there were no observation added to Occultation. [#31]
Corrected bug that did not save the fitted params in all occultations when more than one occultation was used in fit_ellipse(). [#35]
Added axis_labels and lw (linewidth) to Occultation.plot_chords(). [#35]
sora.prediction
SORA v0.1 (2020/May/20)
Classes
The documentation of all classes and functions are on their docstrings, while the scientific part is presented in the full documentation. Here follows a list with the main Classes:
Ephem Three Classes created to generate geocentric ephemeris for a given solar system object. EphemJPL queries the JPL Horizons service and download ephemeris information. EphemKernel reads the BSP files to calculate the ephemeris using the Spiceypy package. EphemPlanet reads an ASCII file with previously determined positions and interpolate them for a given instant.
JPL Horizons - https://ssd.jpl.nasa.gov/horizons.cgi
Star Class created to deal with the star parameters. From the Gaia-DR2 Source ID or a sky region, it queries the VizieR service and downloads the star’s information. From Gaia DR2 Catalog (Gaia Collaboration 2016a, 2016b and 2018) it gets the RA, DEC, parallax, proper motions, G magnitude and star radius; from the NOMAD Catalog (Zacharias et al. 2004) it gets the B, V, R, J, H and K magnitudes. The user can calculate the ICRS coordinate of the star at any epoch. It can be barycentric (corrected from proper motion) or geocentric (corrected from proper motion and parallax). Also, the apparent diameter of the star is calculated using Gaia DR2 information, or some models such as Van Belle (1999) and Kervella et al. (2004).
Gaia - Gaia Collaboration 2016a, 2016b and 2018 Mission: https://ui.adsabs.harvard.edu/abs/2016A%26A…595A…1G/abstract DR1: https://ui.adsabs.harvard.edu/abs/2016A%26A…595A…2G/abstract DR2: https://ui.adsabs.harvard.edu/abs/2018A%26A…616A…1G/abstract VizieR - https://vizier.u-strasbg.fr/viz-bin/VizieR NOMAD - Zacharias et al. 2004 https://ui.adsabs.harvard.edu/abs/2004AAS…205.4815Z/abstract Van Belle, 1999 - https://ui.adsabs.harvard.edu/abs/1999PASP..111.1515V/abstract Kervella, 2004 - https://ui.adsabs.harvard.edu/abs/2004A%26A…426..297K/abstract
Observer: Object Class created to deal with the observer location. The user can also download the ground-based observatories from the Minor Planet Center (MPC) database.
MPC sites - https://minorplanetcenter.net/iau/lists/ObsCodesF.html
Light Curve: Object Class that receives the observational light curve (with time and the occulted star normalized photometry relative to reference stars) and some observational parameters (filter and exposure time). It has functions to determine the instants that the solar system object enters in front of the star and leaves, (immersion and emersion times, respectively). The model considers a sharp-edge occultation model (geometric) convolved with Fresnel diffraction, stellar diameter (projected at the body distance) and finite integration time (Widemann et al., 2009; Sicardy et al., 2011</font>).
Widemann et al. 2009 - https://ui.adsabs.harvard.edu/abs/2009Icar..199..458W/abstract Sicardy et al. 2011 - https://ui.adsabs.harvard.edu/abs/2011Natur.478..493S/abstract
Occultation: Main Object Class within SORA, created to analyze stellar occultations, and control all the other Object Classes within this package. Its functions allow converting the times for each observatory in the occulted body positions in the sky plane relative to the occulted star (f, g) (IERS Conventions). Also, to obtain the best ellipse parameters (centre position, apparent equatorial radius, oblateness and the position angle of the apparent polar radius) that fit the points. The results are the apparent size, shape and astrometrical position of the occulting body.
IERS Conventions: https://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html
Some extra Objects Classes:
PredictionTable: Using the prediction function within SORA results in an Object Class that is a slight modification of an AstropyTable. The added changes allow to create the occultation map for each prediction, convert into specific formats, such as OccultWatcher and PRAIA (Assafin et al. (2011)).
OccultWatcher - https://www.occultwatcher.net/ Assafin et al., 2011 - https://ui.adsabs.harvard.edu/abs/2011gfun.conf…85A/abstract
ChiSquare: This Object Class is the result of the fitting functions within SORA, such as _LightCurve.occ_lcfit()_ and _Occultation.fit_ellipse()_. This Class has functions that allow viewing the values that minimize the \({\chi^2}\) tests, the uncertainties within \({n\sigma}\), plotting the tests, and saving the values.
INPUTS AND OUTPUTS
INPUTS
Event Related (Star and Ephem)
Object Name or provisory designation
Object Code (only for EphemKernel)
BSP file and name (only for EphemKernel)
DE file and name (only for EphemKernel)
Ephemeris offset for RA and DEC - \({\Delta \alpha \cdot \cos \delta}\), \({\Delta \delta}\) (set as 0,0)
Occultation date and time
Occulted star coordinates RA and DEC; or Gaia code
Star offset for RA and DEC - \({\Delta \alpha \cdot \cos \delta}\), \({\Delta \delta}\) (set as 0,0)
Observer Related
Site name and location (latitude, longitude, and height; or IAU/MPC code)
Light curve file and name; or array with fluxes and times; or immersion and emersion times
Exposure time in seconds
Observational bandwidth in microns (set as 0.7 \({\pm}\) 0.3 microns, Clear)
Fitting Related
Initial guess for light curve fitting: immersion, emersion and opacity.
Range to explore all three parameters
Initial guess for ellipse parameters: center (f,g), equatorial radius, oblateness, and position angle
Range to explore all five parameters
OUTPUTS
Star
Star Gaia-DR2 ID
Star coordinates at 2015.5 and uncertainty - RA and DEC (hh mm ss.sss , +dd mm ss.sss, mas, mas)
Star proper motion - in RA, DEC - and uncertainties (mas/yr)
Star parallax and uncertainty (mas)
Star coordinates propagated to event epoch and uncertainty - RA and DEC (hh mm ss.sss , +dd mm ss.sss, mas, mas)
Star magnitudes G, B, V, R, J, H, K (mag)
Star projected diameter and model (km and mas, model: GDR2, Van Belle, Kervella)
Star offset applied in RA and DEC (mas, mas)
Object and Ephemeris
Object Name
Object radius (km)
Object mass (kg)
Ephemeris kernel (version and DE)
Offset applied in RA/DEC (mas, mas)
Object’s distance (AU)
Object apparent magnitude for the date (mag)
Occultation
Event date and time (yyyy-mm-dd hh:mm:ss.sss)
Closest approach Angle - CA (arcsec)
Reference time (yyyy-mm-dd hh:mm:ss.sss)
Position Angle - PA (degree)
Shadow’s velocity relative to the geocenter (km/s)
Number of positive observations
Number of negative observations
Observer Information
Detection status (positive, negative, overcast, tech. problem, other)
Site Name
Site MPC/IAU code (if any)
Site coordinates - Latitude, Longitude and height (dd mm ss.s ; dd mm ss.s ; m)
Light curve file name
Number of images (lines in LC)
Light curve fitting information (for each positive detection)
Acquisition start time (yyyy-mm-dd hh:mm:ss.sss)
Acquisition end time (yyyy-mm-dd hh:mm:ss.sss)
Exposure time (s)
Cycle time (s)
Time offset applied in LC (s)
Light curve calculated RMS
Calculated normalised flux and bottom flux (standard = 1, 0)
Band width and uncertainty (microns)
Shadow’s velocity relative to the station (km/s)
Fresnel scale (s and km)
Projected stellar size scale (s and km)
Integration time scale (s and km)
Dead time scale (s and km)
Model resolution - size of synthetic LC point (s and km)
Immersion Time and uncertainty (yyyy-mm-dd hh:mm:ss.sss +/- s.sss)
Immersion Time and uncertainty - \({1\sigma}\) and \({3\sigma}\) (s)
Emersion Time and uncertainty (yyyy-mm-dd hh:mm:ss.sss +/- s.sss)
\({\chi^2}\) fit model
Emersion Time and uncertainty - \({1\sigma}\) and \({3\sigma}\) (s)
Minimum Chi-square - \({\chi^2_{min}}\)
Number of fitted points for im- and emersion
Number of fitted parameters
Minimum Chi-square per degree of freedom - \({\chi^2_{min-pdf}}\)
Elipse fit procedure
Fitted parameters: Equatorial radius and uncertainty (km); Center position (\({f_0}\), \({g_0}\)) and \({1\sigma}\) uncertainties (km, km); Oblateness and uncertainty; Position angle and uncertainty (degree)
Minimum Chi-square - \({\chi_{min}^2}\)
Minimum Chi-square per degree of freedom - \({\chi_{min-pdf}^2}\)
Number points used to fit ( X points from Y chords )
Astrometric object center position at occ. time and uncertainty (hh mm ss.sss +dd mm ss.sss \({\pm}\) mas)
Plots and files (some are optional)
Prediction map (Lucky Star model)
Normalised light curve - for each site (x = time; y = flux)
Chi-square map for immersion and emersion times (x = time; y = \({\chi^2}\))
Light curve and synthetic LC- for each site (x = time; y = flux)
Chords projected in sky plane (x = \({\xi}\) (km); y = \({\eta}\) (km) )
Chi-square map for each ellipse parameter (x = time; y = \({\chi^2_{param}}\))
Chords projected in sky plane and the best ellipse fitted with \({1\sigma}\) uncertainties (x = \({\xi}\) (km); y = \({\eta}\) (km))
Log file with all information