aop.aop#

Author:

Amélie Solveigh Hohe

Contact:

nina.tolfersheimer@posteo.de

This module contains the main classes and functions of the aop package.

Module Contents#

Classes#

Session

A class representing an astronomical observing session.

Functions#

current_jd(→ numpy.float64)

Returns the Julian Date for the current UTC or a custom datetime.

generate_observation_id(→ str)

This function generates a unique observation ID.

create_entry_id(→ str)

Creates a unique identifier for each and every entry in an .aop protocol.

parse_session(→ Session)

This function parses a session from memory to a new Session object.
aop.aop.current_jd(time: str = 'current') → numpy.float64#

Returns the Julian Date for the current UTC or a custom datetime.

It makes use of astropy’s Time class to represent the datetime given as a Julian Date.

Parameters:

time (str, optional) – An ISO 8601 conform string of the UTC datetime you want to be converted to a Julian Date. If time is “current”, the current UTC datetime will be used, defaults to “current”.

Raises:

  • TypeError – If the time argument is not of type str.

  • InvalidTimeStringError – If the time argument is of type str but not interpretable as representing a time to astropy.time.Time.

Returns:

The Julian Date corresponding to the datetime provided.

Return type:

numpy.float64

aop.aop.generate_observation_id(digits: int = 10) → str#

This function generates a unique observation ID.

The ID is generated as such: YYYY-mm-dd-HH-MM-SS-uuuuuuuuuu, where:

  • YYYY: current UTC year

  • mm: current UTC month

  • dd: current UTC day

  • HH: current UTC hour

  • MM: current UTC minute

  • SS: current UTC second

  • uuuuuuuuuu: a digits-long unique identifier (10 digits per default)

Parameters:

digits (int, optional) – The number of digits to be used for the unique identifier part of the observation ID, defaults to 10.

Returns:

The generated observation ID.

Return type:

str

aop.aop.create_entry_id(time: str = 'current', digits: int = 30) → str#

Creates a unique identifier for each and every entry in an .aop protocol. This identifier is unique even across observations.

Parameters:

  • time (str, optional) – If equal to “current”, the current UTC datetime is used for entry ID creation. You can also pass an ISO 8601 conform string to time, if the time of the entry is not the current time this method is called, defaults to “current”.

  • digits (int, optional) – The number of characters to use for the unique part of the entry ID, defaults to 30.

Raises:

  • TypeError – If time is not a string.

  • InvalidTimeStringError – If a string different from “current” is provided as time argument, but it is not ISO 8601 conform and therefore does not constitute a valid time string.

Returns:

The entry ID generated. It follows the syntax YYYYMMDDhhmmssffffff-u, where:

  • YYYY is the specified UTC year,

  • MM is the specified UTC month,

  • DD is the specified UTC day,

  • hh is the specified UTC hour,

  • mm is the specified UTC month,

  • ss is the specified UTC second,

  • ffffff is the specified fraction of a UTC second and

  • u represents the specified amount of unique identifier characters.

Return type:

str

class aop.aop.Session(filepath: str, **kwargs)#

A class representing an astronomical observing session.

The Session class provides several public methods representing different actions and events that occur throughout an astronomical observation.

filepath#

The path where the implementing script wants aop to store its files. This could be a part of the implementing script’s installation directory, for example.

conditionDescription#

A short description of the observing conditions.

temp#

The temperature at the observing site in °C.

pressure#

The air pressure at the observing site in hPa.

humidity#

The air humidity at the observing site in %.

__repr__() → str#

A Session object is represented by its attributes.

Returns:

A string containing all the instance’s attributes and their values in line format.

Return type:

str

start(time: str = 'current') → None#

This method is called to start the observing session.

By not starting the observation when a Session object is created, it is possible to prepare the Session object pre-observation as well as parse existing protocols from memory into a new Session object. It changes the Session’s “state” flag to “running”, as well as generating an observation ID, setting up a directory for the protocol to live in, and writing the initial files to that directory.

Parameters:

time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your observation to start. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:

  • PermissionError – If the user does not have the adequate access rights for reading from or writing to the .aop file.

  • AopFileAlreadyExistsError – If the .aop file the method tries to create already exists.

  • AopFileAlreadyExistsError – If the .aopl file the method tries to create for legacy only already exists.

  • AolFileAlreadyExistsError – If the .aol file the method tries to create for legacy only already exists.

static __write_to_aop(self, opcode: str, argument: str, time: str = 'current') → None#

This pseudo-private method is called to update the .aopl legacy protocol file.

For the syntax, check with the Astronomical Observation Protocol Syntax Guide. CAUTION! This method should be considered deprecated and should not be used in any new code!

Parameters:

  • opcode (str) – The operation code of the event to be written to protocol, as described in the AOP Syntax Guide.

  • argument (str) – Whatever is to be written to the argument position in the .aopl protocol entry.

  • time (str, optional) – An ISO 8601 conform string of the UTC datetime you want to use. Can also be “current”, in which case the current UTC datetime will be used. In most cases, however, the calling method will pass its own time argument on to __write_to_aop(), defaults to “current”.

Raises:

PermissionError – If the user does not have the adequate access rights for writing to the .aopl file.

static __write_to_aol(self, parameter: str, assigned_value) → None#

This pseudo-private method is used to update the .aol legacy parameter log.

It takes two arguments, the first being the parameter name being updated, the second one being the value it is assigned. CAUTION! This method should be considered deprecated and should not be used in any new code!

Parameters:

  • parameter (str) – The name of the parameter being updated.

  • assigned_value (any) – The value the parameter should be assigned. Typically, this is a string or boolean.

Raises:

  • PermissionError – If the user does not have the adequate access rights for reading from the .aol file.

  • PermissionError – If the user does not have the adequate access rights for writing to the .aol file.

interrupt(time: str = 'current') → None#

This method interrupts the session.

It sets the Session’s interrupted flag to True and logs that change.

Parameters:

time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your observation to be interrupted at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:
resume(time: str = 'current') → None#

This method resumes the session.

It sets the Session’s interrupted flag to False and logs that change.

Parameters:

time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your observation to be resumed at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:
abort(reason: str, time: str = 'current') → None#

This method aborts the session while providing a reason for doing so.

It sets the Session’s state flag to “aborted” and logs that change.

Parameters:

  • reason (str) – The reason why this session had to be aborted.

  • time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your observation to be aborted at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:
end(time: str = 'current') → None#

This method is called to end the observing session.

It sets the Session’s state flag to “ended” and logs that change.

Parameters:

time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your observation to be ended at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:
comment(comment: str, time: str = 'current') → None#

This method adds an observer’s comment to the protocol.

Parameters:

  • comment (str) – Whatever you want your comment to read in the protocol.

  • time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your comment to be added at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:
issue(severity: str, message: str, time: str = 'current') → None#

This method is called to report an issue to the protocol.

There are three severity levels available:

  • potential

  • normal

  • major

Parameters:

  • severity (str) –

    An indicator of the issue’s severity. It has to be one of the following strings:

    • ”potential”

    • ”p”

    • ”normal”

    • ”n”

    • ”major”

    • ”m”.

  • message (str) – A short description of the issue that is logged as well.

  • time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your issue to be reported at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:

  • SessionNotStartedError – If the session has not yet been started.

  • SessionStateError – If the session is not currently “running”.

  • ValueError –

    If an improper value is passed to the ‘severity’ argument, that is anything different from:

    • ”potential”

    • ”p”

    • ”normal”

    • ”n”

    • ”major”

    • ”m”.

point_to_name(targets: list, time: str = 'current') → None#

This method indicates the pointing to one or more target(s) identified by name.

It can handle multiple targets at once, each will be logged in its own sub-tag of the ‘point’ tag.

Parameters:

  • targets (list[any]) – A list object that contains whatever objects represent the targets, most likely strings, but it could be any other object.

  • time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your pointing to be reported at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:

  • SessionNotStartedError – If the session has not yet been started.

  • SessionStateError – If the session is not currently “running”.

  • TypeError – If the targets argument is not of type list.

point_to_coords(ra: float, dec: float, time: str = 'current') → None#

This method indicates the pointing to ICRS coordinates.

Unlike the point_to_name() method, this method can only handle one set of coordinates each time, ideally representing the middle of the field of view. Provide decimal degrees for declination and decimal hours for right ascension.

Parameters:

  • ra (float) – Right ascension in the ICRS coordinate framework.

  • dec (float) – Declination in the ICRS coordinate framework.

  • time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your pointing to be reported at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:

  • SessionNotStartedError – If the session has not yet been started.

  • SessionStateError – If the session is not currently “running”.

  • TypeError – If ‘ra’ is not of type ‘float’.

  • TypeError – If ‘dec’ is not of type ‘float’.

  • ValueError – If ‘ra’ is not 0.0h <= ‘ra’ < 24.0h.

  • ValueError – If ‘dec’ is not -90.0° <= ‘dec’ <= 90.0°.

take_frame(n: int, ftype: str, iso: int, expt: float, ap: float, time: str = 'current') → None#

This method reports the taking of one or more frame(s) of the same target and the same camera settings used.

It is centered on using a DSLR/DSLM as detector, since it uses the term ISO and expects aperture to be provided as a fraction, like it is common for photographic lenses. You can use a dedicated astronomy camera as well however. Interpret ‘iso’ as Gain and calculate the aperture fraction of your optics for the ‘ap’ argument. This method recognizes five distinct frame types:

  • science/light frame (sometimes called ‘sub’, too)

  • dark frame

  • flat frame

  • bias frame

  • pointing frame

Parameters:

  • n (int) – Number of frames of the specified frame type and settings that were taken of the same target.

  • ftype (str) – Type of frame, ftype must not be anything other than: * “science frame” * “science” * “sf” * “s” * “dark frame” * “dark” * “df” * “d” * “flat frame” * “flat” * “ff” * “f” * “bias frame” * “bias” * “bf” * “b” * “pointing frame” * “pointing” * “pf” * “p”.

  • iso (int) – ISO or Gain setting that was used for the frame(s).

  • ap (float) – The denominator of the aperture setting that was used for the frame(s). For example, if f/5.6 was used, provide ap=5.6 to the method.

  • expt (float) – Exposure time that was used for the frame(s), given in seconds.

  • time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your frame(s) to be reported at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:

  • SessionNotStartedError – If the session has not yet been started.

  • SessionStateError – If the session is not currently “running”.

  • TypeError – If one of the parameters is not of the required type: * n: int * ftype: str * expt: float * ap: float * iso: int

  • ValueError –

    If an improper value is passed in the ‘ftype’ argument, that is anything other than:

    • ”science frame”

    • ”science”

    • ”sf”

    • ”s”

    • ”dark frame”

    • ”dark”

    • ”df”

    • ”d”

    • ”flat frame”

    • ”flat”

    • ”ff”

    • ”f”

    • ”bias frame”

    • ”bias”

    • ”bf”

    • ”b”

    • ”pointing frame”

    • ”pointing”

    • ”pf”

    • ”p”.

condition_report(description: str = None, temp: float = None, pressure: float = None, humidity: float = None, time: str = 'current') → None#

This method reports a condition description or measurement.

Every argument is optional, just pass the values for the arguments you want to log. Each argument will be processed completely separately, so a separate log entry will be produced for every argument you provide. For each type of condition report, a corresponding flag will be set.

Parameters:

  • description (str, optional) – A short description of every relevant element influencing the overall observing description, but do not provide any measurements, as these are a Condition Measurement rather than a Condition Description, defaults to None.

  • temp (float, optional) – The measured temperature in °C, defaults to None.

  • pressure (float, optional) – The measured air pressure in hPa, defaults to None.

  • humidity (float, optional) – The measured air humidity in %, defaults to None.

  • time (str, optional) – An ISO 8601 conform string of the UTC datetime you want your condition update to be reported at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Raises:
Returns:

None

report_variable_star_observation(star_id: str, chart_id: str, magnitude: float, comparison_star_1: str, comparison_star_2: str = None, codes: list = None, time: str = 'current') → None#

This method reports a (visual) observation of a variable star.

Alongside your magnitude estimate, the finder chart you used as well as at least one comparison star and possible comment codes are logged. This method is very much constructed with reporting your observation to the American Association of Variable Star Observers (AAVSO) in mind. Please note, however, that it DOES NOT write an AAVSO Visual File Format compliant report, as this is a higher task left to the front-end application.

Parameters:

  • star_id (str) – An unambiguous identifier of the variable star being observed (e.g. “del Cep”).

  • chart_id – The ID of the finder chart in usage. AAVSO charts usually have a box at the upper right-hand

corner containing this information. :type chart_id: str :param magnitude: Your magnitude estimate, including the decimal point. :type magnitude: float :param comparison_star_1: The label of the first comparison star being used. AAVSO charts leave out the decimal point here, please do so as well. :type comparison_star_1: str :param comparison_star_2: The label of the second comparison star being used, if any. :type comparison_star_2: str, optional :param codes: A list of comment codes detailing your observation. Usage of the official AAVSO one-character comment codes is recommended, but not mandated. :type codes: list, optional :param time: An ISO 8601 conform string of the UTC datetime you want your

observation to be reported at. Can also be “current”, in which case the current UTC datetime will be used, defaults to “current”.

Returns:

None

Raises:
aop.aop.parse_session(filepath: str, session_id: str) → Session#

This function parses a session from memory to a new Session object.

Provided with the filepath to the general location where the log files are stored and an observation ID, it reads in the observation parameters from the session’s log. This information is then used to create a new Session object, which is returned by the function.

Parameters:

  • filepath (str) – The path to the file where you expect the session directory to reside. This is most likely equivalent to the path passed to the Session class to create its files in.

  • session_id (str) – The observation ID of the session to be parsed.

Raises:

  • AolNotFoundError – If there is no .aol legacy file using the specified filepath and observation ID.

  • SessionIdDoesntExistOnFilepathError – If the specified observation ID is not in the filepath provided.

  • NotADirectoryError – If the specified filepath does not constitute a directory.

Returns:

The new Session object parsed from the stored observation parameters. For all intents and purposes, this object is equivalent to the object whose parameters were used to parse, and you can use it to continue your observation session or log just the same. Just be careful not to run the Session.start() method again, as this would overwrite the existing protocol instead of continuing it! Due to the ‘started’ flag of the new Session object most likely being set to True, however, this should generally not be possible.

Return type:

Session