Skip to content

Star Catalog Functions

Functions and types for accessing fixed-epoch star catalogs (FK5, Hipparcos, Tycho-2).

All functions are available via brahe.datasets.star_catalogs.<function_name>.

get_fk5

star_catalogs_get_fk5 builtin 

star_catalogs_get_fk5(cache_max_age: float = None) -> FK5Catalog

Download and parse the FK5 star catalog.

Fetches the fixed-width FK5 catalog text file with file-based caching. FK5 is a fixed, published catalog, so by default the cached copy never goes stale.

Parameters:

Name Type Description Default
cache_max_age float

Maximum cache age in seconds. Defaults to None, meaning the cached copy never goes stale. Pass 0 to force a fresh download.

 None

Returns:

Name Type Description
FK5Catalog FK5Catalog

Parsed FK5 catalog container

Raises:

Type Description
BraheError

If download or parsing fails.
Example 
1
2
3
4
import brahe.datasets as datasets

fk5 = datasets.star_catalogs.get_fk5()
print(f"Loaded {len(fk5)} records")

get_hipparcos

star_catalogs_get_hipparcos builtin 

star_catalogs_get_hipparcos(cache_max_age: float = None) -> HipparcosCatalog

Download and parse the Hipparcos star catalog.

Fetches the pipe-delimited Hipparcos catalog text file with file-based caching. Hipparcos is a fixed, published catalog, so by default the cached copy never goes stale.

Parameters:

Name Type Description Default
cache_max_age float

Maximum cache age in seconds. Defaults to None, meaning the cached copy never goes stale. Pass 0 to force a fresh download.

 None

Returns:

Name Type Description
HipparcosCatalog HipparcosCatalog

Parsed Hipparcos catalog container

Raises:

Type Description
BraheError

If download or parsing fails.
Example 
1
2
3
4
5
6
7
8
import brahe.datasets as datasets

hip = datasets.star_catalogs.get_hipparcos()
print(f"Loaded {len(hip)} records")

sirius = hip.get_by_id(32349)
if sirius:
    print(f"Sirius Vmag: {sirius.vmag}")

get_tycho2

star_catalogs_get_tycho2 builtin 

star_catalogs_get_tycho2(cache_max_age: float = None) -> Tycho2Catalog

Download and parse the Tycho-2 star catalog.

Fetches the pipe-delimited Tycho-2 catalog text file with file-based caching. Tycho-2 is a fixed, published catalog, so by default the cached copy never goes stale. The source file is large (~526 MB, ~2.54 million records), so the first call may take some time.

Parameters:

Name Type Description Default
cache_max_age float

Maximum cache age in seconds. Defaults to None, meaning the cached copy never goes stale. Pass 0 to force a fresh download.

 None

Returns:

Name Type Description
Tycho2Catalog Tycho2Catalog

Parsed Tycho-2 catalog container

Raises:

Type Description
BraheError

If download or parsing fails.
Example 
1
2
3
4
import brahe.datasets as datasets

tyc = datasets.star_catalogs.get_tycho2()
print(f"Loaded {len(tyc)} records")

FK5Catalog

FK5Catalog 

FK5Catalog()

Container for FK5 star catalog records with lookup and filter methods.

Provides lookup by FK5 identifier, magnitude filtering, and cone-search filtering. Filter methods return a new FK5Catalog instance.

Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import brahe.datasets as datasets

fk5 = datasets.star_catalogs.get_fk5()
print(f"Loaded {len(fk5)} records")

bright = fk5.filter_by_magnitude(3.0)
print(f"Bright stars: {len(bright)}")

df = fk5.to_dataframe()
print(df.head())

Initialize instance.

filter_by_cone method descriptor 

filter_by_cone(ra: float, dec: float, radius: float, angle_format: AngleFormat) -> FK5Catalog

Filter records to those within an angular radius of a cone center.

Parameters:

Name Type Description Default
ra float

Cone center right ascension. Units: angle

 required
dec float

Cone center declination. Units: angle

 required
radius float

Cone half-angle. Units: angle

 required
angle_format AngleFormat

Format for ra, dec, and radius (RADIANS or DEGREES)

 required

Returns:

Name Type Description
FK5Catalog FK5Catalog

New catalog containing matching records

filter_by_magnitude method descriptor 

filter_by_magnitude(max_mag: float) -> FK5Catalog

Filter records to those with visual magnitude at or brighter than max_mag.

Records with unknown magnitude are excluded. Recall that smaller (more negative) magnitudes are brighter, so this keeps vmag <= max_mag.

Parameters:

Name Type Description Default
max_mag float

Faintest visual magnitude to include. Units: mag

 required

Returns:

Name Type Description
FK5Catalog FK5Catalog

New catalog containing matching records

get_by_id method descriptor 

get_by_id(fk5_id: int) -> Any

Look up a record by FK5 catalog identifier.

Parameters:

Name Type Description Default
fk5_id int

FK5 catalog running number

 required

Returns:

Type Description
Any

FK5Record | None: The matching record, or None if not found

records method descriptor 

records() -> list[FK5Record]

Get all records as a list.

Returns:

Type Description
list[FK5Record]

list[FK5Record]: All records in the catalog

to_dataframe method descriptor 

to_dataframe() -> DataFrame

Convert the catalog to a Polars DataFrame.

One row per record, one column per field. Missing optional values become nulls.

Returns:

Type Description
DataFrame

polars.DataFrame: DataFrame with all catalog fields as columns
Example 
1
2
df = fk5.to_dataframe()
print(df.head())

FK5Record

FK5Record 

FK5Record()

A single record from the FK5 star catalog.

Positions and proper motions are J2000.0 (the FK5 system's native equinox/equator); the legacy B1950 columns and formal-error columns of the source file are not represented.

Attributes:

Name Type Description
fk5_id int

FK5 catalog running number
ra float

Right ascension, J2000.0. Units: deg
dec float

Declination, J2000.0. Units: deg
pm_ra float

Proper motion in right ascension (mu_alpha = mu_alpha cos(dec)), J2000.0. Units: mas/yr*
pm_dec float

Proper motion in declination, J2000.0. Units: mas/yr
epoch_ra_1900 float | None

Mean epoch of right ascension observations, minus 1900. Units: yr
epoch_dec_1900 float | None

Mean epoch of declination observations, minus 1900. Units: yr
vmag float | None

Visual magnitude. Units: mag
vmag_flag str | None

Visual magnitude quality/note flag
spectral_type str | None

Spectral type
parallax float | None

Trigonometric parallax. Units: mas
radial_velocity float | None

Radial velocity. Units: km/s
hd_id str | None

Henry Draper (HD) catalog identifier
dm_id str | None

Durchmusterung (DM) catalog identifier
gc_id str | None

Groombridge Catalogue (GC) identifier
Example 
1
2
3
4
5
6
import brahe.datasets as datasets

fk5 = datasets.star_catalogs.get_fk5()
record = fk5.get_by_id(699)
if record:
    print(f"RA: {record.ra} deg, Dec: {record.dec} deg")

Initialize instance.

dec property 

dec: Any

TODO: Add docstring

dm_id property 

dm_id: Any

TODO: Add docstring

epoch_dec_1900 property 

epoch_dec_1900: Any

TODO: Add docstring

epoch_ra_1900 property 

epoch_ra_1900: Any

TODO: Add docstring

fk5_id property 

fk5_id: Any

TODO: Add docstring

gc_id property 

gc_id: Any

TODO: Add docstring

hd_id property 

hd_id: Any

TODO: Add docstring

parallax property 

parallax: Any

TODO: Add docstring

pm_dec property 

pm_dec: Any

TODO: Add docstring

pm_ra property 

pm_ra: Any

TODO: Add docstring

ra property 

ra: Any

TODO: Add docstring

radial_velocity property 

radial_velocity: Any

TODO: Add docstring

spectral_type property 

spectral_type: Any

TODO: Add docstring

vmag property 

vmag: Any

TODO: Add docstring

vmag_flag property 

vmag_flag: Any

TODO: Add docstring

id method descriptor 

id() -> str

Catalog identifier string.

Returns:

Name Type Description
str str

Catalog identifier, e.g. "FK5 1"

name method descriptor 

name() -> Any

Common or cross-catalog name, if available.

Returns:

Type Description
Any

str | None: Cross-catalog name, e.g. "HD 358"

radec_at_epoch method descriptor 

radec_at_epoch(epoch: Epoch, angle_format: AngleFormat) -> tuple[float, float]

Right ascension and declination propagated to a target epoch using proper motion.

Parameters:

Name Type Description Default
epoch Epoch

Target epoch to propagate the position to

 required
angle_format AngleFormat

Desired angle format (RADIANS or DEGREES) for the returned (ra, dec)

 required

Returns:

Type Description
tuple[float, float]

tuple[float, float]: Right ascension and declination at epoch. Units: (angle, angle)
Example 
1
2
3
4
import brahe as bh

epc = bh.Epoch.from_datetime(2030, 1, 1, 0, 0, 0.0, 0.0, "UTC")
ra, dec = record.radec_at_epoch(epc, bh.AngleFormat.DEGREES)

unit_vector method descriptor 

unit_vector() -> ndarray

Unit vector toward the star, evaluated at the record's reference epoch.

Computed from ra/dec with a unit range, so no proper-motion propagation is applied.

Returns:

Type Description
ndarray

numpy.ndarray: Cartesian unit vector [x, y, z] toward the star. Units: dimensionless

HipparcosCatalog

HipparcosCatalog 

HipparcosCatalog()

Container for Hipparcos star catalog records with lookup and filter methods.

Provides lookup by Hipparcos identifier, magnitude filtering, and cone-search filtering. Filter methods return a new HipparcosCatalog instance.

Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import brahe.datasets as datasets

hip = datasets.star_catalogs.get_hipparcos()
print(f"Loaded {len(hip)} records")

bright = hip.filter_by_magnitude(5.0)
print(f"Bright stars: {len(bright)}")

df = hip.to_dataframe()
print(df.head())

Initialize instance.

filter_by_cone method descriptor 

filter_by_cone(ra: float, dec: float, radius: float, angle_format: AngleFormat) -> HipparcosCatalog

Filter records to those within an angular radius of a cone center.

Parameters:

Name Type Description Default
ra float

Cone center right ascension. Units: angle

 required
dec float

Cone center declination. Units: angle

 required
radius float

Cone half-angle. Units: angle

 required
angle_format AngleFormat

Format for ra, dec, and radius (RADIANS or DEGREES)

 required

Returns:

Name Type Description
HipparcosCatalog HipparcosCatalog

New catalog containing matching records

filter_by_magnitude method descriptor 

filter_by_magnitude(max_mag: float) -> HipparcosCatalog

Filter records to those with visual magnitude at or brighter than max_mag.

Records with unknown magnitude are excluded. Recall that smaller (more negative) magnitudes are brighter, so this keeps vmag <= max_mag.

Parameters:

Name Type Description Default
max_mag float

Faintest visual magnitude to include. Units: mag

 required

Returns:

Name Type Description
HipparcosCatalog HipparcosCatalog

New catalog containing matching records

get_by_id method descriptor 

get_by_id(hip_id: int) -> Any

Look up a record by Hipparcos catalog identifier.

Parameters:

Name Type Description Default
hip_id int

Hipparcos catalog identifier

 required

Returns:

Type Description
Any

HipparcosRecord | None: The matching record, or None if not found

records method descriptor 

records() -> list[HipparcosRecord]

Get all records as a list.

Returns:

Type Description
list[HipparcosRecord]

list[HipparcosRecord]: All records in the catalog

to_dataframe method descriptor 

to_dataframe() -> DataFrame

Convert the catalog to a Polars DataFrame.

One row per record, one column per field. Missing optional values become nulls.

Returns:

Type Description
DataFrame

polars.DataFrame: DataFrame with all catalog fields as columns
Example 
1
2
df = hip.to_dataframe()
print(df.head())

HipparcosRecord

HipparcosRecord 

HipparcosRecord()

A single record from the Hipparcos star catalog.

Positions and proper motions are ICRS at epoch J1991.25. The Hipparcos main catalog does not carry a radial velocity column, so no radial velocity value is available for Hipparcos records.

Attributes:

Name Type Description
hip_id int

Hipparcos catalog identifier
vmag float | None

Visual magnitude. Units: mag
var_flag str | None

Magnitude uncertainty/variability flag
ra float

Right ascension, ICRS, epoch J1991.25. Units: deg
dec float

Declination, ICRS, epoch J1991.25. Units: deg
parallax float | None

Trigonometric parallax. Units: mas
pm_ra float | None

Proper motion in right ascension (mu_alpha = mu_alpha cos(dec)), ICRS. Units: mas/yr*
pm_dec float | None

Proper motion in declination, ICRS. Units: mas/yr
e_ra float | None

Standard error in right ascension. Units: mas
e_dec float | None

Standard error in declination. Units: mas
e_parallax float | None

Standard error in parallax. Units: mas
e_pm_ra float | None

Standard error in right ascension proper motion. Units: mas/yr
e_pm_dec float | None

Standard error in declination proper motion. Units: mas/yr
bt_mag float | None

Mean Tycho BT magnitude. Units: mag
vt_mag float | None

Mean Tycho VT magnitude. Units: mag
b_v float | None

Johnson B-V colour. Units: mag
hp_mag float | None

Hipparcos-system magnitude. Units: mag
hvar_type str | None

Variability type flag
mult_flag str | None

Double/multiple system flag
hd_id int | None

Henry Draper (HD) catalog identifier
bd_id str | None

Raw Bonner Durchmusterung (BD) identifier (see name() for the expanded form)
cod_id str | None

Raw Cordoba Durchmusterung (CoD) identifier (see name() for the expanded form)
cpd_id str | None

Raw Cape Photographic Durchmusterung (CPD) identifier (see name() for the expanded form)
spectral_type str | None

Spectral type
Example 
1
2
3
4
5
6
import brahe.datasets as datasets

hip = datasets.star_catalogs.get_hipparcos()
sirius = hip.get_by_id(32349)
if sirius:
    print(f"Vmag: {sirius.vmag}")

Initialize instance.

b_v property 

b_v: Any

TODO: Add docstring

bd_id property 

bd_id: Any

TODO: Add docstring

bt_mag property 

bt_mag: Any

TODO: Add docstring

cod_id property 

cod_id: Any

TODO: Add docstring

cpd_id property 

cpd_id: Any

TODO: Add docstring

dec property 

dec: Any

TODO: Add docstring

e_dec property 

e_dec: Any

TODO: Add docstring

e_parallax property 

e_parallax: Any

TODO: Add docstring

e_pm_dec property 

e_pm_dec: Any

TODO: Add docstring

e_pm_ra property 

e_pm_ra: Any

TODO: Add docstring

e_ra property 

e_ra: Any

TODO: Add docstring

hd_id property 

hd_id: Any

TODO: Add docstring

hip_id property 

hip_id: Any

TODO: Add docstring

hp_mag property 

hp_mag: Any

TODO: Add docstring

hvar_type property 

hvar_type: Any

TODO: Add docstring

mult_flag property 

mult_flag: Any

TODO: Add docstring

parallax property 

parallax: Any

TODO: Add docstring

pm_dec property 

pm_dec: Any

TODO: Add docstring

pm_ra property 

pm_ra: Any

TODO: Add docstring

ra property 

ra: Any

TODO: Add docstring

spectral_type property 

spectral_type: Any

TODO: Add docstring

var_flag property 

var_flag: Any

TODO: Add docstring

vmag property 

vmag: Any

TODO: Add docstring

vt_mag property 

vt_mag: Any

TODO: Add docstring

id method descriptor 

id() -> str

Catalog identifier string.

Returns:

Name Type Description
str str

Catalog identifier, e.g. "HIP 1"

name method descriptor 

name() -> Any

Common or cross-catalog name, if available.

Returns:

Type Description
Any

str | None: Cross-catalog name, e.g. "HD 224700"

radec_at_epoch method descriptor 

radec_at_epoch(epoch: Epoch, angle_format: AngleFormat) -> tuple[float, float]

Right ascension and declination propagated to a target epoch using proper motion.

Parameters:

Name Type Description Default
epoch Epoch

Target epoch to propagate the position to

 required
angle_format AngleFormat

Desired angle format (RADIANS or DEGREES) for the returned (ra, dec)

 required

Returns:

Type Description
tuple[float, float]

tuple[float, float]: Right ascension and declination at epoch. Units: (angle, angle)
Example 
1
2
3
4
import brahe as bh

epc = bh.Epoch.from_datetime(2030, 1, 1, 0, 0, 0.0, 0.0, "UTC")
ra, dec = record.radec_at_epoch(epc, bh.AngleFormat.DEGREES)

unit_vector method descriptor 

unit_vector() -> ndarray

Unit vector toward the star, evaluated at the record's reference epoch.

Computed from ra/dec with a unit range, so no proper-motion propagation is applied.

Returns:

Type Description
ndarray

numpy.ndarray: Cartesian unit vector [x, y, z] toward the star. Units: dimensionless

Tycho2Catalog

Tycho2Catalog 

Tycho2Catalog()

Container for Tycho-2 star catalog records with lookup and filter methods.

Provides lookup by TYC identifier triple, magnitude filtering, and cone-search filtering. Filter methods return a new Tycho2Catalog instance.

Example 
1
2
3
4
5
6
7
import brahe.datasets as datasets

tyc = datasets.star_catalogs.get_tycho2()
print(f"Loaded {len(tyc)} records")

bright = tyc.filter_by_magnitude(8.0)
print(f"Bright stars: {len(bright)}")

Initialize instance.

filter_by_cone method descriptor 

filter_by_cone(ra: float, dec: float, radius: float, angle_format: AngleFormat) -> Tycho2Catalog

Filter records to those within an angular radius of a cone center.

Parameters:

Name Type Description Default
ra float

Cone center right ascension. Units: angle

 required
dec float

Cone center declination. Units: angle

 required
radius float

Cone half-angle. Units: angle

 required
angle_format AngleFormat

Format for ra, dec, and radius (RADIANS or DEGREES)

 required

Returns:

Name Type Description
Tycho2Catalog Tycho2Catalog

New catalog containing matching records

filter_by_magnitude method descriptor 

filter_by_magnitude(max_mag: float) -> Tycho2Catalog

Filter records to those with visual magnitude at or brighter than max_mag.

Records with unknown magnitude are excluded. Recall that smaller (more negative) magnitudes are brighter, so this keeps vmag <= max_mag.

Parameters:

Name Type Description Default
max_mag float

Faintest visual magnitude to include. Units: mag

 required

Returns:

Name Type Description
Tycho2Catalog Tycho2Catalog

New catalog containing matching records

get_by_id method descriptor 

get_by_id(tyc1: int, tyc2: int, tyc3: int) -> Any

Look up a record by TYC identifier triple.

Parameters:

Name Type Description Default
tyc1 int

GSC region number

 required
tyc2 int

Running number within region

 required
tyc3 int

Component number (for double/multiple entries)

 required

Returns:

Type Description
Any

Tycho2Record | None: The matching record, or None if not found

records method descriptor 

records() -> list[Tycho2Record]

Get all records as a list.

Returns:

Type Description
list[Tycho2Record]

list[Tycho2Record]: All records in the catalog

to_dataframe method descriptor 

to_dataframe() -> DataFrame

Convert the catalog to a Polars DataFrame.

One row per record, one column per field. Missing optional values become nulls.

Returns:

Type Description
DataFrame

polars.DataFrame: DataFrame with all catalog fields as columns
Example 
1
2
df = tyc.to_dataframe()
print(df.head())

Tycho2Record

Tycho2Record 

Tycho2Record()

A single record from the Tycho-2 star catalog.

A small fraction of entries (pflag == "X") have no mean astrometric solution: their ra/dec/pm_ra/pm_dec/epoch_ra/epoch_dec fields are all None. id()/name()/unit_vector()/ radec_at_epoch() fall back to the always-present observed position (ra_observed/dec_observed, epoch ~1991.5) for such records.

Tycho-2 does not carry a parallax or radial velocity column.

Attributes:

Name Type Description
tyc1 int

Tycho-2 identifier, first component (GSC region number)
tyc2 int

Tycho-2 identifier, second component (running number within region)
tyc3 int

Tycho-2 identifier, third component (component number, for double/multiple entries)
pflag str | None

Mean position flag: None/blank for a normal entry, "P" if the mean position was obtained from the photocenter, "X" if no mean position could be computed
ra float | None

Mean right ascension, ICRS. None when pflag == "X". Units: deg
dec float | None

Mean declination, ICRS. None when pflag == "X". Units: deg
pm_ra float | None

Proper motion in right ascension (mu_alpha = mu_alpha cos(dec)). Units: mas/yr*
pm_dec float | None

Proper motion in declination. Units: mas/yr
epoch_ra float | None

Mean epoch of the right ascension. Units: yr
epoch_dec float | None

Mean epoch of the declination. Units: yr
bt_mag float | None

Tycho-2 BT (blue) magnitude. Units: mag
vt_mag float | None

Tycho-2 VT (visual) magnitude. Units: mag
vmag float | None

Johnson V-band approximation. Units: mag
tycho1_flag str | None

Set ("T") if this entry also has a Tycho-1 record
hip_id int | None

Hipparcos catalog identifier, if this star is also in Hipparcos
ra_observed float

Observed right ascension, epoch ~1991.5. Always present. Units: deg
dec_observed float

Observed declination, epoch ~1991.5. Always present. Units: deg
Example 
1
2
3
4
import brahe.datasets as datasets

tyc = datasets.star_catalogs.get_tycho2()
record = tyc.get_by_id(1, 8, 1)

Initialize instance.

bt_mag property 

bt_mag: Any

TODO: Add docstring

dec property 

dec: Any

TODO: Add docstring

dec_observed property 

dec_observed: Any

TODO: Add docstring

epoch_dec property 

epoch_dec: Any

TODO: Add docstring

epoch_ra property 

epoch_ra: Any

TODO: Add docstring

hip_id property 

hip_id: Any

TODO: Add docstring

pflag property 

pflag: Any

TODO: Add docstring

pm_dec property 

pm_dec: Any

TODO: Add docstring

pm_ra property 

pm_ra: Any

TODO: Add docstring

ra property 

ra: Any

TODO: Add docstring

ra_observed property 

ra_observed: Any

TODO: Add docstring

tyc1 property 

tyc1: Any

TODO: Add docstring

tyc2 property 

tyc2: Any

TODO: Add docstring

tyc3 property 

tyc3: Any

TODO: Add docstring

tycho1_flag property 

tycho1_flag: Any

TODO: Add docstring

vmag property 

vmag: Any

TODO: Add docstring

vt_mag property 

vt_mag: Any

TODO: Add docstring

id method descriptor 

id() -> str

Catalog identifier string.

Returns:

Name Type Description
str str

Catalog identifier, e.g. "TYC 1-8-1"

name method descriptor 

name() -> Any

Common or cross-catalog name, if available.

Returns:

Type Description
Any

str | None: Cross-catalog name, e.g. "HIP 416"

radec_at_epoch method descriptor 

radec_at_epoch(epoch: Epoch, angle_format: AngleFormat) -> tuple[float, float]

Right ascension and declination propagated to a target epoch using proper motion.

Parameters:

Name Type Description Default
epoch Epoch

Target epoch to propagate the position to

 required
angle_format AngleFormat

Desired angle format (RADIANS or DEGREES) for the returned (ra, dec)

 required

Returns:

Type Description
tuple[float, float]

tuple[float, float]: Right ascension and declination at epoch. Units: (angle, angle)
Example 
1
2
3
4
import brahe as bh

epc = bh.Epoch.from_datetime(2030, 1, 1, 0, 0, 0.0, 0.0, "UTC")
ra, dec = record.radec_at_epoch(epc, bh.AngleFormat.DEGREES)

unit_vector method descriptor 

unit_vector() -> ndarray

Unit vector toward the star, evaluated at the record's reference epoch.

Computed from the effective ra/dec (falling back to the observed position for pflag == "X" records) with a unit range, so no proper-motion propagation is applied.

Returns:

Type Description
ndarray

numpy.ndarray: Cartesian unit vector [x, y, z] toward the star. Units: dimensionless

See Also