API documentation

agasc.agasc.TABLE_DTYPE = dtype([('AGASC_ID', '<i4'), ('RA', '<f8'), ('DEC', '<f8'), ('POS_ERR', '<i2'), ('POS_CATID', 'u1'), ('EPOCH', '<f4'), ('PM_RA', '<i2'), ('PM_DEC', '<i2'), ('PM_CATID', 'u1'), ('PLX', '<i2'), ('PLX_ERR', '<i2'), ('PLX_CATID', 'u1'), ('MAG_ACA', '<f4'), ('MAG_ACA_ERR', '<i2'), ('CLASS', '<i2'), ('MAG', '<f4'), ('MAG_ERR', '<i2'), ('MAG_BAND', '<i2'), ('MAG_CATID', 'u1'), ('COLOR1', '<f4'), ('COLOR1_ERR', '<i2'), ('C1_CATID', 'u1'), ('COLOR2', '<f4'), ('COLOR2_ERR', '<i2'), ('C2_CATID', 'u1'), ('RSV1', '<f4'), ('RSV2', '<i2'), ('RSV3', 'u1'), ('VAR', '<i2'), ('VAR_CATID', 'u1'), ('ASPQ1', '<i2'), ('ASPQ2', '<i2'), ('ASPQ3', '<i2'), ('ACQQ1', '<i2'), ('ACQQ2', '<i2'), ('ACQQ3', '<i2'), ('ACQQ4', '<i2'), ('ACQQ5', '<i2'), ('ACQQ6', '<i2'), ('XREF_ID1', '<i4'), ('XREF_ID2', '<i4'), ('XREF_ID3', '<i4'), ('XREF_ID4', '<i4'), ('XREF_ID5', '<i4'), ('RSV4', '<i2'), ('RSV5', '<i2'), ('RSV6', '<i2')])

Standard dtypes for AGASC table.

class agasc.agasc.TableOrder(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Enumeration type to specify the AGASC table ordering:

  • TableOrder.NONE. The stars are not sorted.

  • TableOrder.HEALPIX. The stars are sorted using a HEALPix index.

  • TableOrder.DEC. The stars are sorted by declination.

agasc.agasc.add_pmcorr_columns(stars, date)[source]

Add proper-motion corrected columns RA_PMCORR and DEC_PMCORR to Table stars.

This computes the PM-corrected RA and Dec of all stars using the supplied date, which may be a scalar or an array-valued object (np.array or list).

The stars table is updated in-place.

Parameters:
stars

astropy Table of stars from the AGASC

date

scalar, list, array of date(s) in DateTime-compatible format

Returns:
None
agasc.agasc.get_agasc_cone(ra, dec, radius=1.5, date=None, agasc_file=None, pm_filter=True, fix_color1=True, use_supplement=None, matlab_pm_bug=False, columns=None, cache=False)[source]

Get AGASC catalog entries within radius degrees of ra, dec.

The star positions are corrected for proper motion using the date argument, which defaults to the current date if not supplied. The corrected positions are available in the RA_PMCORR and DEC_PMCORR columns, respectively.

By default, stars with available mag estimates or bad star entries in the AGASC supplement are updated in-place in the output stars Table:

  • MAG_ACA and MAG_ACA_ERR are set according to the supplement.

  • MAG_CATID (mag catalog ID) is set to agasc.MAG_CATID_SUPPLEMENT.

  • If COLOR1 is 0.7 or 1.5 then it is changed to 0.69 or 1.49 respectively. Those particular values do not matter except that they are different from the “status flag” values of 0.7 (no color => very unreliable mag estimate) or 1.5 (red star => somewhat unreliable mag estimate) that have special meaning based on deep heritage in the AGASC catalog itself.

  • If AGASC_ID is in the supplement bad stars table then CLASS is set to agasc.BAD_CLASS_SUPPLEMENT.

To disable the magnitude / bad star updates from the AGASC supplement, see the set_supplement_enabled context manager / decorator.

If agasc_file is not specified or is None then use either default_agasc_dir()/${AGASC_HDF5_FILE} if ${AGASC_HDF5_FILE} is defined; or use the latest version of proseco_agasc in default_agasc_dir().

If agasc_file ends with the suffix .h5 then it is useed as-is.

If agasc_file ends with * then the latest version of the matching AGASC file in default_agasc_dir() is useed. For example, proseco_agasc_* could use ${SKA}/data/agasc/proseco_agasc_1p7.h5.

Any other ending for agasc_file raises a ValueError.

The default AGASC directory is the environment variable ${AGASC_DIR} if defined, otherwise ${SKA}/data/agasc.

The default AGASC supplement file is <AGASC_DIR>/agasc_supplement.h5.

Example:

>>> import agasc
>>> stars = agasc.get_agasc_cone(10.0, 20.0, 1.5)
>>> plt.plot(stars['RA'], stars['DEC'], '.')
Parameters:
rafloat

RA (deg)

decfloat

Declination (deg)

radiusfloat

Cone search radius (deg)

dateCxoTimeLike, optional

Date for proper motion (default=Now)

agasc_filestr, optional

AGASC file (optional)

pm_filterbool

Use PM-corrected positions in filtering

fix_color1bool

set COLOR1=COLOR2 * 0.85 for stars with V-I color

use_supplementbool, optional

Use estimated mag from AGASC supplement where available (default=value of AGASC_SUPPLEMENT_ENABLED env var, or True if not defined)

matlab_pm_bugbool

Apply MATLAB proper motion bug prior to the MAY2118A loads (default=False)

columnstuple[str], optional

Columns to return (default=all)

cachebool

Cache the AGASC data in memory (default=False)

Returns:
astropy.table.Table

Table of AGASC entries

agasc.agasc.get_agasc_filename(agasc_file=None, allow_rc=False, version=None)[source]

Get a matching AGASC file name from agasc_file.

If agasc_file is not specified or is None then return either default_agasc_dir()/${AGASC_HDF5_FILE} if ${AGASC_HDF5_FILE} is defined; or return the latest version of proseco_agasc in default_agasc_dir().

If agasc_file ends with the suffix .h5 then it is returned as-is.

If agasc_file ends with * then the latest version of the matching AGASC file in default_agasc_dir() is returned. For example, proseco_agasc_* could return ${SKA}/data/agasc/proseco_agasc_1p7.h5.

Any other ending for agasc_file raises a ValueError.

The default AGASC directory is the environment variable ${AGASC_DIR} if defined, otherwise ${SKA}/data/agasc.

Parameters:
agasc_filestr, Path, optional

AGASC file name (default=None)

allow_rcbool, optional

Allow AGASC release candidate files (default=False)

versionstr, optional

Version number to match (e.g. “1p8” or “1p8rc4”, default=None)

Returns:
filenamestr

Matching AGASC file name

Examples

Setup:

>>> from agasc import get_agasc_filename

Selecting files in the default AGASC directory:

>>> get_agasc_filename()
'/Users/aldcroft/ska/data/agasc/proseco_agasc_1p7.h5'
>>> get_agasc_filename("proseco_agasc_*")
'/Users/aldcroft/ska/data/agasc/proseco_agasc_1p7.h5'
>>> get_agasc_filename("proseco_agasc_*", version="1p8", allow_rc=True)
'/Users/aldcroft/ska/data/agasc/proseco_agasc_1p8rc4.h5'
>>> get_agasc_filename("agas*")
Traceback (most recent call last):
   ...
FileNotFoundError: No AGASC files in /Users/aldcroft/ska/data/agasc found matching
  agas*_?1p([0-9]+).h5

Selecting non-default AGASC file in the default directory:

>>> os.environ["AGASC_HDF5_FILE"] = "proseco_agasc_1p6.h5"
>>> get_agasc_filename()
'/Users/aldcroft/ska/data/agasc/proseco_agasc_1p6.h5'

Changing the default AGASC directory:

>>> os.environ["AGASC_DIR"] = "."
>>> get_agasc_filename()
'proseco_agasc_1p7.h5'

Selecting an arbitrary AGASC file name either directly or with the AGASC_HDF5_FILE environment variable:

>>> get_agasc_filename("any_agasc.h5")
'any_agasc.h5'
>>> os.environ["AGASC_HDF5_FILE"] = "whatever.h5"
>>> get_agasc_filename()
'/Users/aldcroft/ska/data/agasc/whatever.h5'
agasc.agasc.get_star(id, agasc_file=None, date=None, fix_color1=True, use_supplement=None)[source]

Get AGASC catalog entry for star with requested id.

By default, stars with available mag estimates or bad star entries in the AGASC supplement are updated in-place in the output stars Table:

  • MAG_ACA and MAG_ACA_ERR are set according to the supplement.

  • MAG_CATID (mag catalog ID) is set to agasc.MAG_CATID_SUPPLEMENT.

  • If COLOR1 is 0.7 or 1.5 then it is changed to 0.69 or 1.49 respectively. Those particular values do not matter except that they are different from the “status flag” values of 0.7 (no color => very unreliable mag estimate) or 1.5 (red star => somewhat unreliable mag estimate) that have special meaning based on deep heritage in the AGASC catalog itself.

  • If AGASC_ID is in the supplement bad stars table then CLASS is set to agasc.BAD_CLASS_SUPPLEMENT.

To disable the magnitude / bad star updates from the AGASC supplement, see the set_supplement_enabled context manager / decorator.

If agasc_file is not specified or is None then use either default_agasc_dir()/${AGASC_HDF5_FILE} if ${AGASC_HDF5_FILE} is defined; or use the latest version of proseco_agasc in default_agasc_dir().

If agasc_file ends with the suffix .h5 then it is useed as-is.

If agasc_file ends with * then the latest version of the matching AGASC file in default_agasc_dir() is useed. For example, proseco_agasc_* could use ${SKA}/data/agasc/proseco_agasc_1p7.h5.

Any other ending for agasc_file raises a ValueError.

The default AGASC directory is the environment variable ${AGASC_DIR} if defined, otherwise ${SKA}/data/agasc.

The default AGASC supplement file is <AGASC_DIR>/agasc_supplement.h5.

Example:

>>> import agasc
>>> star = agasc.get_star(636629880)
>>> for name in star.colnames:
...     print('{:12s} : {}'.format(name, star[name]))
AGASC_ID     : 636629880
RA           : 125.64184
DEC          : -4.23235
POS_ERR      : 300
POS_CATID    : 6
EPOCH        : 1983.0
PM_RA        : -9999
PM_DEC       : -9999
PM_CATID     : 0
PLX          : -9999
PLX_ERR      : -9999
PLX_CATID    : 0
MAG_ACA      : 12.1160011292
MAG_ACA_ERR  : 45
CLASS        : 0
MAG          : 13.2700004578
...
Parameters:
idint

AGASC id

agasc_fileOptional[str]

Path to the AGASC file (default=None)

dateOptional[CxoTimeLike]

Date for proper motion (default=Now)

fix_color1bool

Set COLOR1=COLOR2 * 0.85 for stars with V-I color (default=True)

use_supplementOptional[bool]

Use estimated mag from AGASC supplement where available (default=value of AGASC_SUPPLEMENT_ENABLED env var, or True if not defined)

Returns:
astropy.table.Table

Row of entry for id

agasc.agasc.get_stars(ids, agasc_file=None, dates=None, method_threshold=5000, fix_color1=True, use_supplement=None)[source]

Get AGASC catalog entries for star ids at dates.

The input ids and dates are broadcast together for the output shape (though note that the result is flattened in the end). If both are scalar inputs then the output is a Table Row, otherwise the output is a Table.

This function has two possible methods for getting stars, either by using the HDF5 tables.read_where() function to get one star at a time from the HDF5 file, or by reading the entire table into memory and doing the search by making a dict index by AGASC ID. Tests indicate that the latter is faster for about 5000 or more stars, so this function will read the entire AGASC if the number of stars is greater than method_threshold.

Unlike the similar get_star function, this adds a DATE column indicating the date at which the star coordinates (RA_PMCORR, DEC_PMCORR) are computed.

By default, stars with available mag estimates or bad star entries in the AGASC supplement are updated in-place in the output stars Table:

  • MAG_ACA and MAG_ACA_ERR are set according to the supplement.

  • MAG_CATID (mag catalog ID) is set to agasc.MAG_CATID_SUPPLEMENT.

  • If COLOR1 is 0.7 or 1.5 then it is changed to 0.69 or 1.49 respectively. Those particular values do not matter except that they are different from the “status flag” values of 0.7 (no color => very unreliable mag estimate) or 1.5 (red star => somewhat unreliable mag estimate) that have special meaning based on deep heritage in the AGASC catalog itself.

  • If AGASC_ID is in the supplement bad stars table then CLASS is set to agasc.BAD_CLASS_SUPPLEMENT.

To disable the magnitude / bad star updates from the AGASC supplement, see the set_supplement_enabled context manager / decorator.

If agasc_file is not specified or is None then use either default_agasc_dir()/${AGASC_HDF5_FILE} if ${AGASC_HDF5_FILE} is defined; or use the latest version of proseco_agasc in default_agasc_dir().

If agasc_file ends with the suffix .h5 then it is useed as-is.

If agasc_file ends with * then the latest version of the matching AGASC file in default_agasc_dir() is useed. For example, proseco_agasc_* could use ${SKA}/data/agasc/proseco_agasc_1p7.h5.

Any other ending for agasc_file raises a ValueError.

The default AGASC directory is the environment variable ${AGASC_DIR} if defined, otherwise ${SKA}/data/agasc.

The default AGASC supplement file is <AGASC_DIR>/agasc_supplement.h5.

Example::
>>> import agasc
>>> star = agasc.get_stars(636629880)
>>> for name in star.colnames:
...     print('{:12s} : {}'.format(name, star[name]))
AGASC_ID     : 636629880
RA           : 125.64184
DEC          : -4.23235
POS_ERR      : 300
POS_CATID    : 6
EPOCH        : 1983.0
PM_RA        : -9999
PM_DEC       : -9999
PM_CATID     : 0
PLX          : -9999
PLX_ERR      : -9999
PLX_CATID    : 0
MAG_ACA      : 12.1160011292
MAG_ACA_ERR  : 45
CLASS        : 0
MAG          : 13.2700004578
...
Parameters:
idsint or array_like

AGASC ids (scalar or array)

agasc_filestr, optional

AGASC file (optional)

datesCxoTimeLike, optional

Dates for proper motion (scalar or array) (default=Now)

method_thresholdint

Number of stars above which to use the “read_entire_agasc” method

fix_color1bool

set COLOR1=COLOR2 * 0.85 for stars with V-I color (default=True)

use_supplementbool, optional

Use estimated mag from AGASC supplement where available (default=value of AGASC_SUPPLEMENT_ENABLED env var, or True if not defined)

Returns:
astropy Table of AGASC entries, or Table Row of one entry for scalar input
agasc.agasc.read_h5_table(h5_file, row0=None, row1=None, path='data', cache=False, columns=None)[source]

Read HDF5 table columns from group path in h5_file.

If row0 and row1 are specified then only the rows in that range are read, e.g. data[row0:row1].

If cache is True then the data for the last read is cached in memory. The cache key is (h5_file, path, columns) and up to 128 cache entries are kept.

Parameters:
h5_filestr, Path, tables.file.File

Path to the HDF5 file to read.

row0int, optional

First row to read. Default is None (read from first row).

row1int, optional

Last row to read. Default is None (read to last row).

pathstr, optional

Path to the data table in the HDF5 file. Default is ‘data’.

cachebool, optional

Whether to cache the read data. Default is False.

columnslist or tuple, optional

Column names to read from the file. If not specified, all columns are read.

Returns:
outnp.ndarray

The HDF5 data as a numpy structured array

agasc.agasc.set_supplement_enabled(value)[source]

Decorator / context manager to temporarily set the default for use of AGASC supplement in query functions.

This sets the default for the use_supplement argument in AGASC function calls if the user does not supply that argument.

This is mostly for testing or legacy applications to override the default behavior to use the AGASC supplement star mags when available.

Examples:

import agasc

# Disable use of the supplement for the context block
with agasc.set_supplement_enabled(False):
    aca = proseco.get_aca_catalog(obsid=8008)

# Disable use of the supplement for the function
@agasc.set_supplement_enabled(False)
def test_get_aca_catalog():
    aca = proseco.get_aca_catalog(obsid=8008)
    ...

# Globally disable use of the supplement everywhere
os.environ[agasc.SUPPLEMENT_ENABLED_VAR] = 'False'
Parameters:
valuebool

Whether to use the AGASC supplement in the context / decorator

agasc.agasc.sphere_dist(ra1, dec1, ra2, dec2)[source]

Haversine formula for angular distance on a sphere: more stable at poles. This version uses arctan instead of arcsin and thus does better with sign conventions. This uses numexpr to speed expression evaluation by a factor of 2 to 3.

Parameters:
ra1array_like

first RA (deg)

dec1array_like

first Dec (deg)

ra2array_like

second RA (deg)

dec2array_like

second Dec (deg)

Returns:
angular separation distance (deg)array_like
agasc.agasc.write_agasc(filename, stars, version, nside=64, order=TableOrder.HEALPIX, full_agasc=True)[source]

Write AGASC stars to a new HDF5 file.

The table is coerced to the correct dtype if necessary (TABLE_DTYPE).

Parameters:
filenamestr

The path to the HDF5 file to write to.

starsnp.ndarray

The AGASC stars to write.

versionstr

The AGASC version number. This sets an attribute in the table.

nsideint, optional

The HEALPix NSIDE parameter to use for the HEALPix index table. Default is 64.

orderTableOrder, optional

The order of the stars in the AGASC file (Default is TableOrder.HEALPIX). The options are:

  • TableOrder.HEALPIX. The stars are sorted using a HEALPix index.

  • TableOrder.DEC. The stars are sorted by declination.

full_agascbool, optional

Whether writing a full AGASC table with all columns or a subset (normally proseco). Default is True, in which case all AGASC columns are required.

agasc.paths.default_agasc_dir()[source]

Path to the AGASC directory.

This returns the AGASC_DIR environment variable if defined, otherwise $SKA/data/agasc.

Returns:
Path
agasc.paths.default_agasc_file()[source]

Default main AGASC file.

Returns:
str
agasc.supplement.utils.add_bad_star(filename, bad, dry_run=False, create=False)[source]

Update the ‘bad’ table of the AGASC supplement.

Parameters:
filenamepathlib.Path

AGASC supplement filename.

badlist

List of pairs (agasc_id, source)

dry_runbool

Do not save the table.

createbool

Create a supplement file if it does not exist

agasc.supplement.utils.get_supplement_table(name, agasc_dir=None, as_dict=False)[source]

Get one of the tables in the AGASC supplement.

This function gets one of the supplement tables, specified with name:

  • bad: Bad stars (agasc_id, source)

  • mags: Estimated mags (agasc_id, mag_aca mag_aca_err)

  • obs: Star-observation status for mag estimation (mp_starcat_time, agasc_id, obsid, status, comments)

This function is cached with a timeout of an hour, so you can call it repeatedly with no penalty in performance.

If as_dict=False (default) then the table is returned as an astropy Table.

If as_dict=True then the table is returned as a dict of {key: value} pairs. For mags and bad, the key is agasc_id. For obs the key is the (agasc_id, mp_starcat_time) tuple. In all cases the value is a dict of the remaining columns.

Parameters:
namestr

Table name within the AGASC supplement HDF5 file

agasc_dirstr, optional

directory containing the AGASC supplement HDF5 file (default=same directory as the AGASC file)

as_dictbool

return result as a dictionary (default=False)

Returns:
supplement table as Table or dict
agasc.supplement.utils.save_version(filename, table_name)[source]

Save the version of a supplement table to the “versions” table.

Along with the version, the time of update is also added to another table called “last_updated”

Example usage:

from agasc.supplement.utils import save_version
save_version('agasc_supplement.h5', mags='4.10.2')

The different versions can be retrieved from the default supplement:

from agasc.supplement.utils import get_supplement_table
versions = get_supplement_table('agasc_versions')
Parameters:
filename

pathlib.Path

table_name

str or list

agasc.supplement.utils.update_mags_table(filename, mags, dry_run=False, create=False)[source]

Update the ‘mags’ table of the AGASC supplement.

Parameters:
filename

AGASC supplement filename

magslist of dict or table.Table

list entries are dictionaries like:: {‘agasc_id’: 1, ‘mag_aca’: 9., ‘mag_aca_err’: 0.2, ‘last_obs_time’: 541074324.949}

dry_runbool

Do not save the table.

agasc.supplement.utils.update_obs_table(filename, obs, dry_run=False, create=False)[source]

Update the ‘obs’ table of the AGASC supplement.

Parameters:
filename

AGASC supplement filename

obslist of dict or table.Table

Dictionary with status flag for specific observations. list entries are dictionaries like:: {‘agasc_id’: 1, ‘mp_starcat_time’: ‘2009:310:17:26:44.706’, ‘obsid’: 0, ‘status’: 0, ‘comments’: ‘some comment’} All the keys are optional except ‘status’, as long as the observations are uniquely defined. If ‘agasc_id’ is not given, then it applies to all stars in that observation.

dry_runbool

Do not save the table.

createbool

Create a supplement file if it does not exist