Star Class
The Star Class within SORA was created to deal with the star information. The documentation here contains the details about every step.
This Jupyter-Notebook was designed as a tutorial for how to work with the Star Class. Any further question, please contact the core team: Altair Ramos Gomes Júnior, Bruno Eduardo Morgado, Gustavo Benedetti Rossi, and Rodrigo Carlos Boufleur.
The Star Docstring was designed to help the users. Also, each function has its Docstring containing its main purpose and the needed parameters (physical description and formats). Please, do not hesitate to use it.
0. Index
[1]:
## import the Star Class
from sora.star import Star
## To facilitate, sora allows to import Star directly from the root
from sora import Star
SORA version: 0.3
1. Instantiating Star Object
The Star Class can be instantiated in different ways. Using the Gaia-DR2 or Gaia-EDR3 Source ID, then all the informations of the stars (RA, DEC, parallax, proper motions, G magnitude and star radius) will be downloaded from VizieR. Using a coordinate, then the Gaia-EDR3 (or Gaia-DR2) star will be searched in VizieR within a radius of 2 arcsec. If more than 1 star is found, the user will be asked to choose the correct one.
Star can also download the B, V, R, J, H and K magnitudes from the NOMAD catalogue. This is useful for calculating the apparent diameter of a star using van Belle’s or Kevella’s methods. If more than 1 star is found within 2 arcsec from the given coordinate, the user will be asked to choose the correct one.
[2]:
Star?
Init signature: Star(catalogue='gaiadr3', **kwargs)
Docstring:
Defines a star.
Parameters
----------
catalogue : `str`, `VizierCatalogue`
The catalogue to download data. It can be ``'gaiadr2'``, ``'gaiaedr3'``,
``'gaiadr3'``, or a VizierCatalogue object.. default='gaiadr3'
code : `str`
Gaia Source code for searching in VizieR.
coord : `str`, `astropy.coordinates.SkyCoord`
If code is not given, coord nust have the coordinates RA and DEC of the
star to search in VizieR: ``'hh mm ss.ss +dd mm ss.ss'``.
ra : `int`, `float`
Right Ascension, in deg.
dec : `int`, `float`
Declination, in deg.
parallax : `int`, `float`. default=0
Parallax, in mas.
pmra : `int`, `float`, default=0
Proper Motion in RA*, in mas/year.
pmdec : `int`, `float`, default=0
Proper Motion in DEC, in mas/year.
rad_vel : `int`, `float`, default=0
Radial Velocity, in km/s.
epoch : `str`, `astropy.time.Time`, default='J2000'
Epoch of the coordinates.
nomad : `bool`
If True, it tries to download the magnitudes from NOMAD catalogue.
bjones : `bool`, default=True
If True, it uses de star distance from Bailer-Jones et al. (2018).
cgaudin : `bool`, default=True
If True, it uses de proper motion correction from Cantat-Gaudin & Brandt (2021).
this option is only available for Gaia-EDR3.
verbose : `bool`, default=True
If True, it prints the downloaded information
local : `bool`, default=False
If True, it uses the given coordinate in 'coord' as final coordinate.
Note
----
The user can give either 'coord' or 'ra' and 'dec', but not both.
To download the coordinates from Gaia, "local" must be set as False
and the ("code") or ("coord") or ("ra" and "dec") must be given.
All values downloaded from Gaia will replace the ones given by the user.
File: ~/Documentos/códigos/SORA/sora/star/core.py
Type: type
Subclasses:
Searching by Gaia Source ID
[3]:
star = Star(code='6306109685386306688')
1 GaiaDR3 star found band={'G': 15.341292}
star coordinate at J2016.0: RA=15h04m17.67141s +/- 0.0307 mas, DEC=-16d19m38.9718s +/- 0.0241 mas
Downloading star parameters from I/297/out
[4]:
print(star)
GaiaDR3 star Source ID: 6306109685386306688
ICRS star coordinate at J2016.0:
RA=15h04m17.67141s +/- 0.0307 mas, DEC=-16d19m38.9718s +/- 0.0241 mas
pmRA=6.286 +/- 0.040 mas/yr, pmDEC=-9.632 +/- 0.033 mas/yr
GaiaDR3 Proper motion corrected as suggested by Cantat-Gaudin & Brandt (2021)
Plx=0.8595 +/- 0.0332 mas, Rad. Vel.=0.00 +/- 0.00 km/s
Magnitudes: G: 15.341, B: 15.460, V: 14.680, R: 15.240, J: 14.121, H: 13.773,
K: 13.643
Apparent diameter from Kervella et. al (2004):
V: 0.0074 mas, B: 0.0077 mas
Apparent diameter from van Belle (1999):
sg: B: 0.0090 mas, V: 0.0092 mas
ms: B: 0.0086 mas, V: 0.0069 mas
vs: B: 0.0135 mas, V: 0.0120 mas
Searching by coordinate
[5]:
star2 = Star(coord='18 22 00.25777 -22 28 10.7057')
2 stars were found within 2 arcsec from given coordinate.
The list below is sorted by distance. Please select the correct star
num dist(") Gmag RA___ICRS___DEC
--- ------- ------ ------------------------------
1 0.022 15.589 18h22m00.2584s -22d28m10.6860s
2 2.009 19.981 18h22m00.3855s -22d28m09.7559s
0: Cancel
Choose the corresponding number of the correct star: 1
1 GaiaDR3 star found band={'G': 15.589052}
star coordinate at J2016.0: RA=18h22m00.25843s +/- 0.0357 mas, DEC=-22d28m10.6860s +/- 0.0313 mas
Downloading star parameters from I/297/out
2 stars were found within 2 arcsec from given coordinate.
The list below is sorted by distance. Please select the correct star
num dist(") Bmag Vmag Rmag Jmag Hmag Kmag RA___ICRS___DEC
--- ------- ------ ------ ------ ------ ------ ------ ------------------------------
1 0.718 17.600 nan nan nan nan nan 18h22m00.2627s -22d28m09.9700s
2 1.774 18.330 nan 14.500 12.419 11.471 11.128 18h22m00.1313s -22d28m10.8901s
0: Cancel
Choose the corresponding number of the correct star: 1
Magnitudes in ['V', 'R', 'J', 'H', 'K'] were not located in NOMAD
[6]:
print(star2)
GaiaDR3 star Source ID: 4089802618196107776
ICRS star coordinate at J2016.0:
RA=18h22m00.25843s +/- 0.0357 mas, DEC=-22d28m10.6860s +/- 0.0313 mas
pmRA=-3.564 +/- 0.045 mas/yr, pmDEC=-8.035 +/- 0.033 mas/yr
GaiaDR3 Proper motion corrected as suggested by Cantat-Gaudin & Brandt (2021)
Plx=0.1181 +/- 0.0377 mas, Rad. Vel.=-79.08 +/- 7.97 km/s
Magnitudes: G: 15.589, B: 17.600
Note that there are warnings if it does not find some information (in this case, the magnitudes from NOMAD)
By default, the Star object will search by a Gaia-DR3 star. However, the user can also set that Gaia-DR2 catalogue should be used instead.
[7]:
star_3 = Star(code='6306109685386306688', catalogue='gaiadr2')
1 GaiaDR2 star found band={'G': 15.3528}
star coordinate at J2015.5: RA=15h04m17.67119s +/- 0.0432 mas, DEC=-16d19m38.9668s +/- 0.0309 mas
Downloading star parameters from I/297/out
[8]:
s = Star(coord='15 04 17.6 -16 19 38.9')
1 GaiaDR3 star found band={'G': 15.341292}
star coordinate at J2016.0: RA=15h04m17.67141s +/- 0.0307 mas, DEC=-16d19m38.9718s +/- 0.0241 mas
Downloading star parameters from I/297/out
[9]:
print(s)
GaiaDR3 star Source ID: 6306109685386306688
ICRS star coordinate at J2016.0:
RA=15h04m17.67141s +/- 0.0307 mas, DEC=-16d19m38.9718s +/- 0.0241 mas
pmRA=6.286 +/- 0.040 mas/yr, pmDEC=-9.632 +/- 0.033 mas/yr
GaiaDR3 Proper motion corrected as suggested by Cantat-Gaudin & Brandt (2021)
Plx=0.8595 +/- 0.0332 mas, Rad. Vel.=0.00 +/- 0.00 km/s
Magnitudes: G: 15.341, B: 15.460, V: 14.680, R: 15.240, J: 14.121, H: 13.773,
K: 13.643
Apparent diameter from Kervella et. al (2004):
V: 0.0074 mas, B: 0.0077 mas
Apparent diameter from van Belle (1999):
sg: B: 0.0090 mas, V: 0.0092 mas
ms: B: 0.0086 mas, V: 0.0069 mas
vs: B: 0.0135 mas, V: 0.0120 mas
2. Changing or including magnitudes
If one necessary magnituge in a specific band is not found in NOMAD or the user wants to add a different value to be saved in the Star history, it can be done with set_magnitude
[10]:
star.set_magnitude?
Signature: star.set_magnitude(**kwargs)
Docstring:
Sets the magnitudes of a star.
Parameters
----------
band=value : `str`
The star magnitude for given band. The band name can be any string
the user wants.
Examples
--------
To set the stars magnitude in the band G:
>>> set_magnitude(G=10)
To set the star's magnitude in the band K:
>>> set_magnitude(K=15)
To set the star's magnitude in a customized band:
>>> set_magnitude(newband=6)
File: ~/Documentos/códigos/SORA/sora/star/core.py
Type: method
[11]:
# Changing an already existing band will show a warning, but the change is done.
star.set_magnitude(V=14)
/home/altair/Documentos/códigos/SORA/sora/star/core.py:153: UserWarning: V mag already defined. V=14.680000305175781 will be replaced by V=14.0
warnings.warn('{0} mag already defined. {0}={1} will be replaced by {0}={2}'.format(
[12]:
star.mag
[12]:
{'G': 15.341292,
'B': 15.460000038146973,
'V': 14.0,
'R': 15.239999771118164,
'J': 14.121000289916992,
'H': 13.77299976348877,
'K': 13.642999649047852}
set_magnitude does not have any pre-set band name, so the user can give whatever the name of the band. It must a string though.
[13]:
star2.set_magnitude(x_ray=15, ultraviolet=10)
[14]:
star2.mag
[14]:
{'G': 15.589052, 'B': 17.600000381469727, 'x_ray': 15.0, 'ultraviolet': 10.0}
3. Propagated positions
If the proper motion and parallax is found in the Gaia catalogue, the user can see the ICRS coordinate of the star at any epoch. It can be barycentric (corrected from proper motion), geocentric (corrected from proper motion and parallax), or for any Observer object.
The returned variable is an Astropy SkyCoord object.
[15]:
# The coord attribute shows the values kept for the star in RA, DEC, distance, proper motion and radial velocity
print(star2.coord)
<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, pc)
(275.50107681, -22.46963499, 8467.40050804)>
[16]:
print(star2.coord.to_string('hmsdms'))
18h22m00.25843459s -22d28m10.68596368s
[17]:
star2.get_position?
Signature: star2.get_position(time, observer='geocenter')
Docstring:
Calculates the position of the star for given observer,
propagating the position using parallax and proper motion
Parameters
----------
time : `float`, `astropy.time.Time`
Reference time to apply proper motion and calculate parallax. It can be a string
in the ISO format (yyyy-mm-dd hh:mm:ss.s) or an astropy Time object.
observer : `str`, `sora.observer.Observer`, `sora.observer.Spacecraft`
Observer of the star t calculate position. It can be 'geocenter' for a geocentric
coordinate, 'barycenter' for a barycenter coordinate, or a sora observer object.
Returns
-------
coord : `astropy.coordinates.SkyCoord`
Astropy SkyCoord object with the star coordinates at the given time.
File: ~/Documentos/códigos/SORA/sora/star/core.py
Type: method
[18]:
pos = star2.get_position(time='2020-05-15 00:00:00', observer='barycenter')
print(pos.to_string('hmsdms', precision=10))
18h22m00.2573114293s -22d28m10.7210625154s
[19]:
pos = star2.get_position(time='2020-05-15 00:00:00', observer='geocenter')
print(pos.to_string('hmsdms', precision=10))
18h22m00.2573170776s -22d28m10.7210581733s
[20]:
from sora import Observer
opd = Observer(name='Pico dos Dias Observatory', code='874')
pos = star2.get_position(time='2020-05-15 00:00:00', observer=opd)
print(pos.to_string('hmsdms', precision=10))
18h22m00.2573170779s -22d28m10.7210581716s
The position error projected at epoch can also be called out. This is done using the formalism proposed by Butkevich et al., 2014, using the parameters and covariance matrix from Gaia catalogue (EDR3 or DR2).
[21]:
star2.error_at(time='2020-05-15 00:00:00')
[21]:
(<Quantity 0.14513241 mas>, <Quantity 0.15681425 mas>)
4. Adding offsets
The Gaia coordinate is expected to be the most precise coordinate published so far. However, if the user has the need to add an offset to the coordinate, it can be done with add_offset. The input values must be in \(\Delta\alpha\cos\delta\) and \(\Delta\delta\), in mas. The application of the offset is done only in the geocentric function.
[22]:
star2.get_position(time='2020-05-15 00:00:00', observer='geocenter').to_string('hmsdms')
[22]:
'18h22m00.25731708s -22d28m10.72105817s'
[23]:
star2.add_offset(40,50)
[24]:
star2.get_position(time='2020-05-15 00:00:00', observer='geocenter').to_string('hmsdms')
[24]:
'18h22m00.26020282s -22d28m10.67105817s'
5. The Apparent Diameter of the star
SORA is able to calculate the apparent diameter of a star at a given distance using the star radius of the Gaia catalogue or the angular diameter calculated from the methods of Kervella (2004) or van Belle (1999). These functions can be used alone, or within the Star object.
[25]:
from sora.star import kervella, van_belle
The functions will return the diameter calculated for B and V magnitudes, in mas
[26]:
kervella(magB=10, magV=11, magK=10)
[26]:
{'V': <Quantity 0.03912911 mas>, 'B': <Quantity 0.03280198 mas>}
In the case of van_belle function, the result is given for Super Giant “sg”, Main Sequence “ms” and Variable Star “vs”
[27]:
van_belle(magB=10, magV=11, magK=10)
[27]:
{'sg': {'B': <Quantity 0.04446313 mas>, 'V': <Quantity 0.04920395 mas>},
'ms': {'B': <Quantity 0.03162278 mas>, 'V': <Quantity 0.03664376 mas>},
'vs': {'B': <Quantity 0.0691831 mas>, 'V': <Quantity 0.06412096 mas>}}
If a Star object is defined and the B, V and K magnitudes are defined, it can be directly called as:
[28]:
star.kervella()
[28]:
{'V': <Quantity 0.00653663 mas>, 'B': <Quantity 0.00766495 mas>}
[29]:
star.van_belle()
[29]:
{'sg': {'B': <Quantity 0.00903109 mas>, 'V': <Quantity 0.00888405 mas>},
'ms': {'B': <Quantity 0.00860855 mas>, 'V': <Quantity 0.00622656 mas>},
'vs': {'B': <Quantity 0.01353278 mas>, 'V': <Quantity 0.01166342 mas>}}
For a Star object, to see the apparent diameter, in km, at a given distance, the apparent_diameter method can be used.
If no parameter is given, the source will be automatically chosen given the following sequence:
- A value given by the user
- The star radius obtained from Gaia.
- The apparent diameter calculated from Kervella at V band
- The apparent diameter calculated from van Belle at V band for a Super Giant star.
[30]:
star.apparent_diameter?
Signature:
star.apparent_diameter(
distance,
mode='auto',
band='V',
star_type='sg',
verbose=True,
)
Docstring:
Calculates the apparent diameter of the star at a given distance.
Parameters
----------
distance : `int`, `float`
Object geocentric distance, in AU.
mode : `str`, default='auto'
The mode to calculate the apparent diameter.
- ``'user'``: calculates using user given diameter.
- ``'gaia'``: calculates using diameter obtained from Gaia.
- ``'kervella'``: calculates using Kervella equations.
- ``'van_belle'``: calculates using van Belle equations.
- ``'auto'``: tries all the above methods until it is able to calculate diameter.
The order of try is the same as shown above (user, Gaia, Kervella, Van Belle).
band : `str`
The band filter to calculate the diameter. If mode is `kervella`
or `van_belle`, the filter must be given, ``'B'`` or ``'V'``.
If mode `auto`, ``'V'`` is selected.
star_type :`str`
Type of star to calculate the diameter. If mode is `van_belle`,
the star type must be given. If mode is `auto`, ``star_type='sg'``.
Accepted types:
- ``'sg'`` for 'Super Giant'.
- ``'ms'`` for 'Main Sequence'.
- ``'vs'`` for 'Variable Star'.
verbose : `bool`
If True, it prints the mode used by `auto`.
File: ~/Documentos/códigos/SORA/sora/star/core.py
Type: method
[31]:
star.apparent_diameter(distance=9) #Distance in AU
Apparent diameter using Kervella et al. (2004)
[31]:
To set an user diameter, in mas
[32]:
star.set_diameter(diameter=0.05)
[33]:
star.apparent_diameter(distance=9)
Calculating apparent diameter from user defined diameter
[33]:
To choose the source of calculation, just select in the mode parameter. If mode='kervella', the user must give ‘band’ as ‘B or ‘V’. If mode='van_belle', the user must give the band and the type of star in star_type as ‘sg’, ‘ms’, or ‘vs’. If not given, band='V' and star_type='sg'.
[34]:
star.apparent_diameter(distance=9.5, mode='kervella')
Apparent diameter using Kervella et al. (2004)
[34]:
[35]:
star.apparent_diameter(distance=9.5, mode='van_belle', band='B', star_type='ms')
Apparent diameter using van Belle (1999)
[35]:
This Jupyter-Notebook was designed as a tutorial for how to work with the Star 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