API documentation#

Loaders#

class astrodb_utils.loaders.DatabaseSettings(settings_file: str, base_path: str = '.', db_name: str = None, felis_path: str = 'schema.yaml', data_path: str = 'data', lookup_tables: list = None)[source]#

Bases: object

Database settings dataclass

base_path: str = '.'#

data_path: str = 'data'#

db_name: str = None#

felis_path: str = 'schema.yaml'#

lookup_tables: list = None#

settings_file: str#

astrodb_utils.loaders.build_db_from_json(settings_file: str = 'database.toml', *, base_path: str = '.', db_name: str = None, felis_path: str = None, data_path: str = None, lookup_tables: list = None)[source]#

Build an SQLite database from JSON files.

Default is to get the database settings from a TOML settings file. Creates the database .sqlite file in the current directory. If a database file with the same name already exists, it is removed. This creates a .sqlite database file.

Inputs#

settings_filestr: Name of the TOML file containing the database settings Default: database.toml
base_pathstr: Path to the directory containing the TOML file Default: None, assumes TOML file is in current directory
db_namestr: Name of the database file (without .sqlite extension) Default: None, reads from TOML file
felis_pathstr: Path to the Felis schema file Default: None, reads from TOML file
data_pathstr: Path to the data directory containing the JSON files Default: None, reads from TOML file
lookup_tableslist: List of tables to consider as lookup tables. Default: None, reads from TOML file

returns:: db – Astrodbkit Database object
rtype:: astrodbkit.astrodb.Database

astrodb_utils.loaders.read_db_from_file(db_name: str, db_path: str = None)[source]#

Read an SQLite database from a file.

Parameters:

db_name (str) – Name of the database file (without .sqlite extension)
db_path (str, optional) – Path to the directory containing the database .sqlite file Default: None, assumes database file is in current directory

Returns:

db – Astrodbkit Database object

Return type:

astrodbkit.astrodb.Database

Sources#

astrodb_utils.sources.find_source_in_db(db, source: str, *, ra: float = None, dec: float = None, search_radius: Quantity = <Quantity 60. arcsec>, ra_col_name: str = 'ra_deg', dec_col_name: str = 'dec_deg', use_simbad: bool = True, fuzzy: bool = False)[source]#

Find a source in the database given a source name and optional coordinates. Uses astrodbkit .search_object and .query_region methods to search the Sources and Names table.

Parameters:

db
source (str) – Source name
ra (float) – Right ascensions of sources. Decimal degrees.
dec (float) – Declinations of sources. Decimal degrees.
search_radius (u.Quantity) – Search radius. Default is 60 arcseconds.
ra_col_name (str) – Name of the column in the database table that contains the right ascension
dec_col_name (str) – Name of the column in the database table that contains the declination
use_simbad (bool) – Use Simbad to resolve the source name if it is not found in the database. Default is True. Set to False if no internet connection.
fuzzy (bool) – Use fuzzy search to find source name in database. Default is False.

Returns:

List of strings.
one match (Single element list with one database source name)
multiple matches (List of possible database names)
no matches (Empty list)

astrodb_utils.sources.ingest_name(db, source: str = None, other_name: str = None, raise_error: bool = None)[source]#

This function ingests an other name into the Names table

Parameters:

db (astrodbkit.astrodb.Database) – Database object created by astrodbkit
source (str) – Name of source as it appears in sources table
other_name (str) – Name of the source different than that found in source table
raise_error (bool) – Raise an error if name was not ingested

Returns:

other_name (str) – Name of the source as it appears in the Names table
or None if name was not ingested

astrodb_utils.sources.ingest_source(db, source, reference: str, *, ra: float = None, dec: float = None, epoch: str = None, equinox: str = None, other_reference: str = None, comment: str = None, raise_error: bool = True, search_db: bool = True, ra_col_name: str = 'ra_deg', dec_col_name: str = 'dec_deg', epoch_col_name: str = 'epoch_year', use_simbad: bool = True)[source]#

Parameters:

db (astrodbkit.astrodb.Database) – Database object created by astrodbkit
source (str) – Names of sources
reference (str) – Discovery references of sources
ra (float, optional) – Right ascensions of sources. Decimal degrees.
dec (float, optional) – Declinations of sources. Decimal degrees.
comment (string, optional) – Comments
epoch (str, optional) – Epochs of coordinates
equinoxe (str, optional) – Equinoxes of coordinates
other_references (str)
raise_error (bool, optional) – True (default): Raise an error if a source cannot be ingested False: Log a warning but skip sources which cannot be ingested
search_db (bool, optional) – True (default): Search database to see if source is already ingested False: Ingest source without searching the database
ra_col_name (str) – Name of the column in the database table that contains the right ascension
dec_col_name (str) – Name of the column in the database table that contains the declination
use_simbad (bool) – True (default): Use Simbad to resolve the source name if it is not found in the database False: Do not use Simbad to resolve the source name.

Return type:

None

Photometry#

Photometry functions

astrodb_utils.photometry.assign_ucd(wave_eff_quantity: Quantity)[source]#

Assign a Unified Content Descriptors (UCD) to a photometry filter based on its effective wavelength UCDs are from the UCD1+ controlled vocabulary https://www.ivoa.net/documents/UCD1+/20200212/PEN-UCDlist-1.4-20200212.html#tth_sEcB

Parameters:: wave_eff (Quantity) – Effective wavelength
Returns:: ucd – UCD string
Return type:: str

astrodb_utils.photometry.fetch_svo(telescope: str = None, instrument: str = None, filter_name: str = None)[source]#

Fetch photometry filter information from the SVO Filter Profile Service http://svo2.cab.inta-csic.es/theory/fps/

Could use better error handling when instrument name or filter name is not found

Parameters:

telescope (str) – Telescope name
instrument (str) – Instrument name
filter_name (str) – Filter name

Returns:

filter_id (str) – Filter ID
wave_eff (Quantity) – Effective wavelength
fwhm (Quantity) – Full width at half maximum (FWHM)
width_effective (Quantity) – Effective width of the filter

Raises:

AstroDBError – If the SVO URL is not reachable or the filter information is not found
KeyError – If the filter information is not found in the VOTable

astrodb_utils.photometry.ingest_photometry(db, *, source: str = None, band: str = None, regime: str = None, magnitude: float = None, magnitude_error: float = None, reference: str = None, telescope: str | None = None, epoch: float | None = None, comments: str | None = None, raise_error: bool = True)[source]#

Add a photometry measurement to the database

Parameters:

db (astrodbkit.astrodb.Database)
source (str)
band (str)
regime (str)
magnitude (float)
magnitude_error (float)
reference (str)
telescope (str, optional)
epoch (float, optional)
comments (str, optional)
raise_error (bool, optional) – True (default): Raise an error if a source cannot be ingested False: Logs a warning but does not raise an error

Returns:

flags –

added: bool: True if the measurement was added to the database False if the measurement was not added to the database

Return type:

dict

astrodb_utils.photometry.ingest_photometry_filter(db, *, telescope=None, instrument=None, filter_name=None, ucd=None, wavelength_col_name: str = 'effective_wavelength_angstroms', width_col_name: str = 'width_angstroms')[source]#: Add a new photometry filter to the database

Utils#

Utils functions for use in ingests.

astrodb_utils.utils.check_obs_date(date, raise_error=True)[source]#

Check if the observation date is in a parseable ISO format (YYYY-MM-DD). :Parameters: date (str) – Observation date

Returns:: True if the date is in parseable ISO format, False otherwise
Return type:: bool

astrodb_utils.utils.exit_function(msg, raise_error=True, return_value=None)[source]#

Exit function to handle errors and exceptions

Parameters:

msg (str) – Message to be logged
raise_error (bool) – Flag to raise an error
return_value (any) – Value to be returned if raise_error is False

astrodb_utils.utils.get_db_regime(db, regime: str, raise_error=True)[source]#

Check if a regime is in the Regimes table using ilike matching. This minimizes problems with case sensitivity.

If it is not found or there are multiple matches, raise an error or return None. If it is found, return the reference as a string.

Returns:

str (The regime found)
None (If the regime is not found or there are multiple matches.)

astrodb_utils.utils.internet_connection()[source]#

astrodb_utils.utils.load_astrodb(db_file, data_path='data/', recreatedb=True, reference_tables=['Publications', 'Telescopes', 'Instruments', 'Versions', 'PhotometryFilters', 'Regimes', 'AssociationList', 'ParameterList', 'CompanionList', 'SourceTypeList'], felis_schema=None)[source]#

Utility function to load the database

Note

Deprecated in 2.0 and will be removed in future versions. load_astrodb is deprecated. It is replaced by loaders.build_db_from_json() and loaders.read_db_from_file().

Parameters:

db_file (str) – Name of SQLite file to use
data_path (str) – Path to data directory; default ‘data/’
recreatedb (bool) – Flag whether or not the database file should be recreated
reference_tables (list) – List of tables to consider as reference tables. Default: Publications, Telescopes, Instruments, Versions, PhotometryFilters
felis_schema (str) – Path to Felis schema; default None

Spectra#

astrodb_utils.spectra.check_spectrum_plottable(spectrum_path: str | Spectrum, raise_error: bool = True, show_plot: bool = False, format: str = None)[source]#

Check if spectrum is readable and plottable with specutils. show_plot = True requires matplotlib to be installed.

Parameters:

spectrum_path (str or Spectrum) – Path to spectrum file or Spectrum object
raise_error (bool. Default=True) – True: Raise error if spectrum is not plottable False: Do not raise error if spectrum is not plottable. Log warning instead.
show_plot (bool. Default=False) – True: Show plot of spectrum. Matplotlib must be installed.
format (str, optional) – Format of the spectrum file. If not provided, the format will be inferred by specutils.

Returns:

True: Spectrum is plottable False: Spectrum is not plottable

Return type:

bool

astrodb_utils.spectra.find_spectra(db: Database, source: str, *, reference: str = None, obs_date: str = None, telescope: str = None, instrument: str = None, mode: str = None, regime: str = None)[source]#

Find what spectra already exists in database for this source Finds matches based on parameter provided. E.g., if only source is provided, all spectra for that source are returned.

If Source and telescope are provided, only spectra for that source and telescope are provided.

Parameters:

db (astrodbkit.astrodb.Database) – Database object created by astrodbkit
source (str) – source name

Returns:

source_spec_data – Table of spectra for source

Return type:

astropy.table.Table

astrodb_utils.spectra.ingest_spectrum(db: Database, *, source: str = None, spectrum: str = None, regime: str = None, telescope: str = None, instrument: str = None, mode: str = None, obs_date: str | datetime = None, reference: str = None, original_spectrum: str | None = None, comments: str | None = None, other_references: str | None = None, local_spectrum: str | None = None, raise_error: bool = True, format: str | None = None)[source]#

Parameters:

db (astrodbkit.astrodb.Database) – Database object created by astrodbkit
source (str) – source name
spectrum (str) – URL or path to spectrum file
regime (str) – Regime of spectrum (optical, infrared, radio, etc.) controlled by Regimes table
telescope (str) – Telescope used to obtain spectrum. Required to be in Telescopes table.
instrument (str) – Instrument used to obtain spectrum. Instrument-Mode pair needs to be in Instruments table.
mode (str) – Instrument mode used to obtain spectrum. Instrument-Mode pair needs to be in Instruments table.
obs_date (str) – Observation date of spectrum.
reference (str) – Reference for spectrum. Required to be in Publications table.
original_spectrum (str) – Path to original spectrum file if different from spectrum.
comments (str) – Comments about spectrum.
other_references (str) – Other references for spectrum.
local_spectrum (str) – Path to local spectrum file.
raise_error (bool) – If True, raise an error if the spectrum cannot be added. If False, continue without raising an error.
format (str) – Format of the spectrum file used by specutils to load the file. If not provided, the format will be determined by specutils. Options: “tabular-fits”,

Returns:

flags –

Status response with the following keys:

”added”: True if it’s added and False if it’s skipped.
”content”: the data that was attempted to add
”message”: string which includes information about why skipped

Return type:

dict

Raises:

AstroDBError –

Fits#

astrodb_utils.fits.add_missing_keywords(header=None, format='ivoa-spectrum-dm-1.2', keywords=None)[source]#

Finds the keywords that are missing from a header and adds them with blank values

Inputs#

header: fits.Header: a fits header object or dictionary of header values
format: string: header data models to enforce. Options, ‘simple-spectrum’ and ‘ivoa-spectrum-dm-1.2`
keywords: list: a list of keywords to check for if format is not specified

rtype:: FITS header object

Examples

Returns a header with keywords but blank values >>> new_header = add_missing_keywords()

Adds missing keywords (with blank values) to an existing header using the simple spectrum data model >>> new_header = add_missing_keywords(old_header, format=’simple-spectrum’)

astrodb_utils.fits.add_observation_date(header=None, date=None)[source]#

Adds the observation date to the header

Inputs#

header: fits.Header: a fits header object or dictionary of header values
date: string: the date of the observation

rtype:: None

Examples

>>> add_observation_date(header, date='2021-06-01')

astrodb_utils.fits.add_wavelength_keywords(header=None, wavelength_data=None)[source]#

Uses wavelength array to generate header keywords

Inputs#

wavelength_data: astropy.units.Quantity: an array of wavelengths. should include units.
header_dict: header: a Header object

rtype:: None

Examples

>>> wavelength = np.arange(5100, 5300)*u.AA
>>> add_wavelength_keywords(header=new_header, wavelength_data = wavelength)

astrodb_utils.fits.check_header(header=None, format='ivoa-spectrum-dm-1.2', ignore_simbad=False)[source]#

Check the header of a FITS file for required keywords and other properties.

Parameters:

header (astropy.io.fits.Header) – The header object to be checked.
format (str, optional) – The data model of the FITS file. Default is ‘ivoa-spectrum-dm-1.2’.
ignore_simbad (bool, optional) – Whether to ignore checking SIMBAD coordinates. Default is False.

Returns:

True if the header passes all checks, False otherwise.

Return type:

bool

Raises:

ValueError – If the header is not provided.

Publications#

astrodb_utils.publications.check_ads_token()[source]#: Check if an ADS token is set

astrodb_utils.publications.find_publication(db, *, reference: str = None, doi: str = None, bibcode: str = None)[source]#

Find publications in the database by matching on the publication name, doi, or bibcode

Parameters:

db – Variable referencing the database to search
reference (str) – Name of publication to search
doi (str) – DOI of publication to search
bibcode (str) – ADS Bibcode of publication to search

Returns:

# TODO (Return three things: Boolean, n_pubs_found, string result)
True, str (if only one match)
False, 0 (No matches)
False, N_matches (Multiple matches)

Examples

>>> test = search_publication(db, reference='Cruz')
Found 8 matching publications for Cruz or None or None

>>> test = search_publication(db, reference='Kirk19')
Found 1 matching publications for Kirk19 or None or None
 name        bibcode                 doi
------ ------------------- ------------------------
Kirk19 2019ApJS..240...19K 10.3847/1538-4365/aaf6af
                        description
-----------------------------------------------------------------------------
Preliminary Trigonometric Parallaxes of 184 Late-T and Y Dwarfs and an
Analysis of the Field Substellar Mass Function into the Planetary Mass Regime

>>> test = search_publication(db, reference='Smith')
No matching publications for Smith, Trying Smit
No matching publications for Smit
Use add_publication() to add it to the database.

Instruments#

astrodb_utils.instruments.get_db_instrument(db, instrument=None, mode=None, telescope=None)[source]#

Retrieve instrument from the database

Parameters:

db (astrodbkit.astrodb.Database) – Database object created by astrodbkit
instrument (str, optional) – Name (or substring) of the instrument
mode (str, optional) – Observing mode
telescope (str, optional) – Telescope name

Returns:

one match found (tuple containing the matched)
no match or multiple matches (None)

astrodb_utils.instruments.ingest_instrument(db, *, telescope=None, instrument=None, mode=None, raise_error=True)[source]#

Script to ingest instrumentation TODO: Add option to ingest references for the telescope and instruments

Parameters:

db (astrodbkit.astrodb.Database) – Database object created by astrodbkit
telescope (str)
instrument (str)
mode (str)

Return type:

None