astra.utils

astra.utils#

Utility functions for astronomical observations and data processing.

This module provides essential utility functions for the Astra observatory system, including time conversions, coordinate transformations, database queries, and telescope error handling. Functions support FITS header processing, flat field observations, and SPECULOOS telescope operations.

Key capabilities: - Julian Day and astronomical time system conversions - FITS header time calculations with light travel corrections - Solar position analysis for flat field timing - Database queries for astronomical catalogs - SPECULOOS telescope error checking and acknowledgement

Functions

ack_astelos_error(telescope, valid, ...[, close])

Acknowledge acceptable SPECULOOS telescope errors.

check_astelos_error(telescope[, close])

Check SPECULOOS telescope status for known acceptable errors.

clean_image(data)

Clean an image by subtracting the background.

getLightTravelTimes(target, time_to_correct)

Calculate light travel times to heliocentric and barycentric frames.

interpolate_dfs(index, *data)

Interpolate multiple pandas DataFrames onto a common index.

is_sun_rising(obs_location)

Determine solar motion and flat field observation readiness.

time_conversion(jd, location, target)

Convert time to various astronomical reference frames.

to_jd(dt[, fmt])

Convert datetime object to Julian Day using standard algorithm.

Classes

CustomImageClass(data[, header])

Enhanced image processing class with background subtraction and cleaning.
class astra.utils.CustomImageClass(data, header=None)[source]#

Bases: Image

Enhanced image processing class with background subtraction and cleaning.

preconstruct_hook() → None[source]#

Apply image preprocessing before Donuts star detection.

Performs background subtraction, noise reduction, and systematic correction to improve star detection reliability.

astra.utils.interpolate_dfs(index: ndarray, *data: DataFrame) → DataFrame[source]#

Interpolate multiple pandas DataFrames onto a common index.

Merges and interpolates multiple DataFrames using a specified index array, commonly used for wavelength-dependent data processing in spectroscopy.

Parameters:

  • index (np.ndarray) – 1D array to interpolate data onto (e.g., wavelength grid).

  • *data (pd.DataFrame) – Variable number of DataFrames to interpolate.

Returns:

pd.DataFrame – Combined DataFrame with all data interpolated onto the common index.

astra.utils.__to_format(jd: float, fmt: str) → float[source]#

Convert Julian Day to specified time format.

Internal function for converting Julian Day values to different astronomical time formats like Modified Julian Day or Reduced Julian Day.

Parameters:

  • jd (float) – Julian Day value to convert.

  • fmt (str) – Target format (‘jd’, ‘mjd’, ‘rjd’).

Returns:

float – Converted time value in specified format.

Raises:

ValueError – If format string is not recognized.

astra.utils.to_jd(dt: datetime, fmt: str = 'jd') → float[source]#

Convert datetime object to Julian Day using standard algorithm.

Converts Python datetime to Julian Day format using the algorithm from Wikipedia. Supports conversion to various Julian Day formats.

Parameters:

  • dt (datetime) – Datetime object to convert.

  • fmt (str) – Output format (‘jd’, ‘mjd’, ‘rjd’). Defaults to ‘jd’.

Returns:

float – Julian Day value in specified format.

astra.utils.getLightTravelTimes(target: SkyCoord, time_to_correct: Time) → Tuple[Time, Time][source]#

Calculate light travel times to heliocentric and barycentric frames.

Computes corrections for light travel time from Earth to the solar system barycenter and heliocenter, essential for precise timing in astronomy.

Parameters:

  • target (SkyCoord) – Target celestial coordinates.

  • time_to_correct (Time) – Observation time requiring correction. Must be initialized with an EarthLocation.

Returns:

Tuple[Time, Time] – Light travel times as (barycentric, heliocentric).

astra.utils.time_conversion(jd: float, location: Any, target: SkyCoord) → Tuple[float, float, float, str][source]#

Convert time to various astronomical reference frames.

Transforms Julian Day to heliocentric and barycentric systems, calculates local sidereal time and hour angle for astronomical observations.

Parameters:

  • jd (float) – Julian Day to convert.

  • location (EarthLocation) – Observer’s geographic location.

  • target (SkyCoord) – Target celestial coordinates.

Returns:

Tuple[float, float, float, str] –

Converted times as

(hjd, bjd, lst_seconds, hour_angle_string).

astra.utils.is_sun_rising(obs_location: Any) → Tuple[bool, bool, AltAz][source]#

Determine solar motion and flat field observation readiness.

Analyzes sun position and movement to determine if conditions are suitable for flat field calibration observations, which require specific twilight conditions.

Parameters:

obs_location (EarthLocation) – Observer’s geographic location.

Returns:

Tuple[bool, bool, AltAz] –

Solar status as (rising, flat_ready, position):

  • rising: True if sun is rising, False if setting

  • flat_ready: True if optimal for flats (sun altitude -12° to -1°)

  • position: Current sun position in alt-az coordinates

astra.utils.clean_image(data: ndarray) → ndarray[source]#

Clean an image by subtracting the background.

Parameters:

data (np.ndarray) – The 2D image data.

Returns:

np.ndarray – The background-subtracted image.

astra.utils.check_astelos_error(telescope: Any, close: bool = False) → Tuple[bool, DataFrame, str][source]#

Check SPECULOOS telescope status for known acceptable errors.

Analyzes telescope status messages to identify errors and determines if they are in the list of known acceptable errors that can be safely acknowledged.

Parameters:

  • telescope (Any) – Telescope object with get() method for status commands.

  • close (bool) – Whether to include slit closure errors in acceptable list.

Returns:

Tuple[bool, pd.DataFrame, str] –

Error analysis as (valid, errors, messages):

  • valid: True if all errors are acceptable, False otherwise

  • errors: DataFrame with columns [‘error’, ‘detail’, ‘level’, ‘component’]

  • messages: Raw telescope status message string

astra.utils.ack_astelos_error(telescope: Any, valid: bool, all_errors: DataFrame, messages: str, close: bool = False) → Tuple[bool, str][source]#

Acknowledge acceptable SPECULOOS telescope errors.

Attempts to clear acceptable telescope errors by sending appropriate acknowledgement commands. Continues until all errors are cleared or unacceptable errors are encountered.

Parameters:

  • telescope (Any) – Telescope object with get() method for commands.

  • valid (bool) – Whether errors are acceptable (from check_astelos_error).

  • all_errors (pd.DataFrame) – Error information with ‘level’ column.

  • messages (str) – Original telescope status messages.

  • close (bool) – Whether to include slit closure errors as acceptable.

Returns:

Tuple[bool, str] –

Acknowledgement result as (success, final_messages):

  • success: True if all errors cleared, False if unacceptable errors remain

  • final_messages: Updated telescope status messages

Raises:

TimeoutError – If error clearing takes longer than 2 minutes.

Contents