Scan

class sofia_redux.scan.scan.scan.Scan(channels, reduction=None)

Bases: ABC

Initialize a scan.

The scan is a high level class operated on by the reduction and reduction pipeline containing all of the information from an astronomical scan. It contains a set of integrations (time stream data) from the scan for all of the instrument channels as well as it’s own individual source model which may contribute to the overall reduction source.

Parameters:

channelssofia_scan.scan.channels.channels.Channels

The instrument channels for this scan.

reductionsofia_scan.scan.reduction.reduction.Reduction, optional

The reduction to which this scan belongs.

Notes

The integration configurations are based off the scan configuration, but are not linked and are distinct objects. The scan configuration is generally only accessed for scan specific operations or parameters. Therefore, do not expect that modifying the scan configuration will propagate down to the integrations, where the bulk of processing occurs.

Attributes Summary

apparent	Return the apparent equatorial coordinate of the observation.
astrometry	Return the scan astrometry information.
channel_flagspace	Return the flagspace for the scan channels.
configuration	Return the scan configuration.
equatorial	Return the scan equatorial position.
frame_flagspace	Return the flagspace for the scan frames.
horizontal	Get the scan horizontal coordinate position.
info	Return the information object for the scan.
instrument_name	Return the name of the instrument in the scan.
is_nonsidereal	Return whether the observation is non-sidereal.
is_tracking	Return whether the telescope is tracking.
lst	Get the scan Local Sidereal Time (LST).
mjd	Get the scan Modified Julian Date (MJD).
referenced_attributes	Return the names of attributes that are referenced during a copy.
serial	Return the scan serial number.
site	Return the location of the site of the observation.
size	Return the number of integrations in the scan.
source_name	Return the name of the observation source.

Methods Summary

calculate_apparent()	Calculate the apparent equatorial coordinates of the scan.
calculate_equatorial()	Calculate the equatorial coordinates of the scan.
calculate_horizontal()	Calculate the horizontal coordinates of the scan.
calculate_precessions(epoch)	Calculate the precessions to and from the apparent coordinates.
class_from_instrument_name(name)	Return the appropriate scan instance for an instrument name.
copy()	Return a copy of the scan.
decorrelate(modality_name)	Decorrelate a modality.
edit_pointing_header_info(header)	Edit pointing information in a header.
edit_scan_header(header)	Edit scan FITS header information.
frame_midpoint_value(frame_field)	Return the midpoint value of a given frame field.
get_equatorial_pointing(source)	Return the equatorial pointing.
get_first_frame()	Return the first frame of the first integration.
get_first_integration()	Return the first integration of the scan.
get_focus_string([asymmetry, elongation, weight])	Return a string representing focus.
get_frame_count([keep_flag, discard_flag, ...])	Return the number of frames in the scan.
get_id()	Return the scan simple ID.
get_integration_instance()	Return an integration instance of the correct type for the scan.
get_last_frame()	Return the last frame of the last integration.
get_last_integration()	Return the last integration of the scan.
get_nasmyth_offset(pointing)	Return the Nasmyth pointing offset w.r.t the reference position.
get_native_coordinates()	Return the native coordinates of the scan.
get_native_offset_of(equatorial_offset)	Get the native offset of equatorial offsets.
get_native_pointing(source)	Get the native pointing from a Gaussian source.
get_native_pointing_increment(source)	Return the native pointing increment of the map from the pointing.
get_observing_time()	Return the scan observing time in seconds.
get_pa()	Return the position angle derived from mid point values of frames.
get_point_size()	Return the point size of the scan.
get_pointing_correction(options)	Return the pointing corrections.
get_pointing_data()	Return pointing data information.
get_pointing_string()	Return a string representing the pointing information.
get_pointing_string_from_increment(increment)	Return a pointing string given an increment offset.
get_position_reference([system])	Return position reference in the defined coordinate frame.
get_short_date_string()	Return a short date representation of the MJD time.
get_source_asymmetry(region)	Return the source model asymmetry.
get_source_elongation_x(ellipse)	Return the elliptical source elongation in x.
get_source_generation()	Return the source generation.
get_source_model()	Return the source model which may be loaded from file.
get_summary_hdu([configuration])	Create a FITS HDU from the scan given a configuration.
get_table_entry(name)	Return a parameter value for the given name.
has_option(option)	Check whether an option is set in the configuration.
have_apparent()	Return whether horizontal coordinates exist for the scan.
have_equatorial()	Return whether equatorial coordinates exist for the scan.
have_horizontal()	Return whether horizontal coordinates exist for the scan.
have_site()	Return whether site coordinates exist for the scan.
have_valid_integrations()	Return whether valid integrations exist in the scan.
is_valid()	Return whether the scan contains any valid integrations.
merge_integrations()	Merge integrations as necessary.
perform(task)	Perform a reduction task on the scan.
pointing_at(correction)	Apply a pointing correction.
precess(epoch)	Precess coordinates to a new epoch and update integrations.
read(filename[, read_fully])	Read a filename to populate the scan.
report_focus()	Report the focus information for the scan.
report_pointing()	Return the pointing results for the scan.
segment_to(segment_time)	Split integrations such that each are approximately the same length.
set_channels(channels)	Set the instrument channels for the scan.
set_iteration(iteration[, rounds])	Set the configuration for a given iteration
set_source_model(source_model)	Set the source model based on whether pickling is enabled or not.
sort_integrations()	Sort scan integrations based on MJD.
split()	Split this scan into multiple scans.
time_order_scans(scans)	Return a list or scans in time order (by MJD).
update_gains(modality_name)	Update all gains in the scan for a given modality.
validate()	Validate the scan after a read.
validate_integrations()	Remove any invalid integrations from the scan.
write_products()	Write the scan information to file.

Attributes Documentation

apparent

Return the apparent equatorial coordinate of the observation.

Returns:

apparent_coordinateEquatorialCoordinate

astrometry

Return the scan astrometry information.

Returns:

infoAstrometryInfo

channel_flagspace

Return the flagspace for the scan channels.

Returns:

flagspaceChannelFlags

configuration

Return the scan configuration.

Returns:

Configuration

equatorial

Return the scan equatorial position.

Returns:

equatorial_coordinateEquatorialCoordinates

frame_flagspace

Return the flagspace for the scan frames.

Returns:

flagspaceFrameFlags

horizontal

Get the scan horizontal coordinate position.

Returns:

horizontal_coordinateHorizontalCoordinate

info

Return the information object for the scan.

The information object contains the reduction configuration and various parameters pertaining the this scan.

Returns:

Info

instrument_name

Return the name of the instrument in the scan.

Returns:

instrumentstr

is_nonsidereal

Return whether the observation is non-sidereal.

Returns:

non_siderealbool

is_tracking

Return whether the telescope is tracking.

Returns:

trackingbool

lst

Get the scan Local Sidereal Time (LST).

Returns:

lstastropy.units.Quantity

The LST as an hour angle.

mjd

Get the scan Modified Julian Date (MJD).

Returns:

mjdfloat

referenced_attributes

Return the names of attributes that are referenced during a copy.

Returns:

attribute_namesset (str)

serial

Return the scan serial number.

Returns:

serial_numberint

site

Return the location of the site of the observation.

Returns:

site_locationGeodeticCoordinates

size

Return the number of integrations in the scan.

Returns:

n_integrationsint

source_name

Return the name of the observation source.

Returns:

namestr

Methods Documentation

calculate_apparent()

Calculate the apparent equatorial coordinates of the scan.

Returns:

None

calculate_equatorial()

Calculate the equatorial coordinates of the scan.

Returns:

None

calculate_horizontal()

Calculate the horizontal coordinates of the scan.

Returns:

None

calculate_precessions(epoch)

Calculate the precessions to and from the apparent coordinates.

epoch : int or float or str or Epoch

Returns:

None

classmethod class_from_instrument_name(name)

Return the appropriate scan instance for an instrument name.

Parameters:

namestr

The instrument name.

Returns:

Scan

A scan instance.

copy()

Return a copy of the scan. Certain attributes will be referenced only.

Returns:

scanScan

decorrelate(modality_name)

Decorrelate a modality.

Parameters:

modality_namestr

Returns:

None

edit_pointing_header_info(header)

Edit pointing information in a header.

Parameters:

headerastropy.io.fits.header.Header

The FITS header to edit.

Returns:

None

edit_scan_header(header)

Edit scan FITS header information.

Parameters:

headerastropy.io.fits.header.Header

The header to edit.

Returns:

None

frame_midpoint_value(frame_field)

Return the midpoint value of a given frame field.

The midpoint is defined as the mean of the first valid frame value from the first integration, and the last frame of the last integration.

Parameters:

frame_fieldstr

The name of the frame field.

Returns:

midpoint

get_equatorial_pointing(source)

Return the equatorial pointing.

Parameters:

sourceGaussianSource

Returns:

coordinatesCoordinate2D

get_first_frame()

Return the first frame of the first integration.

Returns:

Frames

get_first_integration()

Return the first integration of the scan.

Returns:

integrationIntegration or None

Will be None if no integrations exist.

get_focus_string(asymmetry=None, elongation=None, weight=None)

Return a string representing focus.

Parameters:

asymmetryAsymmetry2D, optional

The source asymmetry. If not supplied, will be determined from the scan pointing.

elongationfloat, optional

The elongation of the source in x. If not supplied, will be determined from the pointing elongation.

weightfloat, optional

The weight of the elongation. If not supplied will be determined from the pointing elongation.

Returns:

str

get_frame_count(keep_flag=None, discard_flag=None, match_flag=None)

Return the number of frames in the scan.

Optionally provide flags to indicate which

Parameters:

keep_flagint or FrameFlagTypes

discard_flagint or FrameFlagTypes

match_flagint or FrameFlagTypes

Returns:

n_framesint

The number of frames in the scan.

get_id()

Return the scan simple ID.

Returns:

str

get_integration_instance()

Return an integration instance of the correct type for the scan.

Returns:

integrationIntegration

get_last_frame()

Return the last frame of the last integration.

Returns:

Frames

get_last_integration()

Return the last integration of the scan.

Returns:

integrationIntegration or None

Will be None if no integrations exist.

get_nasmyth_offset(pointing)

Return the Nasmyth pointing offset w.r.t the reference position.

Parameters:

pointingOffset2D

Returns:

Coordinate2D

get_native_coordinates()

Return the native coordinates of the scan.

Returns:

SphericalCoordinates

get_native_offset_of(equatorial_offset)

Get the native offset of equatorial offsets.

Parameters:

equatorial_offsetOffset2D

The equatorial (x, y) offsets w.r.t. a reference position.

Returns:

Offset2D

get_native_pointing(source)

Get the native pointing from a Gaussian source.

Parameters:

sourceGaussianSource

Returns:

Offset2D

get_native_pointing_increment(source)

Return the native pointing increment of the map from the pointing.

Parameters:

sourceGaussianSource

Returns:

Offset2D

get_observing_time()

Return the scan observing time in seconds.

Returns:

observing_timeastropy.units.Quantity

The observing time in seconds.

get_pa()

Return the position angle derived from mid point values of frames.

The position angle is the mean of the position angle from the first frame of the first integration, and the last frame of the last integration.

Returns:

angleastropy.units.Quantity

The position angle in degrees.

get_point_size()

Return the point size of the scan.

The point size will be the maximum of either the scan or source model (if available).

Returns:

astropy.units.Quantity

The point size.

get_pointing_correction(options)

Return the pointing corrections.

Parameters:

optionsdict

The pointing options. Relevant keys are ‘value’ and ‘offset’.

Returns:

correctionCoordinate2D

Contains the (x, y) pointing offsets.

get_pointing_data()

Return pointing data information.

Returns:

datadict

get_pointing_string()

Return a string representing the pointing information.

Returns:

infostr

get_pointing_string_from_increment(increment)

Return a pointing string given an increment offset.

Parameters:

incrementOffset2D

Returns:

str

get_position_reference(system=None)

Return position reference in the defined coordinate frame.

By default, the equatorial coordinates are returned, but many other frame systems may be specified. All astropy coordinate frames may be used but may raise conversion errors depending on the type. If an error is encountered during conversion, or the frame system is unavailable, equatorial coordinates will be returned.

Parameters:

systemstr

Name of the coordinate frame. Available values are: {‘horizontal’, ‘native’, ‘focalplane’} and all Astropy frame type names. Note that focalplane is not currently implemented and will raise an error.

Returns:

coordinatesSphericalCoordinates

Coordinates of the specified type.

get_short_date_string()

Return a short date representation of the MJD time.

Returns:

datestr

The MJD date in YYYY-MM-DD format.

get_source_asymmetry(region)

Return the source model asymmetry.

Parameters:

regionCircularRegion

Returns:

Asymmetry2D

get_source_elongation_x(ellipse)

Return the elliptical source elongation in x.

Parameters:

ellipseEllipticalSource

Returns:

elongation_x, elongation_x_weightfloat, float

get_source_generation()

Return the source generation.

Returns:

source_generationint

get_source_model()

Return the source model which may be loaded from file.

Returns:

SourceModel or None

get_summary_hdu(configuration=None)

Create a FITS HDU from the scan given a configuration.

Parameters:

configurationConfiguration, optional

The configuration from which to create the HDU. If not supplied defaults to the scan configuration.

Returns:

astropy.io.fits.hdu.table.BinTableHDU

get_table_entry(name)

Return a parameter value for the given name.

Parameters:

namestr

The name of the parameter to retrieve.

Returns:

value

has_option(option)

Check whether an option is set in the configuration.

Parameters:

optionstr

The configuration option.

Returns:

bool

have_apparent()

Return whether horizontal coordinates exist for the scan.

Returns:

bool

have_equatorial()

Return whether equatorial coordinates exist for the scan.

Returns:

bool

have_horizontal()

Return whether horizontal coordinates exist for the scan.

Returns:

bool

have_site()

Return whether site coordinates exist for the scan.

Returns:

bool

have_valid_integrations()

Return whether valid integrations exist in the scan.

Returns:

bool

is_valid()

Return whether the scan contains any valid integrations.

Returns:

bool

merge_integrations()

Merge integrations as necessary.

Returns:

None

perform(task)

Perform a reduction task on the scan.

Parameters:

taskstr

The name of the task.

Returns:

None

pointing_at(correction)

Apply a pointing correction.

If a new pointing correction is provided, it will be added to the existing pointing correction.

Parameters:

correctionCoordinate2D

The pointing (x, y) offset.

Returns:

None

precess(epoch)

Precess coordinates to a new epoch and update integrations.

The scan and all integration frames will be precessed to a new epoch if necessary.

Parameters:

epochEpoch

The new epoch.

Returns:

None

abstract read(filename, read_fully=True)

Read a filename to populate the scan.

The read should validate the channels before instantiating integrations for reading.

Parameters:

filenamestr

The name of the file to read.

read_fullybool, optional

If True, perform a full read (default)

Returns:

None

report_focus()

Report the focus information for the scan.

Returns:

None

report_pointing()

Return the pointing results for the scan.

Returns:

None

segment_to(segment_time)

Split integrations such that each are approximately the same length.

Integrations are merged together, and then split such that each integration is of length segment_time. All previous dependents, signals, and filter objects will unset.

Parameters:

segment_timeastropy.units.Quantity

The maximum time for an integration.

Returns:

None

set_channels(channels)

Set the instrument channels for the scan.

Parameters:

channelsChannels

Returns:

None

set_iteration(iteration, rounds=None)

Set the configuration for a given iteration

Parameters:

iterationfloat or int or str

The iteration to set. A positive integer defines the exact iteration number. A negative integer defines the iteration relative to the last (e.g. -1 is the last iteration). A float represents a fraction (0->1) of the number of rounds, and a string may be parsed in many ways such as last, first, a float, integer, or percentage (if suffixed with a %).

roundsint, optional

The maximum number of iterations.

Returns:

None

set_source_model(source_model)

Set the source model based on whether pickling is enabled or not.

Parameters:

source_modelSourceModel

Returns:

None

sort_integrations()

Sort scan integrations based on MJD.

The integration IDs are also updated.

Returns:

None

split()

Split this scan into multiple scans.

Returns a list of scans each containing a single integration.

Returns:

list (Scan)

static time_order_scans(scans)

Return a list or scans in time order (by MJD).

Parameters:

scanslist (Scan)

A list of scans.

Returns:

list (Scan)

update_gains(modality_name)

Update all gains in the scan for a given modality.

Parameters:

modality_namestr

The name of the modality

Returns:

None

validate()

Validate the scan after a read.

Returns:

None

validate_integrations()

Remove any invalid integrations from the scan.

Returns:

None

write_products()

Write the scan information to file.

Returns:

None