ScienceImage

class ScienceImage[source]

Class representing a science FITS image.

Inherits from BaseImage and includes extended support for tracking processing status, managing file paths, saving metadata, and handling associated files such as background maps, error maps, masks, and source catalogs.

__init__(path, telinfo=None, status=None, load=True)[source]

Initialize a ScienceImage instance.

Parameters:

  • path (str or Path) – Path to the science FITS image.

  • telinfo (dict, optional) – Telescope metadata dictionary.

  • status (Status, optional) – Initial status object. If not provided, status is loaded from file or initialized.

  • load (bool, optional) – Whether to load status and header upon initialization.

Methods

show(self, coord_type='coord', cmap='gray', scale='zscale', downsample=4, figsize=(8, 6), title=None, save_path=False, close_fig=False)

Visualize the FITS image with optional WCS overlay and downsampling.

run_ds9(self)

Open the image with SAOImage DS9.

Parameters:

None

Return type:

None

show_position(self, x, y, coord_type='coord', radius_arcsec=None, a_arcsec=None, b_arcsec=None, theta_deg=None, aperture_linewidth=1.0, aperture_color='red', aperture_label='detected', downsample=4, zoom_radius_pixel=100, cmap='gray', scale='zscale', figsize=(6, 6), title=None, title_fontsize=18, ax=None, save_path=None)

Display a zoomed-in view around a given (x, y) or (RA, Dec) position.

Parameters:

  • x (float) – X-coordinate (pixel or RA)

  • y (float) – Y-coordinate (pixel or Dec)

  • radius_arcsec (float, optional) – Radius of the circle in arcseconds. Default is None.

  • a_arcsec (float, optional) – Semi-major axis of the ellipse in arcseconds. Default is None.

  • b_arcsec (float, optional) – Semi-minor axis of the ellipse in arcseconds. Default is None.

  • theta_deg (float, optional) – Position angle of the ellipse in degrees. Default is None.

  • coord_type (str, optional) – β€˜pixel’ or β€˜coord’. Default is β€˜pixel’.

  • downsample (int, optional) – Step size for downsampling via slicing. Default is 4.

  • zoom_radius_pixel (int, optional) – Radius of the zoom-in region in pixels. Default is 100.

  • cmap (str, optional) – Matplotlib colormap. Default is β€˜gray’.

  • scale (str, optional) – Scaling method. Default is β€˜zscale’.

  • figsize (tuple, optional) – Matplotlib figure size. Default is (6, 6).

  • ax (matplotlib Axes object, optional) – If provided, the image will be plotted on this axis. Default is None.

  • save_path (str, optional) – Path to save the figure. Default is None.

  • title (bool, optional) – Whether to display the title. Default is True.

calculate_invalidmask(self, threshold_invalid_connection=100000, save=False, verbose=True, visualize=True, save_fig=False)

Calculate the invalid mask for this ScienceImage. The invalid mask is a mask of pixels that are invalid (zero or nan value). If save is True, the invalid mask is saved. Then, you can load the invalid mask with self.invalidmask.

Parameters:

  • threshold_invalid_connection (int) – The threshold for invalid connection.

  • save (bool) – If True, save the invalid mask.

  • verbose (bool) – If True, print verbose output.

  • visualize (bool) – If True, visualize the invalid mask.

  • save_fig (bool) – If True, save the figure of the invalid mask.

Returns:

target_ivpmask – The invalid mask.

Return type:

Mask

calculate_sourcemask(self, target_srcmask=None, sigma=5.0, mask_radius_factor=3, saturation_level=50000, save=False, verbose=True, visualize=True, save_fig=False)

Calculate the source mask for this ScienceImage. The source mask is a mask of pixels that are sources. Detection is made with global background and background RMS map. If save is True, the source mask is saved. Then, you can load the source mask with self.sourcemask.

Parameters:

  • target_srcmask (Mask) – The source mask.

  • sigma (float) – The sigma for the source detection.

  • mask_radius_factor (float) – The radius factor for the source detection.

  • saturation_level (float) – The saturation level for the source detection.

  • save (bool) – If True, save the source mask.

  • verbose (bool) – If True, print verbose output.

  • visualize (bool) – If True, visualize the source mask.

  • save_fig (bool) – If True, save the figure of the source mask.

Returns:

target_sourcemask – The source mask.

Return type:

Mask

calculate_bkg(self, target_srcmask=None, target_ivpmask=None, is_2D_bkg=True, box_size=64, filter_size=3, correct_global_offset=True, save=False, verbose=True, visualize=True, save_fig=False)

Calculate the background map for this ScienceImage. The background map is a map of the background level of the image. If save is True, the background map is saved. Then, you can load the background map with self.bkgmap.

Parameters:

  • target_srcmask (Mask) – The source mask.

  • target_ivpmask (Mask) – The invalid mask.

  • is_2D_bkg (bool) – If True, use 2D background estimation.

  • box_size (int) – The box size for the background estimation.

  • filter_size (int) – The filter size for the background estimation.

  • correct_global_offset (bool) – If True, correct the global offset of the background map.

  • save (bool) – If True, save the background map.

  • verbose (bool) – If True, print verbose output.

  • visualize (bool) – If True, visualize the background map.

  • save_fig (bool) – If True, save the figure of the background map.

Returns:

target_bkg – The calculated background map.

Return type:

Background

calculate_bkgrms(self, target_srcmask=None, target_ivpmask=None, box_size=64, filter_size=3, save=False, verbose=True, visualize=True, save_fig=False)

Calculate the background RMS map for this ScienceImage. The background RMS map is a map of the background RMS level of the image. If save is True, the background RMS map is saved. Then, you can load the background RMS map with self.bkgrms.

Parameters:

  • target_srcmask (Mask) – The source mask.

  • target_ivpmask (Mask) – The invalid mask.

  • box_size (int) – The box size for the background RMS estimation.

  • filter_size (int) – The filter size for the background RMS estimation.

  • save (bool) – If True, save the background RMS map.

  • verbose (bool) – If True, print verbose output.

  • visualize (bool) – If True, visualize the background RMS map.

  • save_fig (bool) – If True, save the figure of the background RMS map.

Returns:

target_bkgrms – The background RMS map.

Return type:

Errormap

calculate_errormap(self, target_srcmask=None, target_ivpmask=None, box_size=64, filter_size=3, save=False, verbose=True, visualize=True, save_fig=False)

Calculate the source RMS map for this ScienceImage. The source RMS map is a map of the source RMS level of the image. If save is True, the source RMS map is saved. Then, you can load the source RMS map with self.sourcerms.

Parameters:

  • target_srcmask (Mask) – The source mask.

  • target_ivpmask (Mask) – The invalid mask.

  • box_size (int) – The box size for the source RMS estimation.

  • filter_size (int) – The filter size for the source RMS estimation.

  • save (bool) – If True, save the source RMS map.

  • verbose (bool) – If True, print verbose output.

  • visualize (bool) – If True, visualize the source RMS map.

  • save_fig (bool) – If True, save the figure of the source RMS map.

Returns:

target_sourcerms – The source RMS map.

Return type:

Errormap

calculate_bkgrms_from_propagation(self, target_bkg=None, mbias=None, mdark=None, mflat=None, mflaterr=None, save=False, verbose=True, visualize=True, save_fig=False)

Calculate the background RMS map for this ScienceImage from the background map, bias frame, dark frame, and flat frame. The background RMS map is a map of the background RMS level of the image. If save is True, the background RMS map is saved. Then, you can load the background RMS map with self.bkgrms.

Parameters:

  • target_srcmask (Mask) – The source mask.

  • target_ivpmask (Mask) – The invalid mask.

  • mbias (CalibrationImage) – The bias frame.

  • mdark (CalibrationImage) – The dark frame.

  • mflat (CalibrationImage) – The flat frame.

  • mflaterr (Errormap) – The flat error map.

  • save (bool) – If True, save the background RMS map.

  • verbose (bool) – If True, print verbose output.

  • visualize (bool) – If True, visualize the background RMS map.

  • save_fig (bool) – If True, save the figure of the background RMS map.

Returns:

target_bkgrms – The background RMS map.

Return type:

Errormap

calculate_errormap_from_propagation(self, mbias=None, mdark=None, mflat=None, mflaterr=None, save=False, verbose=True, visualize=True, save_fig=False)

Calculate the source RMS map for this ScienceImage from the background map, bias frame, dark frame, and flat frame. The source RMS map is a map of the source RMS level of the image. If save is True, the source RMS map is saved. Then, you can load the source RMS map with self.sourcerms.

Parameters:

  • target_srcmask (Mask) – The source mask.

  • target_ivpmask (Mask) – The invalid mask.

  • mbias (CalibrationImage) – The bias frame.

  • mdark (CalibrationImage) – The dark frame.

  • mflat (CalibrationImage) – The flat frame.

  • mflaterr (Errormap) – The flat error map.

  • save (bool) – If True, save the source RMS map.

  • verbose (bool) – If True, print verbose output.

  • visualize (bool) – If True, visualize the source RMS map.

  • save_fig (bool) – If True, save the figure of the source RMS map.

Returns:

target_sourcerms – The source RMS map.

Return type:

Errormap

get_masterframe(self, imagetyp, max_days=10)

Get master frame from the image.

This method will search for the master frame in the master frame directory.

Parameters:

  • imagetyp (str) – The type of image to get the master frame from. (BIAS, DARK, FLAT)

  • max_days (float, optional) – The maximum number of days to search for the master frame.

Returns:

  • master_img (CalibrationImage) – The master frame image.

  • master_frames_tbl (Table) – Metadata of the master frame(s) found.

get_referenceframe(self, telname=None, min_obsdate=None, max_obsdate=None, sort_key=['fraction', 'depth'], overlap_threshold=0.5, return_groups=True, group_overlap_threshold=0.8, verbose=True)

Get the reference frame from the target image.

Parameters:

  • telname (str, optional) – The telescope name.

  • min_obsdate (Union[str, float, Time], optional) – The minimum observation date.

  • max_obsdate (Union[str, float, Time], optional) – The maximum observation date.

  • sort_key (Union[str, List[str]], optional) – The sort key.

  • overlap_threshold (float, optional) – The overlap threshold.

  • return_groups (bool, optional) – Whether to return the groups.

  • group_overlap_threshold (float, optional) – The group overlap threshold.

Returns:

  • reference_img (ReferenceImage) – The reference image.

  • reference_frames (Table) – The metadata of the reference frames matched the criteria.

query_referenceframe(self, save_path=None, verbose=True, n_processes=4)

Query the reference frame from the target image.

Parameters:

  • save_path (str, optional) – The save path of the reference frame.

  • verbose (bool, optional) – The verbose flag.

  • n_processes (int, optional) – The number of processes.

Returns:

reference_img – The reference image.

Return type:

ReferenceImage

load(self)

Load both image data and header from disk.

Parameters:

None

Return type:

None

write(self, verbose=True)

Write ScienceImage data to savepath.

Parameters:

None

Return type:

None

remove(self, remove_main=True, remove_connected_files=True, skip_patterns=[], verbose=True)
Return type:

dict

copy(self)

Return an in-memory deep copy of this ScienceImage instance,

Parameters:

None

Returns:

copied_image – A deep copy of the ScienceImage instance.

Return type:

ScienceImage

rename(self, new_name, verbose=True)

Rename the image file and update the internal path.

Parameters:

new_name (str) – New name of the image file.

Return type:

None

clear(self, clear_data=True, clear_header=False, verbose=True)

Clear the image data and/or header from memory.

Parameters:

  • clear_data (bool, optional) – If True, clear the image data. Default is True.

  • clear_header (bool, optional) – If True, clear the image header. Default is False.

Additional Methods

update_header(self, **kwargs)

Update FITS header values using known key variants.

Parameters:

kwargs (dict) – Keyword arguments to update the FITS header.

Return type:

None

to_referenceimage(self)

Convert this ScienceImage to a ReferenceImage

Parameters:

None

Return type:

ReferenceImage

load_status(self)

Load processing status from a JSON file

Parameters:

None

Returns:

status – Status object loaded from the JSON file.

Return type:

Status

save_status(self)

Save processing status to a JSON file

Parameters:

None

Return type:

None

update_status(self, process_name)

Mark a process as completed and update time

Parameters:

process_name (str) – Name of the process to update.

save_info(self)

Save processing info to a JSON file

Parameters:

None

Return type:

None

Properties

Key Properties

Property

Description

altitude

Altitude of the telescope.

available_telescope_keys

Return a list of available telescope keys.

azimuth

Azimuth of the telescope.

biaspath

Path to the bias image.

binning

Binning of the image.

bkgmap

Background map of the image. If not exists, return None.

bkgrms

Background RMS map of the image. If not exists, return None.

bkgtype

Type of the background image.

catalog

Source catalog of the image. If not exists, return None.

ccd

Name of the CCD.

ccdtemp

CCD temperature.

center

Center pixel (0-based) and its world coordinates (RA, Dec).

connected_files

Return all associated files that would be deleted in remove() if remove_connected_files=True,

darkpath

Path to the dark image.

data

Image data array.

dec

Declination of the target.

depth

Depth of the image.

egain

Electron gain of the image.

emaptype

Type of the emap image.

exptime

Exposure time of the image.

filter

Filter name.

flatpath

Path to the flat image.

fovx

Field of view along the first axis.

fovy

Field of view along the second axis.

gain

Gain of the image.

header

FITS header object.

imgtype

Type of the image. Among BIAS, DARK, FLAT, LIGHT, OBJECT, UNKNOWN.

info

Information instance of the image. Info is defined in Info class.

invalidmask

Invalid mask of the image. If not exists, return None.

is_data_loaded

Whether the image data is loaded.

is_exists

Whether the image file exists.

is_header_loaded

Whether the image header is loaded.

is_saved

Check if the image has been saved

jd

Julian date of the observation.

masktype

Type of the mask image.

mjd

Modified Julian date of the observation.

naxis1

Number of pixels along the first axis.

naxis2

Number of pixels along the second axis.

ncombine

Number of combined images.

objname

Object name.

obsdate

Observation date in UTC.

observatory

Name of the observatory.

obsmode

Observation mode.

pixelscale

Pixel scale of the image.

ra

Right ascension of the target.

refcatalog

Reference catalog of the image. If not exists, return None.

savedir

Return the directory where this image and associated files will be saved.

savepath

Dynamically builds save paths based on current header info

seeing

Seeing of the image.

sourcemask

Source mask of the image. If not exists, return None.

specmode

Spectroscopic mode.

telname

Name of the telescope.

wcs

WCS information of the image.

zp

Zero point of the image.

zperr

Zero point error of the image.