tessl/pypi-astroquery

Functions and classes to access online astronomical data resources

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

General Astronomical Databases

Name: tessl/pypi-astroquery
Author: tessl

Core astronomical data services that provide access to fundamental astronomical catalogs, object databases, and multi-wavelength surveys. These services form the foundation of astronomical research by offering standardized access to comprehensive stellar, galactic, and extragalactic data.

Capabilities

SIMBAD - Astronomical Object Database

SIMBAD (Set of Identifications, Measurements and Bibliography for Astronomical Data) provides comprehensive information about astronomical objects outside our solar system, including identifiers, coordinates, measurements, and bibliographic references.

from astroquery.simbad import Simbad

def query_object(object_name: str, *, wildcard: bool = False, criteria=None,
                get_query_payload: bool = False, verbose: bool = False) -> Table:
    """
    Query SIMBAD for information about a specific astronomical object.
    
    Parameters:
    - object_name: Name or identifier of the astronomical object
    - wildcard: Enable wildcard matching for object names  
    - criteria: Dictionary specifying query criteria/fields
    - get_query_payload: Return query parameters instead of executing
    - verbose: Show detailed output
    
    Returns:
    Table with object information including coordinates, identifiers, and measurements
    """

def query_objects(object_names: List[str]) -> Table:
    """
    Query SIMBAD for multiple objects simultaneously.
    
    Parameters:
    - object_names: List of object names or identifiers
    
    Returns:
    Table with information for all queried objects
    """

def query_region(coordinates: Union[SkyCoord, str], radius: Union[Quantity, str] = "2 arcmin", *,
                criteria=None, get_query_payload: bool = False) -> Table:
    """
    Query SIMBAD for objects within a sky region.
    
    Parameters:
    - coordinates: Center coordinates as SkyCoord or string
    - radius: Search radius (default: 2 arcmin)
    - criteria: Dictionary specifying query criteria/fields
    - get_query_payload: Return query parameters instead of executing
    
    Returns:
    Table with objects found in the specified region
    """

def query_objectids(object_name: str) -> Table:
    """
    Get all known identifiers for an astronomical object.
    
    Parameters:
    - object_name: Name or identifier of the object
    
    Returns:
    Table with all known identifiers and their sources
    """

def query_tap(query: str, **kwargs) -> Table:
    """
    Execute direct TAP/ADQL queries against SIMBAD database.
    
    Parameters:
    - query: ADQL query string
    - **kwargs: Additional TAP service parameters
    
    Returns:
    Table with query results
    """

# Configuration
from astroquery.simbad import conf
conf.server: List[str]        # SIMBAD mirror servers
conf.timeout: int = 60        # Connection timeout in seconds  
conf.row_limit: int = -1      # Maximum rows (-1 for unlimited)

Usage examples:

from astroquery.simbad import Simbad
import astropy.units as u
from astropy.coordinates import SkyCoord

# Query basic object information
result = Simbad.query_object('M1')
print(result['main_id', 'ra', 'dec'])

# Query with wildcard matching
result = Simbad.query_object('NGC 1*', wildcard=True)

# Region query around coordinates
coords = SkyCoord('05h35m17.3s -05h23m28s', frame='icrs')
result = Simbad.query_region(coords, radius=2*u.arcmin)

# Get all identifiers for an object
ids = Simbad.query_objectids('M1')
print(ids['id'])

# Custom SIMBAD fields
Simbad.add_votable_fields('flux(B)', 'flux(V)', 'sptype')
result = Simbad.query_object('Vega')

VizieR - Catalog Access Service

VizieR provides access to the most complete library of published astronomical catalogs and data tables available online, with standardized search capabilities across thousands of catalogs.

from astroquery.vizier import Vizier

def query_object(object_name: str, radius: Union[Quantity, str] = None, 
                catalog: Union[str, List[str]] = None) -> TableList:
    """
    Query VizieR catalogs around a named object.
    
    Parameters:
    - object_name: Name of the astronomical object
    - radius: Search radius around object (default: 2 arcmin)
    - catalog: Specific catalog(s) to query (default: all)
    
    Returns:
    TableList containing results from matching catalogs
    """

def query_region(coordinates: Union[SkyCoord, str], radius: Union[Quantity, str] = None,
                catalog: Union[str, List[str]] = None) -> TableList:
    """
    Query VizieR catalogs in a sky region.
    
    Parameters:
    - coordinates: Center coordinates as SkyCoord or string
    - radius: Search radius (default: 2 arcmin)
    - catalog: Specific catalog(s) to query
    
    Returns:
    TableList with catalog entries in the specified region
    """

def query_constraints(**kwargs) -> TableList:
    """
    Query catalogs with column value constraints.
    
    Parameters:
    - **kwargs: Column constraints (e.g., Vmag='<10', BV='>0.5')
    
    Returns:
    TableList with entries matching the constraints
    """

def get_catalogs(keywords: Union[str, List[str]]) -> Table:
    """
    Search for catalogs by keywords.
    
    Parameters:
    - keywords: Keywords to search catalog descriptions
    
    Returns:
    Table with matching catalog information
    """

def find_catalogs(keywords: Union[str, List[str]]) -> Table:
    """
    Find available catalogs matching keywords.
    
    Parameters:
    - keywords: Search keywords
    
    Returns:
    Table with catalog names and descriptions
    """

# Configuration
from astroquery.vizier import conf
conf.server: str              # VizieR server URL
conf.timeout: int = 60        # Connection timeout
conf.row_limit: int = 50      # Default row limit per catalog

Usage examples:

from astroquery.vizier import Vizier
import astropy.units as u
from astropy.coordinates import SkyCoord

# Set row limit and columns
Vizier.ROW_LIMIT = 100
Vizier.columns = ['_RAJ2000', '_DEJ2000', 'Vmag']

# Query around an object
result = Vizier.query_object('M1', radius=5*u.arcmin)
print(f"Found {len(result)} catalogs")

# Query specific catalogs
result = Vizier.query_object('Polaris', catalog=['2MASS', 'USNO-B1'])

# Region query with constraints
coords = SkyCoord('12h30m', '+41d16m', frame='icrs')
result = Vizier.query_region(coords, radius=1*u.deg, 
                           catalog='2MASS-PSC',
                           column_filters={'Kmag': '<10'})

# Find catalogs by keyword
catalogs = Vizier.find_catalogs('photometry')
print(catalogs['title'])

Gaia - European Space Agency's Gaia Mission

Gaia provides access to the most precise stellar astrometry, photometry, and spectroscopy data available, revolutionizing our understanding of the Milky Way galaxy structure and stellar physics.

from astroquery.gaia import Gaia

def query_object(coordinate: Union[SkyCoord, str], *, radius: Union[Quantity, str] = None,  
                width: Union[Quantity, str] = None, height: Union[Quantity, str] = None,
                verbose: bool = False, columns: tuple = ()) -> Table:
    """
    Query Gaia catalog around coordinates.
    
    Parameters:
    - coordinate: Center position as SkyCoord or string
    - radius: Search radius for circular region
    - width: Width for rectangular region
    - height: Height for rectangular region
    - verbose: Show detailed output
    - columns: Tuple specifying which columns to retrieve
    
    Returns:
    Table with Gaia sources in the specified region
    """

def cone_search(coordinate: Union[SkyCoord, str], *, radius: Union[Quantity, str] = None,
               table_name: str = None, ra_column_name: str = "ra", dec_column_name: str = "dec",
               output_file: str = None, output_format: str = "votable_gzip", 
               verbose: bool = False, dump_to_file: bool = False, columns: tuple = ()) -> Table:
    """
    Perform cone search in Gaia catalog.
    
    Parameters:
    - coordinate: Center coordinates
    - radius: Search radius (maximum 0.5 degrees)
    - table_name: Gaia table to query (uses default if not specified)
    - ra_column_name: Name of RA column in the table
    - dec_column_name: Name of DEC column in the table
    - output_file: Optional file to save results
    - output_format: Format for output file (votable_gzip, csv, etc.)
    - verbose: Show detailed output
    - dump_to_file: Save results to file
    - columns: Tuple specifying which columns to retrieve
    
    Returns:
    Table with Gaia sources within the cone
    """

def cone_search_async(coordinate: Union[SkyCoord, str], radius: Union[Quantity, str] = None) -> JobResults:
    """
    Submit asynchronous cone search job.
    
    Parameters:
    - coordinate: Center coordinates  
    - radius: Search radius
    
    Returns:
    JobResults object for retrieving results
    """

def launch_job(query: str, name: str = None, output_file: str = None, 
              output_format: str = 'votable', verbose: bool = False) -> JobResults:
    """
    Submit synchronous ADQL query job to Gaia TAP service.
    
    Parameters:
    - query: ADQL query string
    - name: Job name
    - output_file: File to save results
    - output_format: Output format ('votable', 'csv', 'fits')
    - verbose: Show detailed output
    
    Returns:
    JobResults with query results
    """

def launch_job_async(query: str, name: str = None, output_file: str = None,
                    output_format: str = 'votable', verbose: bool = False) -> JobResults:
    """
    Submit asynchronous ADQL query job.
    
    Parameters:
    - query: ADQL query string
    - name: Job name  
    - output_file: File to save results
    - output_format: Output format
    - verbose: Show detailed output
    
    Returns:
    JobResults object for monitoring and retrieving results
    """

def load_table(table_name: str, verbose: bool = False) -> Table:
    """
    Load Gaia data table schema information.
    
    Parameters:
    - table_name: Name of Gaia table to load
    - verbose: Show detailed output
    
    Returns:
    Table with schema information
    """

# Configuration  
from astroquery.gaia import conf
conf.server: str              # Gaia TAP server URL
conf.timeout: int = 60        # Connection timeout

Usage examples:

from astroquery.gaia import Gaia
import astropy.units as u
from astropy.coordinates import SkyCoord

# Simple cone search
coords = SkyCoord(ra=280.161, dec=11.161, unit='deg', frame='icrs')
result = Gaia.cone_search(coords, radius=0.1*u.deg)
print(f"Found {len(result)} Gaia sources")

# Query with ADQL
query = '''
SELECT TOP 1000 source_id, ra, dec, phot_g_mean_mag, bp_rp
FROM gaiadr3.gaia_source 
WHERE CONTAINS(POINT('ICRS', ra, dec), 
               CIRCLE('ICRS', 280.161, 11.161, 0.1)) = 1
AND phot_g_mean_mag < 15
ORDER BY phot_g_mean_mag
'''
job = Gaia.launch_job(query)
result = job.get_results()

# Asynchronous job for large queries  
job = Gaia.launch_job_async(query, name="bright_stars_search")
print(f"Job status: {job.get_phase()}")
result = job.get_results()

# Get table schema
schema = Gaia.load_table('gaiadr3.gaia_source')
print(schema['column_name', 'datatype', 'description'])

Common Types

from astropy.table import Table, TableList
from astropy.coordinates import SkyCoord
from astropy.units import Quantity
from typing import Union, List, Optional

# Input coordinate types
coordinates: Union[SkyCoord, str]     # Sky coordinates
radius: Union[Quantity, str, None]    # Search radius with units

# Query parameters
object_name: str                      # Astronomical object name
catalog: Union[str, List[str], None]  # Catalog identifier(s)
get_query_payload: bool = False       # Return parameters only
cache: bool = True                    # Enable caching
verbose: bool = False                 # Detailed output

# Return types
Table                                 # Single table result
TableList                            # Multiple catalog results
JobResults                           # Asynchronous job results

Install with Tessl CLI