azely.azel module#

Azely’s azel module (high-level API).

This module mainly provides compute function as a high-level API for users which computes azimuth/elevation of an astronomical object under given conditions.

The compute function (1) gets object, location, and time information, (2) computes az/el and LST (local sidereal time), and (3) returns them as a pandas DataFrame.

Object information can be obtained either online (CDS) or offline (an user-defined TOML file) by query (e.g., 'NGC1068' or 'Sun'). Location information can be obtained either online (IP address or OpenStreetMap) or offline (an user-defined TOML file) by query (e.g., 'Tokyo' or 'ALMA AOS'). Time information can be computed from either formatted (e.g., '2020-01-01') and natural language-like query (e.g., 'Jan 1st 2020'). See docstrings of get_[object|location|time] functions for more detailed query options.

There are two different locations to be used for a computation: (1) site: location where az/el of an object is computed. (2) view: location where time information (timezone) is considered.

Examples

To compute daily az/el of NGC1068 at ALMA AOS:

>>> df = azely.compute('NGC1068', 'ALMA AOS', '2020-02-01')

To compute the same object and location but view from Japan:

>>> df = azely.compute('NGC1068', 'ALMA AOS', '2020-02-01', view='Tokyo')

To compute az/el of Sun at noon during an year at Tokyo:

>>> df = azely.compute('Sun', 'Tokyo', '1/1 12:00 to 12/31 12:00', freq='1D')

As DataFrame has plot method for matplotlib, plotting the result is so easy:

>>> df.el.plot() # plot elevation

If users want to use LST instead of time information, use in_lst property:

>>> df.in_lst.el.plot()

In order to use LST values as an index of DataFrame, LST has pseudo dates which start from 1970-01-01. Please ignore them or hide them by using matplotlib’s DateFormatter when you plot the result.

class AzEl(data=None, index: Optional[Union[ExtensionArray, ndarray, Index, Series, List, range]] = None, columns: Optional[Union[ExtensionArray, ndarray, Index, Series, List, range]] = None, dtype: Optional[Union[ExtensionDtype, str, dtype, Type[Union[str, complex, bool, object]]]] = None, copy: Optional[bool] = None)[source]#

Bases: DataFrame

Subclass of pandas DataFrame with special properties for Azely.

Parameters:

  • index (Axes | None) –

  • columns (Axes | None) –

  • dtype (Dtype | None) –

  • copy (bool | None) –

property alt#

Alias of dataframe.el.

property in_lst#

Convert time index to LST.

property in_utc#

Convert time index to UTC.

compute(object: str, site: str = 'here', time: str = 'today', view: str = '', frame: str = 'icrs', freq: str = '10T', dayfirst: bool = False, yearfirst: bool = False, timeout: int = 10) → AzEl[source]#

Compute az/el and local sidereal time (LST) of an astronomical object.

The compute function (1) gets object, location, and time information, (2) computes az/el and LST (local sidereal time), and (3) returns them as a pandas DataFrame.

Object information can be obtained either online (CDS) or offline (an user-defined TOML file) by query (e.g., 'NGC1068' or 'Sun'). Location information can be obtained either online (IP address or OpenStreetMap) or offline (an user-defined TOML file) by query (e.g., 'Tokyo' or 'ALMA AOS'). Time information can be computed from either formatted (e.g., '2020-01-01') and natural language-like query (e.g., 'Jan 1st 2020'). See docstrings of get_[object|location|time] functions for more detailed query options.

There are two different locations to be used for a computation: (1) site: location where az/el of an object is computed. (2) view: location where time information (timezone) is considered.

Parameters:

  • object (str) – Query string for object information (e.g., 'Sun' or 'NGC1068'). Specify 'user:NGC1068' if users want to get information from user.toml.

  • site (str) – Query string for location information at a site (e.g., 'Tokyo'). Specify 'user:Tokyo' if users want to get information from user.toml.

  • time (str) – Query string for time information at a view (e.g., '2020-01-01').

  • view (str) – Query string for timezone information at the view. (e.g., 'Asia/Tokyo', 'UTC', or Tokyo). By default (''), timezone at the site is used.

  • frame (str) – (object option) Name of equatorial coordinates used in astropy’s SkyCoord.

  • freq (str) – (time option) Frequency of time samples as the same format of pandas offset aliases (e.g., '1D' -> 1 day, '3H' -> 3 hours, '10T' -> 10 minutes).

  • dayfirst (bool) – (time option) Whether to interpret the first value in an ambiguous 3-integer date (e.g., '01-02-03') as the day. If True, for example, '01-02-03' is treated as Feb. 1st 2003.

  • yearfirst (bool) – (time option) Whether to interpret the first value in an ambiguous 3-integer date (e.g., '01-02-03') as the year. If True, for example, '01-02-03' is treated as Feb. 3rd 2001. If dayfirst is also True, then it will be Mar. 2nd 2001.

  • timeout (int) – (common option) Query timeout expressed in units of seconds.

Returns:

Computed DataFrame of object’s az/el and LST at given site and view.

Raises:

AzelyError – Raised if one of mid-level APIs fails to get any information.

Return type:

AzEl

Examples

To compute daily az/el of NGC1068 at ALMA AOS:

>>> df = azely.compute('NGC1068', 'ALMA AOS', '2020-02-01')

To compute the same object and location but view from Japan:

>>> df = azely.compute('NGC1068', 'ALMA AOS', '2020-02-01', view='Tokyo')

To compute az/el of Sun at noon during an year at Tokyo:

>>> df = azely.compute('Sun', 'Tokyo', '1/1 12:00 to 12/31 12:00', freq='1D')