Observations planning (ctapointing.observation)

Functionality to plan pointing observations and store their properties.

• PointingObservation: container to store information about individual pointing observations, such as target position, observation time and exposure duration.

• StarSelector: tool to select stars for pointing observations, such that their distribution is isotropic within specified altitude limits.

• ObservationPlan: functionality to schedule/plan pointing observations, select proper targets using e.g. the StarSelection, and read/write the observation plan from/to HDF5 file.

API

ctapointing.observation Package

class ctapointing.observation.ObservationPlan(**kwargs: Any)

Observation planning for pointing observations.

__init__(config=None, parent=None, **kwargs)

Class to create and store observation plans.

add_target(target_name, target_pos, start_time, duration)

Add a new target at the end of the observation plan.

Parameters:

• name (str) – target name

• target_pos (astropy.SkyCoord) – target position (ICRS or AltAz frame)

• start_time (astropy.Time) – start time of observation

• duration (astropy.Quantity) – duration of the observation

classmethod from_config(**kwargs)

Read an observation plan configuration from either configuration file or database. Either the path of a configuration file (‘input_url’) or a database collection (‘collection’) must be provided.

Parameters:

• input_url (str or pathlib.Path) – path of the configuration file.

• name (str) – name of the camera (as in PointingCamera.name). When loading the configuration from file, can be set to check that the configuration with the correct name is loaded. When loading from database, is used to identify the correct database record.

• uuid (str) – UUID of the camera (as in PointingCamera.uuid). When loading the configuration from file, can be set to check that the configuration with the correct UUID is loaded. When loading from database, is used to identify the correct database record.

• collection (str) – name of the database collection from which configuration is read

• database (str) – name of the database in which the collection is stored

Returns:

plan

Return type:

ObservationPlan object

get_schedule()

Return observation plan as a QTable.

Return type:

astropy.table.QTable

input_url

observation plan file

name

name of ObservationPlan

read(filename: str, file_format: str = 'hdf5')

Load an observation plan from file (to which it was previously written using ObservationPlan.write()).

Parameters:

• filename (str or Path) – filename from which to read the observation plan.

• file_format (str) – file format according to astropy specifications (default: “auto”)

schedule_coordinates_altaz(target_position_altaz, duration)

Schedule according to a set of AltAz coordinates

schedule_isotropic(num_targets: int, start_time: ~astropy.time.core.Time, location: ~ctapointing.config.traits.AstroEarthLocation, duration: ~astropy.units.quantity.Quantity = <Quantity 10. s>, time_between_targets: ~astropy.units.quantity.Quantity = <Quantity 120. s>, altitude_limits: (<class 'astropy.units.quantity.Quantity'>, <class 'astropy.units.quantity.Quantity'>) = (<Quantity 10. deg>, <Quantity 70. deg>), magnitude_limits: (<class 'float'>, <class 'float'>) = (-3.0, 4.0))

Schedule an isotropic observation plan, i.e. aim at selecting targets such that isotropy on the (half-)sky is reached.

Parameters:

• num_targets (int) – number of targets to schedule

• start_time (astropy.time.Time or str) – start time of the observations

• location (AstroEarthLocation) – earth location of observer

• duration (astropy.units.Quantity) – duration of each exposure

• time_between_targets (astropy.units.Quantity) – time between the targets

• altitude_limits (tuple of astropy.units.Quantity) – altitude lower and upper limit

• magnitude_limits (tuple of float) – magnitude range for star selection

uuid

UUID of ObservationPlan

write(filename: str | None = None, file_format: str = 'hdf5', overwrite: bool = False)

Write observation schedule to file.

The observation plan is converted to an astropy.tables.QTable. The file format can be chosen from those available within astropy.tables

Parameters:

• filename (str or Path) – filename to which observation plan is written

• file_format (str or Path) – file format, according to astropy specifications

• overwrite (bool) – force overwrite of already existing file if True

Returns:

filename – filename of output file

Return type:

str

class ctapointing.observation.PointingObservation(prefix=None, **fields)

Class storing information about a pointing observation

uuid

UUID

Type:

Field(default=None, type=str)

target_name

target name

Type:

Field(default=, type=str)

start_time

start time of exposure

Type:

Field(default=None, type=Time)

duration

exposure duration

Type:

Field(default=nan s, unit=s)

target_pos_ra

target position (right ascension)

Type:

Field(default=nan deg, unit=deg)

target_pos_dec

target position (declination)

Type:

Field(default=nan deg, unit=deg)

location_x

geocentric location (x)

Type:

Field(default=nan m, unit=m)

location_y

geocentric location (y)

Type:

Field(default=nan m, unit=m)

location_z

geocentric location (z)

Type:

Field(default=nan m, unit=m)

ambient_pressure

atmospheric pressure

Type:

Field(default=nan mbar, unit=mbar)

ambient_temperature

atmospheric temperature

Type:

Field(default=nan deg_C, unit=deg_C)

meta

dict of attached metadata

Type:

dict

prefix

Prefix attached to column names when saved to a table or file

Type:

str

__init__(prefix=None, **fields)

property altazframe

Return AltAz frame, using currently available meta information.

classmethod from_name(name, **kwargs)

Load PointingObservation from HDF5 file or database. See `ctapointing.io.from_name()`for details.

property mean_observation_time

Return time of mean time of observation.

Returns:

mean observation time

Return type:

astropy.Time

property target_pos_altaz

Return AltAz telescope pointing, i.e. the telescope orientation at the time of mean exposure.

class ctapointing.observation.StarSelectorIsotropic(location, altitude_limits=<Quantity [10., 70.] deg>, magnitude_limits=(-3, 4))

A class for selecting stellar targets for pointing calibration observations

Targets are selected based on maximum isotropic coverage of the sky based on - previously visited targets (history) - planned start time of the observation within the provided azimuth and altitude limits (if requested).

Parameters:

location: astropy.coordinates.EarthLocation

earth location of the telescope

altitude limits: None or tuple of astropy.Angle

tuple of two angles representing the altitude range in which targets get selected

magnitude limits: None or tuple of float

tuple representing minimum and maximum magnitude of catalog stars used as targets

TODO: Make target history work. This requires generating a random selection of targets outside the altitude range, as otherwise the resulting distribution will be biased.

__init__(location, altitude_limits=<Quantity [10., 70.] deg>, magnitude_limits=(-3, 4))

select_target(start_time, duration)

Select the next best target, based on observation history. Target is selected such that the resulting AltAz distribution is as isotropic as possible (within the limits of the star distribution)

Parameters:

• start_time (astropy.Time) – Time at which the observation of the target will start

• duration (astropy.units.Quantity) – duration of the observation

Return type:

PointingObservation or list of PointingObservation

ctapointing.observation.create_animation_altaz(observations)

Creates a matplotlib.animation object that shows the selected targets one after the other.

Parameters:

observations (iterable of type PointingObservations) – observation plan or list of PointingObservations

Return type:

reference to matplotlib.animation

ctapointing.observation.plot_observations_altaz(observations)

Plot the target distribution of a list of PointingObservations

Parameters:

observation (iterable of type PointingObservation) – observation pland or list of PointingObservations

Return type:

axes object

ctapointing.observation.plot_observations_projection(observations)

Plot altitude and azimuth projections of a list of PointingObservations

Parameters:

observation_list (iterable of type PointingObservation) – ObservationPlan or list of Pointing Observations

Return type:

array of axes objects

Functions

plot_observations_altaz(observations)	Plot the target distribution of a list of PointingObservations
plot_observations_projection(observations)	Plot altitude and azimuth projections of a list of PointingObservations
create_animation_altaz(observations)	Creates a matplotlib.animation object that shows the selected targets one after the other.

Classes

ObservationPlan(**kwargs)	Observation planning for pointing observations.
PointingObservation([prefix])	Class storing information about a pointing observation
StarSelectorIsotropic(location[, ...])	A class for selecting stellar targets for pointing calibration observations

Class Inheritance Diagram