sora.star

The Star Class

class sora.Star(catalogue='gaiadr3_linea', **kwargs)[source]

Defines a star.

Parameters:

catalogue (str, Catalogue) – The catalogue to download data. It can be 'gaiadr2', 'gaiaedr3', 'gaiadr3', 'gaiadr3_linea', or a Catalogue object, default=’gaiadr3_linea’.
code (str) – Gaia source identifier used for catalogue searches.
coord (str, astropy.coordinates.SkyCoord) – If code is not given, coord must have the coordinates RA and DEC of the star to search in the catalogue: 'hh mm ss.ss +dd mm ss.ss'.
ra (int, float, astropy.units.Quantity) – Right ascension. Numeric values are interpreted as hour angle.
dec (int, float, astropy.units.Quantity) – 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, default=True) – If True, it tries to download the magnitudes from NOMAD catalogue.
bjones (bool, default=False) – If True, it uses the star distance from Bailer-Jones et al. (2018).
cgaudin (bool, default=True) – If True, it uses the proper motion correction from Cantat-Gaudin & Brandt (2021). This option is only available for Gaia EDR3/DR3.
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.

add_offset(da_cosdec, ddec)[source]

Adds an offset to the star position.

Parameters:

da_cosdec (int, float) – Offset in delta_alpha_cos_delta, in mas.
ddec (int, float) – Offset in delta_delta, in mas.

apparent_diameter(distance, mode='auto', band='V', star_type='sg', verbose=True)[source]

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 the user-defined 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, default=’V’) – Band filter used to calculate the diameter. If mode is 'kervella' or 'van_belle', the filter must be 'B' or 'V'. If mode is 'auto', 'V' is selected.
star_type (str, default=’sg’) –
Type of star used 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, default=True) – If True, it prints the mode used by auto.

Returns:

diameter – Apparent stellar diameter at the given distance, in km.

Return type:

astropy.units.Quantity

barycentric(time)[source]

Calculates the position of the star using proper motion.

Parameters:: time (str, astropy.time.Time) – Reference time to apply proper motion. It can be a string in the ISO format (yyyy-mm-dd hh:mm:ss.s) or an astropy Time object.
Returns:: coord – Barycentric star coordinate at the given time.
Return type:: astropy.coordinates.SkyCoord

error_at(time)[source]

Estimates the star position error at a given time.

Parameters:: time (str, astropy.time.Time, iterable) – Reference time to propagate the star error. It can be a string in the ISO format (yyyy-mm-dd hh:mm:ss.s), an astropy Time object, or a list of values accepted by astropy.time.Time.
Returns:: errors – Position errors in RA*cos(DEC) and DEC, in mas. For vector times, each element contains the error at the corresponding time.
Return type:: tuple

geocentric(time)[source]

Calculates the geocentric star position using parallax and proper motion.

Parameters:: time (str, 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.
Returns:: coord – Geocentric star coordinate at the given time.
Return type:: astropy.coordinates.SkyCoord

get_position(time, observer='geocenter')[source]

Calculates the star position for a given observer and time.

Parameters:

time (str, float, astropy.time.Time, iterable) – 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), an astropy Time object, or a list of values accepted by astropy.time.Time.
observer (str, sora.observer.Observer, sora.observer.Spacecraft, default=’geocenter’) – Observer used to calculate the star position. It can be 'geocenter' for a geocentric coordinate, 'barycenter' for a barycentric coordinate, or a SORA observer object.

Returns:

coord – Astropy SkyCoord object with the star coordinates at the given time.

Return type:

astropy.coordinates.SkyCoord

kervella()[source]

Determines the diameter of a star in mas using equations from Kervella et al. (2004).

See: Astronomy & Astrophysics, 426, 297-307.

Returns:: diameter – Angular diameters by band.
Return type:: dict

set_diameter(diameter)[source]

Sets a user-defined diameter for the star, in mas.

Parameters:: diameter (int, float) – User-defined angular diameter of the star, in mas.

set_magnitude(**kwargs)[source]

Sets the magnitudes of a star.

Parameters:: **kwargs (float) – Magnitude values keyed by band name. 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)

to_log(namefile)[source]

Saves the star log to a file.

Parameters:: namefile (str) – File path where the log will be saved.

van_belle()[source]

Determines the diameter of a star in mas using equations from van Belle (1999).

See: Publications of the Astronomical Society of the Pacific, 111, 1515-1523.

Returns:: diameter – Angular diameters by stellar type and band.
Return type:: dict

The Star Catalogue

class sora.star.catalog.VizierCatalogue(**kwargs)[source]

Defines parameters needed to download star information from VizieR.

Parameters:

name (str) – Name of the catalogue used by other processes.
cat_path (str) – The path of the catalogue in the Vizier website. For instance, for GaiaEDR3, cat_path='I/350/gaiaedr3'
code (str) – Column name for the unique source identifier within the catalogue.
ra (str) – Column name for right ascension within the catalogue.
dec (str) – Column name for declination within the catalogue.
epoch (str, astropy.time.Time) – The epoch of the catalogue. If it is defined in the catalogue, just pass the keyword within the catalogue. If the epoch is not present in the catalogue table, we must pass a Time object directly, for example epoch=Time('J2000'), which defines the catalogue coordinates in J2000 TDB.
pmra (str, optional) – Column name for the proper motion in RA*cos(DEC) within the catalogue. If not available, set it to None.
pmdec (str, optional) – Column name for the proper motion in DEC within the catalogue. If not available, set it to None.
parallax (str, optional) – Column name for parallax within the catalogue. If not available, set it to None.
rad_vel (str, optional) – Column name for radial velocity within the catalogue.
band (dict [str, str], optional) – A dictionary where the key is band name and the value is the keyword referring to the band within the catalogue. For instance, in Gaia: band={'G': 'Gmag'}. If not available, set it to None.
errors (list [str], optional) – A list with the 6 keywords that refer to the uncertainty parameters within the catalogue in the order: [ra, dec, pmra, pmdec, parallax, rad_vel]. If some parameters are not available, please pass each one as None. Ex: errors=['eRA', 'eDEC', None, None, None, None], or errors=None if none of the errors is available.

Examples

To define the Gaia-EDR3 catalogue with VizierCatalogue, define an object like:

>>> catalogue = VizierCatalogue(name='GaiaEDR3', cat_path='I/350/gaiaedr3', code='Source', ra='RA_ICRS', dec='DE_ICRS',
>>>                             pmra='pmRA', pmdec='pmDE', epoch='Epoch', parallax='Plx', rad_vel='RVDR2', band={'G': 'Gmag'},
>>>                             errors=['e_RA_ICRS', 'e_DE_ICRS', 'e_pmRA', 'e_pmDE', 'e_Plx', 'e_RVDR2'])

parse_catalogue(table)

Parses a catalogue table into SORA star parameters.

Parameters:: table (astropy.table.Table) – Table with the parameters read from the catalogue server.
Returns:: cat_info – Dictionary with catalogue parameters converted to SORA names and units.
Return type:: dict

search_region(coord, radius=None, width=None, height=None, columns=None, row_limit=10000000, timeout=600, **kwargs)[source]

Searches the catalogue around a sky position.

Parameters:

coord (str, astropy.coordinates.SkyCoord) – Target around which to search. It may be specified as a string, in which case it is resolved using online services or as the appropriate astropy SkyCoord object. ICRS coordinates may also be entered as a string.
radius (number) – Radius of the circular region to query.
width (number) – Width of the square or rectangular region to query.
height (number) – When set in addition to width, the queried region becomes rectangular, with the specified width and height.
columns (list) – List of strings with the keywords to fetch from the catalogue. If columns=None it will download all the columns. If columns="simple" it will download only the columns for the code, epoch and astrometric parameters.
row_limit (int) – Maximum number of rows that will be fetched from the result (set to -1 for unlimited). Default: row_limit=10_000_000.
timeout (number) – Timeout for connecting to server in seconds. Default: timeout=600.
**kwargs – Additional keyword arguments passed to astroquery.vizier.Vizier.

Returns:

catalogue – Query result with catalogue information about the stars.

Return type:

astroquery.utils.commons.TableList

search_star(code=None, coord=None, radius=None)[source]

Searches for a specific star in the catalogue.

Parameters:

code (str) – Unique source identifier of the star.
coord (str, astropy.coordinates.SkyCoord) – Target coordinate to search. It may be specified as a string, in which case it is resolved using online services or as the appropriate astropy SkyCoord object. ICRS coordinates may also be entered as a string.
radius (number) – Radius of the circular region to query.

Returns:

catalogue – Query result with catalogue information about the star.

Return type:

astroquery.utils.commons.TableList

Raises:

ValueError – Raised when code or (coord, radius) are not provided.

Notes

This function must be called in one of the following ways:

Using code if the unique id of the star is known

Using coord and radius if the catalogue position is known.

If both alternatives are provided, only the first is used.

Complementary functions

sora.star.utils.kervella(magB=None, magV=None, magK=None)[source]

Determines the diameter of a star in mas using equations from Kervella et al. (2004).

See: Astronomy & Astrophysics, 426, 297-307.

Parameters:

magB (float, default=None) – The magnitude B of the star.
magV (float, default=None) – The magnitude V of the star.
magK (float, default=None) – The magnitude K of the star.

Returns:

diameter – Angular diameters by band.

Return type:

dict

Notes

If any of those values is ‘None’, ‘nan’ or higher than 49, it is not considered.

sora.star.utils.van_belle(magB=None, magV=None, magK=None)[source]

Determines the diameter of a star in mas using equations from van Belle (1999).

See: Publications of the Astronomical Society of the Pacific, 111, 1515-1523.

Parameters:

magB (float, default=None) – The magnitude B of the star.
magV (float, default=None) – The magnitude V of the star.
magK (float, default=None) – The magnitude K of the star.

Returns:

diameter – Angular diameters by stellar type and band.

Return type:

dict

Notes

If any of those values is ‘None’, ‘nan’ or higher than 49, it is not considered.