hispecdrp.primitives.utils.gaia_query

Functions

_cell(row, colname)

Extract a plain Python scalar from an astropy table cell, or None if masked/NaN.

_convert_epoch_gaia(ra, dec[, epoch, pmra, ...])

Convert epoch to Gaia epoch.

_gaia_class()

Import astroquery.gaia.Gaia lazily (same hang rationale as VizieR).

_linear_pm_epoch_shift(ra, dec, pmra, pmdec, ...)

First-order proper-motion shift when parallax/distance are unknown.

_norm(name)

Strip non-alphanumeric characters (keep case) for robust column-name matching.

_query_2mass_by_designation(designation)

Look up a single 2MASS PSC source by its designation on VizieR (mirror fallback).

_query_gaia_dr3(*[, source_id, center, ...])

Query Gaia DR3: ESA TAP by default, with VizieR fallback.

_query_gaia_dr3_tap(*[, source_id, center, ...])

Query ESA Gaia Archive TAP via astroquery.gaia.

_query_gaia_dr3_vizier(*[, source_id, ...])

Query the VizieR Gaia DR3 mirror via the shared mirror-fallback layer.

_row_to_dict(row[, colnames])

Convert an astropy table row to a plain Python dict (masked/NaN → None).

_tap_row_to_gaia_dict(row)

Normalize a Gaia TAP gaia_source row to the public result dict.

_tmass_designation_from_vizier(source_id)

Return the 2MASS column from the VizieR Gaia DR3 row, or None.

_tmass_from_tap(source_id)

Return 2MASS PSC photometry via Gaia TAP cross-match tables, or None.

_twomass_row_to_dict(row, colnames)

Convert a 2MASS PSC (II/246) VizieR row to the get_2mass_from_gaia dict format.

_vizier_class()

Import astroquery.vizier.Vizier lazily.

_vizier_row_to_gaia_dict(row, colnames[, ...])

Convert a VizieR I/355/gaiadr3 row to the Gaia TAP output dict format.

gaia_backend()

Return the Gaia catalog backend: tap, vizier, or auto.

get_2mass_data_vizier(ra, dec[, radius_arcsec])

Cone-search the 2MASS PSC on VizieR (II/246) and return the nearest source.

get_2mass_from_gaia(source_id[, radius_arcsec])

Return the 2MASS counterpart for a Gaia DR3 source.

get_stellar_data_gaia_by_coordinates(ra, dec)

Query Gaia DR3 for basic stellar properties nearest to the given coordinates.

get_stellar_data_gaia_from_source_id(source_id)

Query Gaia DR3 for basic stellar properties using a specific Gaia source_id.

query_vizier(*, catalog[, columns, center, ...])

Query one VizieR catalog, trying mirror servers in order with retry rounds.

vizier_mirrors()

Return the VizieR servers to try, in order.

vizier_timeout()

Per-request VizieR timeout in seconds (HISPEC_DRP_VIZIER_TIMEOUT overrides).

_convert_epoch_gaia(ra, dec, epoch=2000.0, pmra=0.0, pmdec=0.0, px=0.0, rvsys=0.0, to_gaia=True, release='DR3')[source]

Convert epoch to Gaia epoch.

Parameters:
  • ra (float) – Right ascension in degrees.

  • dec (float) – Declination in degrees.

  • epoch (float) – Epoch of the input coordinates (e.g., 2000.0).

  • pmra (float, optional) – Proper motion in RA (mas/yr).

  • pmdec (float, optional) – Proper motion in Dec (mas/yr).

  • px (float, optional) – Parallax (mas).

  • rvsys (float, optional) – Systemic Radial velocity (km/s).

  • to_gaia (bool, optional) – If True, convert to Gaia epoch; otherwise, convert from Gaia to the specified epoch.

  • release (str, optional) – The Gaia data release to use (default “DR3”).

Returns:

tuple[float, float] – Converted right ascension and declination.

gaia_backend()[source]

Return the Gaia catalog backend: tap, vizier, or auto.

HISPEC_DRP_GAIA_BACKEND overrides the default (auto = ESA TAP, then VizieR on failure). Unknown values fall back to auto.

get_2mass_data_vizier(ra, dec, radius_arcsec=3.0)[source]

Cone-search the 2MASS PSC on VizieR (II/246) and return the nearest source.

Uses the same VizieR mirror fallback as the Gaia DR3 queries. The returned dict uses the same key names as get_2mass_from_gaia() (twomass_id, tm_ra, tm_dec, j_m, j_msigcom, h_m, h_msigcom, ks_m, ks_msigcom). 2MASS JHKs magnitudes are in the Vega system.

Parameters:
  • ra (float) – ICRS coordinates in degrees (e.g. the Gaia source position).

  • dec (float) – ICRS coordinates in degrees (e.g. the Gaia source position).

  • radius_arcsec (float) – Cone search radius in arcseconds (default 3).

Returns:

dict or None – Photometry/astrometry for the nearest 2MASS source, or None if no match.

get_2mass_from_gaia(source_id, radius_arcsec=1.0)[source]

Return the 2MASS counterpart for a Gaia DR3 source.

Prefer ESA TAP: Gaia DR3 tmass_psc_xsc_* cross-match joined to gaiadr1.tmass_original_valid. If TAP is unavailable, fall back to the VizieR Gaia DR3 2MASS designation looked up in the 2MASS PSC (II/246), then a cone search around the Gaia position propagated to J2000.

The returned dict keys are twomass_id, tm_ra, tm_dec, j_m, j_msigcom, h_m, h_msigcom, ks_m, ks_msigcom; JHKs are Vega.

get_stellar_data_gaia_by_coordinates(ra, dec, radius_arcsec=5.0, epoch=2000.0, pmra=0.0, pmdec=0.0, px=0.0, rvsys=0.0, release='DR3')[source]

Query Gaia DR3 for basic stellar properties nearest to the given coordinates.

Uses ESA Gaia Archive TAP (astroquery.gaia) by default, with VizieR mirror fallback when TAP is unavailable (see gaia_backend()).

Parameters:
  • ra (float) – Right ascension in degrees.

  • dec (float) – Declination in degrees.

  • radius_arcsec (float) – Search cone radius in arcseconds (default 5).

  • epoch (float) – Epoch of the input coordinates (default 2000.0).

  • pmra (float, optional) – Proper motion in RA (mas/yr).

  • pmdec (float, optional) – Proper motion in Dec (mas/yr).

  • px (float, optional) – Parallax (mas).

  • rvsys (float, optional) – Systemic Radial velocity (km/s).

  • release (str, optional) – The Gaia data release to use (default “DR3”).

Returns:

dict or None – Gaia DR3 properties for the closest match, or None if no source found.

get_stellar_data_gaia_from_source_id(source_id)[source]

Query Gaia DR3 for basic stellar properties using a specific Gaia source_id.

Uses ESA Gaia Archive TAP (astroquery.gaia) by default, with VizieR mirror fallback when TAP is unavailable (see gaia_backend()).

Parameters:

source_id (int | str) – Gaia DR3 source_id of the star.

Returns:

dict or None – Gaia DR3 properties for the specified source, or None if not found.

query_vizier(*, catalog, columns=None, center=None, radius_deg=None, constraints=None, column_filters=None, row_limit=50, max_rounds=None, description=None)[source]

Query one VizieR catalog, trying mirror servers in order with retry rounds.

Shared fallback layer for every VizieR query in the DRP, following the POTPyRI query_vizier_region / query_gaia_dr3_region pattern: clear the astroquery cache, walk vizier_mirrors() catching per-server errors, and repeat the whole list up to max_rounds times for transient failures. Each request uses a finite timeout (vizier_timeout()) so one unresponsive mirror cannot block the rest.

Exactly one of center (with radius_deg) or constraints must be given, selecting a cone search or a constraint query respectively.

Parameters:
  • catalog (str) – VizieR catalog identifier (e.g. 'I/355/gaiadr3').

  • columns (list of str, optional) – Columns to request; defaults to all columns (['**']).

  • center (astropy.coordinates.SkyCoord, optional) – Cone-search center.

  • radius_deg (float, optional) – Cone-search radius in degrees. Required with center.

  • constraints (dict, optional) – Column constraints for query_constraints (e.g. {'Source': '==12345'}).

  • column_filters (dict, optional) – VizieR server-side column filters (e.g. {'Gmag': '<8'}).

  • row_limit (int) – Maximum rows to return (-1 for unlimited).

  • max_rounds (int, optional) – Full passes over the mirror list. Defaults to VIZIER_MAX_ROUNDS_DEFAULT.

  • description (str, optional) – Short label for log messages; defaults to catalog.

Returns:

astropy.table.Table or None – First table of the response, or None if every mirror failed or no row matched.

vizier_mirrors()[source]

Return the VizieR servers to try, in order.

HISPEC_DRP_VIZIER_MIRRORS (comma-separated hostnames) overrides the built-in list, which lets a site with a local VizieR/Gaia DR3 mirror (e.g. Keck’s offline DR3) redirect every query in the DRP without code changes.

vizier_timeout()[source]

Per-request VizieR timeout in seconds (HISPEC_DRP_VIZIER_TIMEOUT overrides).