GaiaData#

class pyia.GaiaData(data, distance_colname='parallax', distance_error_colname='parallax_error', distance_unit=None, radial_velocity_colname='radial_velocity', radial_velocity_error_colname='radial_velocity_error', radial_velocity_unit=None, **kwargs)#

Bases: object

The main class for loading and interacting with data from the Gaia mission. This should work with Gaia catalog data from any data release, i.e., DR1 gaia_source or TGAS, or DR2, EDR3, DR3 gaia_source tables.

Parameters:

data (Union[Table, str, Path, Dict[str, Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]]) – The input Gaia data set, either as a pre-loaded table, data frame, or dictionary of columns, or a filename to load. The filename can point to any file format that can be read by astropy.table.Table.
distance_colname (str) – The name of the column to use for distance. Defaults to parallax. This is useful if you use a non-Gaia column for distance.
distance_error_colname (str) – The name of the column to use for distance error. Defaults to parallax_error.
distance_unit (Union[Unit, str, None]) – The Astropy unit of the distance column. Defaults to u.mas. For example, if you use the Bailer-Jones distances, you should set this to u.pc.
radial_velocity_colname (str) – The name of the column to use for radial velocity. Defaults to radial_velocity. This is useful if you use a non-Gaia column for radial velocity, such as from a spectroscopic survey that is cross-matched to Gaia.
radial_velocity_error_colname (str) – The name of the column to use for radial velocity error. Defaults to radial_velocity_error.
radial_velocity_unit (Union[Unit, str, None]) – The Astropy unit of the radial velocity column. Defaults to u.km/u.s.
**kwargs (Any) – Any additional keyword arguments are passed to astropy.table.Table read().

Attributes Summary

`distance`	Assumes 1/parallax.
`distmod`	Distance modulus
`skycoord`	Return an `SkyCoord` object to represent all coordinates.
`vtan`	Tangential velocity computed using the proper motion and inverse parallax as the distance.

Methods Summary

`filter`(**kwargs)	Filter the data based on columns and data ranges.
`from_query`(query_str[, login_info, verbose])	Run the specified query and return a `GaiaData` instance with the returned data.
`from_source_id`(source_id[, source_id_dr, ...])	Retrieve data from a DR for a given Gaia source_id in a DR.
`get_BP0`(**kwargs)	Return the extinction-corrected G_BP magnitude.
`get_G0`(**kwargs)	Return the extinction-corrected G-band magnitude.
`get_RP0`(**kwargs)	Return the extinction-corrected G_RP magnitude.
`get_abs_mag`([mag_name])	Return the absolute magnitude.
`get_cov`([RAM_threshold, coords, units, ...])	The Gaia data tables contain correlation coefficients and standard deviations for (ra, dec, parallax, pm_ra, pm_dec), but for most analyses we need covariance matrices.
`get_distance`([min_parallax, fill_value, ...])	Compute distance from parallax (by inverting the parallax) using `Distance`.
`get_ebv`([dustmaps_cls])	Compute the E(B-V) reddening at this location
`get_error_samples`([size, rng])	Generate a sampling from the Gaia error distribution for each source.
`get_ext`([ebv, dustmaps_cls])	Compute the E(B-V) reddening at this location
`get_pm`([frame])	Get the 2D proper motion array in the specified frame
`get_radial_velocity`([fill_value])	Return radial velocity but with invalid values filled with the specified fill value.
`get_ruwe`()	rtype: `None`
`get_skycoord`([distance, radial_velocity, ...])	Return an `SkyCoord` object to represent all coordinates.
`get_uwe`()	Compute and return the unit-weight error.

Attributes Documentation

distance#

Assumes 1/parallax. Has shape (nrows,).

This attribute will raise an error when there are negative or zero parallax values. For more flexible retrieval of distance values and auto-filling bad values, use the .get_distance() method.

distmod#: Distance modulus

skycoord#

Return an SkyCoord object to represent all coordinates. Note: this requires Astropy v3.0 or higher!

Use the get_skycoord() method for more flexible access.

vtan#: Tangential velocity computed using the proper motion and inverse parallax as the distance. Has shape (nrows, 2)

Methods Documentation

filter(**kwargs)#

Filter the data based on columns and data ranges.

Parameters:: **kwargs (Any) – Keys should be column names, values should be tuples representing ranges to select the column values withing. For example, to select parallaxes between 0.5 and 5, pass parallax=(0.5, 5)*u.mas. Pass None to skip a filter, for example parallax=(None, 5*u.mas) would select all parallax values < 5 mas.
Returns:: The same data table, but filtered.
Return type:: GaiaData

classmethod from_query(query_str, login_info=None, verbose=False)#

Run the specified query and return a GaiaData instance with the returned data.

This is meant only to be used for quick queries to the main Gaia science archive. For longer queries and more customized usage, use TAP access to any of the Gaia mirrors with, e.g., astroquery or pyvo.

This requires astroquery to be installed.

Parameters:

query_str (str) – The string ADQL query to execute.
login_info (Optional[Dict[str, str]]) – Username and password for the Gaia science archive as keys “user” and “password”. If not specified, will use anonymous access, subject to the query limits.
verbose (bool) –

Returns:

An instance of this object.

Return type:

GaiaData

classmethod from_source_id(source_id, source_id_dr=None, data_dr=None, **kwargs)#

Retrieve data from a DR for a given Gaia source_id in a DR.

Useful if you have, e.g., a DR2 source_id and want EDR3 data.

Parameters:

source_id (int) – The Gaia source_id
source_id_dr (Optional[str]) – The data release slug (e.g., ‘dr2’ or ‘edr3’) for the input source_id. Defaults to the latest data release.
data_dr (Optional[str]) – The data release slug (e.g., ‘dr2’ or ‘edr3’) to retrieve data from. Defaults to the latest data release.
**kwargs (Any) – Passed to from_query()

Returns:

An instance of this object.

Return type:

GaiaData

get_BP0(**kwargs)#

Return the extinction-corrected G_BP magnitude. Any arguments are passed to get_ext().

Parameters:: kwargs (Any) –
Return type:: Quantity

get_G0(**kwargs)#

Return the extinction-corrected G-band magnitude. Any arguments are passed to get_ext().

Parameters:: kwargs (Any) –
Return type:: Quantity

get_RP0(**kwargs)#

Return the extinction-corrected G_RP magnitude. Any arguments are passed to get_ext().

Parameters:: kwargs (Any) –
Return type:: Quantity

get_abs_mag(mag_name='phot_g_mean_mag')#

Return the absolute magnitude.

Parameters:: mag_name (str) –
Return type:: Quantity

get_cov(RAM_threshold=<Quantity 1. Gbyte>, coords=None, units=None, warn_missing_corr=False)#

The Gaia data tables contain correlation coefficients and standard deviations for (ra, dec, parallax, pm_ra, pm_dec), but for most analyses we need covariance matrices. This converts the data provided by Gaia into covariance matrices.

If a radial velocity exists, this also contains the radial velocity variance. If radial velocity doesn’t exist, that diagonal element is set to inf.

The default units of the covariance matrix are [degree, degree, mas, mas/yr, mas/yr, km/s], but this can be modified by passing in a dictionary with new units. For example, to change just the default ra, dec units for the covariance matrix, you can pass in:

units=dict(ra=u.radian, dec=u.radian)

Parameters:

RAM_threshold (Quantity) – Raise an error if the expected covariance array is larger than the specified threshold. Set to None to disable this checking.
coords (Optional[List[str]]) –
units (Optional[Dict[str, Unit]]) –
warn_missing_corr (bool) –

Return type:

Tuple[ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], Dict[str, Unit]]

Returns:

ndarray – The covariance matrix with shape (nrows, 6, 6).
dict – A dictionary of the units of the covariance matrix rows/columns.

get_distance(min_parallax=None, fill_value=nan, allow_negative=False)#

Compute distance from parallax (by inverting the parallax) using Distance.

Parameters:

min_parallax (Optional[Quantity]) – If min_parallax specified, the parallaxes are clipped to this values (and it is also used to replace NaNs).
fill_value (float) –
allow_negative (bool) – This is passed through to Distance.

Returns:

A Distance object with the data.

Return type:

Distance

get_ebv(dustmaps_cls=None)#

Compute the E(B-V) reddening at this location

This requires the dustmaps package to run!

Parameters:: dustmaps_cls (Optional[Any]) – By default, SFDQuery.
Returns:: The E(B-V) reddening values.
Return type:: numpy.ndarray

get_error_samples(size=1, rng=None, **get_cov_kwargs)#

Generate a sampling from the Gaia error distribution for each source.

This function constructs the astrometric covariance matrix for each source and generates a specified number of random samples from the error distribution for each source. This does not handle spatially-dependent correlations. Samplings generated with this method can be used to, e.g., propagate the Gaia errors through coordinate transformations or analyses.

Parameters:

size (int) – The number of random samples per source to generate.
rng (Union[int, Generator, None]) – The random number generator or an integer seed.
get_cov_kwargs (Any) –

Returns:

The same data table, but now each Gaia coordinate entry contains samples from the error distribution.

Return type:

GaiaData

get_ext(ebv=None, dustmaps_cls=None)#

Compute the E(B-V) reddening at this location

This requires the dustmaps package to run!

Parameters:

dustmaps_cls (Optional[Any]) – By default, SFDQuery.
ebv (Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]], None]) –

Return type:

Tuple[Quantity, Quantity, Quantity]

Returns:

ndarray – The A_G values
ndarray – The A_BP values
ndarray – The A_RP values

get_pm(frame='icrs')#

Get the 2D proper motion array in the specified frame

Parameters:: frame (Union[str, BaseCoordinateFrame]) – The coordinate frame to return the proper motion vector in. Has shape (nrows, 2)
Returns:: A 2D array of proper motion values in the specified frame.
Return type:: Quantity

get_radial_velocity(fill_value=None)#

Return radial velocity but with invalid values filled with the specified fill value.

Parameters:: fill_value (Optional[float]) – If not None, fill any invalid values with the specified value.
Returns:: The radial velocity values.
Return type:: Quantity [velocity]

get_ruwe()#

Return type:: None

get_skycoord(distance=None, radial_velocity=None, ref_epoch=<Time object: scale='tt' format='jyear' value=2016.0>)#

Return an SkyCoord object to represent all coordinates. Note: this requires Astropy v3.0 or higher!

ref_epoch is used to set the obstime attribute on the coordinate objects. This is often included in the data release tables, but ref_epoch here is used if it’s not.

Parameters:

distance (Optional[Quantity]) – If None, this inverts the parallax to get the distance from the Gaia data. If False, distance information is ignored. If an astropy Quantity or Distance object, it sets the distance values of the output SkyCoord to whatever is passed in.
radial_velocity (Optional[Quantity]) – If None, this uses radial velocity data from the input Gaia table. If an astropy Quantity object, it sets the radial velocity values of the output SkyCoord to whatever is passed in.
ref_epoch (str) – The reference epoch of the data. If not specified, this will try to read it from the input Gaia data table. If not provided, this will be set to whatever the most recent data release is, so, beware!

Returns:

The coordinate object constructed from the input Gaia data.

Return type:

SkyCoord

get_uwe()#

Compute and return the unit-weight error.

Return type:: Quantity