GCAT Functions¶

Functions and types for accessing Jonathan McDowell's GCAT satellite catalogs (SATCAT and PSATCAT).

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

gcat_get_satcat¶

gcat_get_satcat `builtin` ¶

gcat_get_satcat(cache_max_age: float = None) -> GCATSatcat

Download and parse the GCAT SATCAT catalog.

Fetches the SATCAT TSV file from GCAT with file-based caching (default 24h). Returns a GCATSatcat container with search and filter methods.

Parameters:

Name	Type	Description	Default
`cache_max_age`	`float`	Maximum cache age in seconds. Defaults to 86400 (24 hours). Pass 0 to force a fresh download.	`None`

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	Parsed SATCAT catalog container

Raises:

Type	Description
`BraheError`	If download or parsing fails.

Example

import brahe.datasets as datasets

# Default 24h cache
satcat = datasets.gcat.get_satcat()
print(f"Loaded {len(satcat)} records")

# Custom cache age (1 hour)
satcat = datasets.gcat.get_satcat(cache_max_age=3600)

# Look up ISS
iss = satcat.get_by_satcat("25544")
if iss:
    print(f"ISS: {iss.name}")

gcat_get_psatcat¶

gcat_get_psatcat `builtin` ¶

gcat_get_psatcat(cache_max_age: float = None) -> GCATPsatcat

Download and parse the GCAT PSATCAT catalog.

Fetches the PSATCAT TSV file from GCAT with file-based caching (default 24h). Returns a GCATPsatcat container with search and filter methods.

Parameters:

Name	Type	Description	Default
`cache_max_age`	`float`	Maximum cache age in seconds. Defaults to 86400 (24 hours). Pass 0 to force a fresh download.	`None`

Returns:

Name	Type	Description
`GCATPsatcat`	`GCATPsatcat`	Parsed PSATCAT catalog container

Raises:

Type	Description
`BraheError`	If download or parsing fails.

Example

import brahe.datasets as datasets

psatcat = datasets.gcat.get_psatcat()
print(f"Loaded {len(psatcat)} records")

active = psatcat.filter_active()
print(f"Active payloads: {len(active)}")

GCATSatcat¶

GCATSatcat ¶

GCATSatcat()

Container for GCAT SATCAT records with search and filter methods.

Provides lookup by JCAT/SATCAT number, name search, and various field-based filters. All filter methods return a new GCATSatcat instance.

Example

import brahe.datasets as datasets

satcat = datasets.gcat.get_satcat()
print(f"Loaded {len(satcat)} records")

# Search by name
iss_results = satcat.search_by_name("ISS")
print(f"Found {len(iss_results)} ISS-related objects")

# Filter by type and status
active_payloads = satcat.filter_by_type("P").filter_by_status("O")

# Convert to DataFrame
df = satcat.to_dataframe()
print(df.head())

Initialize instance.

filter_by_apogee_range ¶

filter_by_apogee_range(min_km: float, max_km: float) -> GCATSatcat

Filter records by apogee altitude range in km.

Parameters:

Name	Type	Description	Default
`min_km`	`float`	Minimum apogee altitude in km	required
`max_km`	`float`	Maximum apogee altitude in km	required

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	New catalog containing matching records

Example

leo = satcat.filter_by_apogee_range(200.0, 2000.0)

filter_by_inc_range ¶

filter_by_inc_range(min_deg: float, max_deg: float) -> GCATSatcat

Filter records by inclination range in degrees.

Parameters:

Name	Type	Description	Default
`min_deg`	`float`	Minimum inclination in degrees	required
`max_deg`	`float`	Maximum inclination in degrees	required

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	New catalog containing matching records

Example

polar = satcat.filter_by_inc_range(85.0, 100.0)

filter_by_owner ¶

filter_by_owner(owner: str) -> GCATSatcat

Filter records by owner (exact match).

Parameters:

Name	Type	Description	Default
`owner`	`str`	Owner/operator organization name	required

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	New catalog containing matching records

Example

nasa_objects = satcat.filter_by_owner("NASA")

filter_by_perigee_range ¶

filter_by_perigee_range(min_km: float, max_km: float) -> GCATSatcat

Filter records by perigee altitude range in km.

Parameters:

Name	Type	Description	Default
`min_km`	`float`	Minimum perigee altitude in km	required
`max_km`	`float`	Maximum perigee altitude in km	required

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	New catalog containing matching records

Example

leo = satcat.filter_by_perigee_range(200.0, 2000.0)

filter_by_state ¶

filter_by_state(state: str) -> GCATSatcat

Filter records by responsible state (exact match).

Parameters:

Name	Type	Description	Default
`state`	`str`	State/country code (e.g. "US", "RU")	required

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	New catalog containing matching records

Example

us_objects = satcat.filter_by_state("US")

filter_by_status ¶

filter_by_status(status: str) -> GCATSatcat

Filter records by status code (exact match).

Parameters:

Name	Type	Description	Default
`status`	`str`	Status code (e.g. "O" for operational, "D" for decayed)	required

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	New catalog containing matching records

Example

operational = satcat.filter_by_status("O")

filter_by_type ¶

filter_by_type(object_type: str) -> GCATSatcat

Filter records by object type (exact match).

Parameters:

Name	Type	Description	Default
`object_type`	`str`	Object type code (e.g. "P" for payload, "R" for rocket body)	required

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	New catalog containing matching records

Example

payloads = satcat.filter_by_type("P")

get_by_jcat ¶

get_by_jcat(jcat: str) -> GCATSatcatRecord

Look up a record by JCAT identifier.

Parameters:

Name	Type	Description	Default
`jcat`	`str`	JCAT catalog identifier	required

Returns:

Type	Description
`GCATSatcatRecord`	GCATSatcatRecord \| None: The matching record, or None if not found

Example

record = satcat.get_by_jcat("S049652")

get_by_satcat ¶

get_by_satcat(satcat_num: str) -> GCATSatcatRecord

Look up a record by NORAD SATCAT number.

Parameters:

Name	Type	Description	Default
`satcat_num`	`str`	NORAD SATCAT number (e.g. "25544" for ISS)	required

Returns:

Type	Description
`GCATSatcatRecord`	GCATSatcatRecord \| None: The matching record, or None if not found

Example

iss = satcat.get_by_satcat("25544")

records ¶

records() -> list[GCATSatcatRecord]

Get all records as a list.

Returns:

Type	Description
`list[GCATSatcatRecord]`	list[GCATSatcatRecord]: All records in the catalog

search_by_name ¶

search_by_name(pattern: str) -> GCATSatcat

Search records by name (case-insensitive substring match).

Parameters:

Name	Type	Description	Default
`pattern`	`str`	Search pattern (case-insensitive)	required

Returns:

Name	Type	Description
`GCATSatcat`	`GCATSatcat`	New catalog containing matching records

Example

starlinks = satcat.search_by_name("starlink")

to_dataframe ¶

to_dataframe() -> DataFrame

Convert the catalog to a Polars DataFrame.

All record fields become columns. String fields are Utf8 type, numeric fields are Float64 type. Missing values are None.

Returns:

Type	Description
`DataFrame`	polars.DataFrame: DataFrame with all catalog fields as columns

Example

df = satcat.to_dataframe()
print(df.head())
print(df.filter(pl.col("status") == "O").shape)

GCATPsatcat¶

GCATPsatcat ¶

GCATPsatcat()

Container for GCAT PSATCAT records with search and filter methods.

Provides lookup by JCAT, name search, and various field-based filters. All filter methods return a new GCATPsatcat instance.

Example

import brahe.datasets as datasets

psatcat = datasets.gcat.get_psatcat()
print(f"Loaded {len(psatcat)} records")

# Filter for active payloads
active = psatcat.filter_active()
print(f"Active payloads: {len(active)}")

# Convert to DataFrame
df = psatcat.to_dataframe()

Initialize instance.

filter_active ¶

filter_active() -> GCATPsatcat

Filter for active payloads (result is "S" and no end date or tdate="*").

Returns:

Name	Type	Description
`GCATPsatcat`	`GCATPsatcat`	New catalog containing active records

filter_by_category ¶

filter_by_category(category: str) -> GCATPsatcat

Filter records by mission category (exact match).

Parameters:

Name	Type	Description	Default
`category`	`str`	Category code (e.g. "COM", "IMG", "TECH", "SCI", "NAV")	required

Returns:

Name	Type	Description
`GCATPsatcat`	`GCATPsatcat`	New catalog containing matching records

filter_by_class ¶

filter_by_class(class_: str) -> GCATPsatcat

Filter records by mission class (exact match).

Parameters:

Name	Type	Description	Default
`class_`	`str`	Mission class code (e.g. "A", "B", "C", "D")	required

Returns:

Name	Type	Description
`GCATPsatcat`	`GCATPsatcat`	New catalog containing matching records

filter_by_result ¶

filter_by_result(result: str) -> GCATPsatcat

Filter records by mission result (exact match).

Parameters:

Name	Type	Description	Default
`result`	`str`	Result code (e.g. "S" for success, "F" for failure)	required

Returns:

Name	Type	Description
`GCATPsatcat`	`GCATPsatcat`	New catalog containing matching records

get_by_jcat ¶

get_by_jcat(jcat: str) -> GCATPsatcatRecord

Look up a record by JCAT identifier.

Parameters:

Name	Type	Description	Default
`jcat`	`str`	JCAT catalog identifier	required

Returns:

Type	Description
`GCATPsatcatRecord`	GCATPsatcatRecord \| None: The matching record, or None if not found

records ¶

records() -> list[GCATPsatcatRecord]

Get all records as a list.

Returns:

Type	Description
`list[GCATPsatcatRecord]`	list[GCATPsatcatRecord]: All records in the catalog

search_by_name ¶

search_by_name(pattern: str) -> GCATPsatcat

Search records by name (case-insensitive substring match).

Parameters:

Name	Type	Description	Default
`pattern`	`str`	Search pattern (case-insensitive)	required

Returns:

Name	Type	Description
`GCATPsatcat`	`GCATPsatcat`	New catalog containing matching records

to_dataframe ¶

to_dataframe() -> DataFrame

Convert the catalog to a Polars DataFrame.

Returns:

Type	Description
`DataFrame`	polars.DataFrame: DataFrame with all catalog fields as columns

Example

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

GCATSatcatRecord¶

GCATSatcatRecord ¶

GCATSatcatRecord()

A single record from the GCAT SATCAT catalog.

Contains physical, orbital, and administrative metadata for an artificial space object. All 41+ columns from the satcat.tsv file are represented.

Attributes:

Name	Type	Description
`jcat`	`str`	JCAT catalog identifier (primary key)
`satcat`	`str \| None`	NORAD SATCAT number
`launch_tag`	`str \| None`	Launch tag identifier
`piece`	`str \| None`	Piece designation
`object_type`	`str \| None`	Object type code
`name`	`str \| None`	Current object name
`pl_name`	`str \| None`	Payload name
`ldate`	`str \| None`	Launch date
`parent`	`str \| None`	Parent object identifier
`sdate`	`str \| None`	Separation/deployment date
`primary`	`str \| None`	Primary body orbited
`ddate`	`str \| None`	Decay/deorbit date
`status`	`str \| None`	Current status code
`dest`	`str \| None`	Destination/orbit description
`owner`	`str \| None`	Owner/operator organization
`state`	`str \| None`	Responsible state/country
`manufacturer`	`str \| None`	Manufacturer organization
`bus`	`str \| None`	Spacecraft bus type
`motor`	`str \| None`	Motor/propulsion type
`mass`	`float \| None`	Launch mass in kg
`mass_flag`	`str \| None`	Mass quality flag
`dry_mass`	`float \| None`	Dry mass in kg
`dry_flag`	`str \| None`	Dry mass quality flag
`tot_mass`	`float \| None`	Total mass in kg
`tot_flag`	`str \| None`	Total mass quality flag
`length`	`float \| None`	Length in meters
`length_flag`	`str \| None`	Length quality flag
`diameter`	`float \| None`	Diameter in meters
`diameter_flag`	`str \| None`	Diameter quality flag
`span`	`float \| None`	Span in meters
`span_flag`	`str \| None`	Span quality flag
`shape`	`str \| None`	Shape description
`odate`	`str \| None`	Operational orbit epoch date
`perigee`	`float \| None`	Perigee altitude in km
`perigee_flag`	`str \| None`	Perigee quality flag
`apogee`	`float \| None`	Apogee altitude in km
`apogee_flag`	`str \| None`	Apogee quality flag
`inc`	`float \| None`	Orbital inclination in degrees
`inc_flag`	`str \| None`	Inclination quality flag
`op_orbit`	`str \| None`	Operational orbit class
`oqual`	`str \| None`	Orbit quality code
`alt_names`	`str \| None`	Alternative names

Example

import brahe.datasets as datasets

satcat = datasets.gcat.get_satcat()
record = satcat.get_by_satcat("25544")
if record:
    print(f"Name: {record.name}")
    print(f"Perigee: {record.perigee} km")

Initialize instance.

alt_names `property` ¶

alt_names: Any

TODO: Add docstring

apogee `property` ¶

apogee: Any

TODO: Add docstring

apogee_flag `property` ¶

apogee_flag: Any

TODO: Add docstring

bus `property` ¶

bus: Any

TODO: Add docstring

ddate `property` ¶

ddate: Tuple[int, ...]

TODO: Add docstring

dest `property` ¶

dest: Any

TODO: Add docstring

diameter `property` ¶

diameter: Any

TODO: Add docstring

diameter_flag `property` ¶

diameter_flag: Any

TODO: Add docstring

dry_flag `property` ¶

dry_flag: Any

TODO: Add docstring

dry_mass `property` ¶

dry_mass: Any

TODO: Add docstring

inc `property` ¶

inc: Any

TODO: Add docstring

inc_flag `property` ¶

inc_flag: Any

TODO: Add docstring

jcat `property` ¶

jcat: Any

TODO: Add docstring

launch_tag `property` ¶

launch_tag: Any

TODO: Add docstring

ldate `property` ¶

ldate: Tuple[int, ...]

TODO: Add docstring

length `property` ¶

length: Any

TODO: Add docstring

length_flag `property` ¶

length_flag: Any

TODO: Add docstring

manufacturer `property` ¶

manufacturer: Any

TODO: Add docstring

mass `property` ¶

mass: Any

TODO: Add docstring

mass_flag `property` ¶

mass_flag: Any

TODO: Add docstring

motor `property` ¶

motor: Any

TODO: Add docstring

name `property` ¶

name: Any

TODO: Add docstring

object_type `property` ¶

object_type: Any

TODO: Add docstring

odate `property` ¶

odate: Tuple[int, ...]

TODO: Add docstring

op_orbit `property` ¶

op_orbit: Any

TODO: Add docstring

oqual `property` ¶

oqual: Any

TODO: Add docstring

owner `property` ¶

owner: Any

TODO: Add docstring

parent `property` ¶

parent: Any

TODO: Add docstring

perigee `property` ¶

perigee: Any

TODO: Add docstring

perigee_flag `property` ¶

perigee_flag: Any

TODO: Add docstring

piece `property` ¶

piece: Any

TODO: Add docstring

pl_name `property` ¶

pl_name: Any

TODO: Add docstring

primary `property` ¶

primary: Any

TODO: Add docstring

satcat `property` ¶

satcat: Any

TODO: Add docstring

sdate `property` ¶

sdate: Tuple[int, ...]

TODO: Add docstring

shape `property` ¶

shape: Any

TODO: Add docstring

span `property` ¶

span: Any

TODO: Add docstring

span_flag `property` ¶

span_flag: Any

TODO: Add docstring

state `property` ¶

state: ndarray

TODO: Add docstring

status `property` ¶

status: Any

TODO: Add docstring

tot_flag `property` ¶

tot_flag: Any

TODO: Add docstring

tot_mass `property` ¶

tot_mass: Any

TODO: Add docstring

GCATPsatcatRecord¶

GCATPsatcatRecord ¶

GCATPsatcatRecord()

A single record from the GCAT PSATCAT catalog.

Contains payload-specific metadata including mission details, UN registry information, and disposal orbit parameters.

Attributes:

Name	Type	Description
`jcat`	`str`	JCAT catalog identifier (primary key)
`piece`	`str \| None`	Piece designation
`name`	`str \| None`	Payload name
`ldate`	`str \| None`	Launch date
`tlast`	`str \| None`	Last contact date
`top`	`str \| None`	Operational start date
`tdate`	`str \| None`	End of operations date
`tf`	`str \| None`	Date quality flag
`program`	`str \| None`	Program/constellation name
`plane`	`str \| None`	Orbital plane identifier
`att`	`str \| None`	Attitude control type
`mvr`	`str \| None`	Maneuver capability
`class_`	`str \| None`	Mission class
`category`	`str \| None`	Mission category
`result`	`str \| None`	Mission result/outcome
`control`	`str \| None`	Control authority
`discipline`	`str \| None`	Mission discipline
`un_state`	`str \| None`	UN registry state
`un_reg`	`str \| None`	UN registry number
`un_period`	`float \| None`	UN registered orbital period in minutes
`un_perigee`	`float \| None`	UN registered perigee in km
`un_apogee`	`float \| None`	UN registered apogee in km
`un_inc`	`float \| None`	UN registered inclination in degrees
`disp_epoch`	`str \| None`	Disposal orbit epoch
`disp_peri`	`float \| None`	Disposal perigee in km
`disp_apo`	`float \| None`	Disposal apogee in km
`disp_inc`	`float \| None`	Disposal inclination in degrees
`comment`	`str \| None`	Comments

Example

import brahe.datasets as datasets

psatcat = datasets.gcat.get_psatcat()
record = psatcat.get_by_jcat("S049652")
if record:
    print(f"Program: {record.program}")
    print(f"Category: {record.category}")

Initialize instance.

att `property` ¶

att: Any

TODO: Add docstring

category `property` ¶

category: Any

TODO: Add docstring

class_ `property` ¶

class_: Any

TODO: Add docstring

comment `property` ¶

comment: Any

TODO: Add docstring

control `property` ¶

control: Any

TODO: Add docstring

discipline `property` ¶

discipline: Any

TODO: Add docstring

disp_apo `property` ¶

disp_apo: Any

TODO: Add docstring

disp_epoch `property` ¶

disp_epoch: Any

TODO: Add docstring

disp_inc `property` ¶

disp_inc: Any

TODO: Add docstring

disp_peri `property` ¶

disp_peri: Any

TODO: Add docstring

jcat `property` ¶

jcat: Any

TODO: Add docstring

ldate `property` ¶

ldate: Tuple[int, ...]

TODO: Add docstring

mvr `property` ¶

mvr: Any

TODO: Add docstring

name `property` ¶

name: Any

TODO: Add docstring

piece `property` ¶

piece: Any

TODO: Add docstring

plane `property` ¶

plane: Any

TODO: Add docstring

program `property` ¶

program: Any

TODO: Add docstring

result `property` ¶

result: Any

TODO: Add docstring

tdate `property` ¶

tdate: Tuple[int, ...]

TODO: Add docstring

tf `property` ¶

tf: Any

TODO: Add docstring

tlast `property` ¶

tlast: Any

TODO: Add docstring

top `property` ¶

top: Any

TODO: Add docstring

un_apogee `property` ¶

un_apogee: Any

TODO: Add docstring

un_inc `property` ¶

un_inc: Any

TODO: Add docstring

un_perigee `property` ¶

un_perigee: Any

TODO: Add docstring

un_period `property` ¶

un_period: Any

TODO: Add docstring

un_reg `property` ¶

un_reg: Any

TODO: Add docstring

un_state `property` ¶

un_state: ndarray

TODO: Add docstring

GCAT Functions¶

gcat_get_satcat¶

gcat_get_satcat builtin ¶

gcat_get_psatcat¶

gcat_get_psatcat builtin ¶

GCATSatcat¶

GCATSatcat ¶

filter_by_apogee_range ¶

filter_by_inc_range ¶

filter_by_owner ¶

filter_by_perigee_range ¶

filter_by_state ¶

filter_by_status ¶

filter_by_type ¶

get_by_jcat ¶

get_by_satcat ¶

records ¶

search_by_name ¶

to_dataframe ¶

GCATPsatcat¶

GCATPsatcat ¶

filter_active ¶

filter_by_category ¶

filter_by_class ¶

filter_by_result ¶

get_by_jcat ¶

records ¶

search_by_name ¶

to_dataframe ¶

GCATSatcatRecord¶

GCATSatcatRecord ¶

alt_names property ¶

apogee property ¶

apogee_flag property ¶

bus property ¶

ddate property ¶

dest property ¶

diameter property ¶

diameter_flag property ¶

dry_flag property ¶

dry_mass property ¶

inc property ¶

inc_flag property ¶

jcat property ¶

launch_tag property ¶

ldate property ¶

length property ¶

length_flag property ¶

manufacturer property ¶

mass property ¶

mass_flag property ¶

motor property ¶

name property ¶

object_type property ¶

odate property ¶

op_orbit property ¶

oqual property ¶

owner property ¶

parent property ¶

perigee property ¶

perigee_flag property ¶

piece property ¶

pl_name property ¶

primary property ¶

satcat property ¶

sdate property ¶

shape property ¶

span property ¶

span_flag property ¶

state property ¶

status property ¶

tot_flag property ¶

tot_mass property ¶

GCATPsatcatRecord¶

GCATPsatcatRecord ¶

att property ¶

category property ¶

class_ property ¶

comment property ¶

control property ¶

gcat_get_satcat `builtin` ¶

gcat_get_psatcat `builtin` ¶

alt_names `property` ¶

apogee `property` ¶

apogee_flag `property` ¶

bus `property` ¶

ddate `property` ¶

dest `property` ¶

diameter `property` ¶

diameter_flag `property` ¶

dry_flag `property` ¶

dry_mass `property` ¶

inc `property` ¶

inc_flag `property` ¶

jcat `property` ¶

launch_tag `property` ¶

ldate `property` ¶

length `property` ¶

length_flag `property` ¶

manufacturer `property` ¶

mass `property` ¶

mass_flag `property` ¶

motor `property` ¶

name `property` ¶

object_type `property` ¶

odate `property` ¶

op_orbit `property` ¶

oqual `property` ¶

owner `property` ¶

parent `property` ¶

perigee `property` ¶

perigee_flag `property` ¶

piece `property` ¶

pl_name `property` ¶

primary `property` ¶

satcat `property` ¶

sdate `property` ¶

shape `property` ¶

span `property` ¶

span_flag `property` ¶

state `property` ¶

status `property` ¶

tot_flag `property` ¶

tot_mass `property` ¶

att `property` ¶

category `property` ¶

class_ `property` ¶

comment `property` ¶

control `property` ¶

discipline `property` ¶

disp_apo `property` ¶

disp_epoch `property` ¶

disp_inc `property` ¶

disp_peri `property` ¶

jcat `property` ¶

ldate `property` ¶

mvr `property` ¶

name `property` ¶

piece `property` ¶

plane `property` ¶

program `property` ¶

result `property` ¶

tdate `property` ¶

tf `property` ¶

tlast `property` ¶

top `property` ¶

un_apogee `property` ¶

un_inc `property` ¶

un_perigee `property` ¶

un_period `property` ¶

un_reg `property` ¶

un_state `property` ¶