azely package

Submodules

• azely.azel module
  • AzEl
    • AzEl.alt
    • AzEl.in_lst
    • AzEl.in_utc
  • compute()
• azely.consts module
  • DAYFIRST
  • FRAME
  • FREQ
  • HERE
  • NOW
  • TIMEOUT
  • TODAY
  • YEARFIRST
• azely.location module
  • Location
    • Location.altitude
    • Location.latitude
    • Location.longitude
    • Location.name
    • Location.to_dict()
    • Location.to_earthloc()
    • Location.tzinfo
  • get_location()
• azely.object module
  • Object
    • Object.frame
    • Object.is_solar()
    • Object.latitude
    • Object.longitude
    • Object.name
    • Object.to_dict()
    • Object.to_skycoord()
  • get_object()
• azely.time module
  • Time
    • Time.to_index()
    • Time.to_obstime()
  • get_time()
• azely.utils module
  • AzelyError
  • cache_to
    • cache_to.pattern
  • open_toml()
  • set_defaults
    • set_defaults.update()

Module contents

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

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')

get_location(query: str = 'here', timeout: int = 10) → Location

Get location information by various ways.

This function acquires location information by the following three ways: (1) Guess by IP address (by default). Internet connection is required. (2) Data from OpenStreetMap. Internet connection is required. (3) User-defined location information written in a TOML file.

In the cases of (1) and (2), obtained location information is cached in a special TOML file (~/.config/azely/locations.toml) for an offline use.

In the case of (3), users can define location information in a TOML file (e.g., user.toml) which should be put in a current directory or in the Azely’s config directory (~/.config/azely).

Then location information can be obtained by get_location(<query>). Use get_location(<name>:<query>) for user-defined location information, where <name> must be the name of a TOML file without suffix or the full path of it. If it does not exist in a current directory, the function will try to find it in the Azely’s config directory (~/.config/azely).

Parameters:

• query (str) – Query string (e.g., 'ALMA AOS' or 'user:ASTE'). Default value, ‘here’, is a special one with which the function tries to guess location information by an IP address of a client.

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

Returns:

Location information as an instance of Location class.

Raises:

AzelyError – Raised if the function fails to get location information.

Return type:

Location

Examples

To get location information by IP address:

>>> loc = azely.location.get_location('here')

To get location information from OpenStreetMap:

>>> loc = azely.location.get_location('ALMA AOS')

To get location information from user.toml:

>>> loc = azely.location.get_location('user:ASTE')

get_object(query: str, frame: str = 'icrs', timeout: int = 10) → Object

Get object information by various ways.

This function acquires object information by the following two ways: (1) Data from CDS (by default). Internet connection is required. (2) User-defined object information written in a TOML file.

In the case of (1), obtained object information is cached in a special TOML file (~/.config/azely/objects.toml) for an offline use.

In the case of (2), users can define object information in a TOML file (e.g., user.toml) which should be put in a current directory or in the Azely’s config directory (~/.config/azely).

Then object information can be obtained by get_object(<query>). Use get_object(<name>:<query>) for user-defined object information, where <name> must be the name of a TOML file without suffix or the full path of it. If it does not exist in a current directory, the function will try to find it in the Azely’s config directory (~/.config/azely).

Parameters:

• query (str) – Query string (e.g., 'NGC1068' or 'user:GC').

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

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

Returns:

Object information as an instance of Object class.

Raises:

AzelyError – Raised if the function fails to get object information.

Return type:

Object

Notes

As object is the Python’s builtin base class, it might be better to use an alternative variable name (e.g., object_ or obj) for object information which this function returns.

Examples

To get object info from CDS:

>>> obj = azely.object.get_object('NGC1068')

To get object info from user.toml:

>>> obj = azely.object.get_object('user:GC')

get_time(query: str = 'today', view: str = 'here', freq: str = '10T', dayfirst: bool = False, yearfirst: bool = False, timeout: int = 10) → Time

Get time information by various ways.

The get_time function computes time information in several cases: (1) Current time (e.g., [2020-01-01 22:32:58+09:00]). (2) Time range of today (e.g., [2020-01-01 00:00, …, 2020-01-02 00:00]) (3) Time range of given date and length (by query)

In the cases of (1) and (2), special queries, 'now' and 'today', must be specified, respectively. The view option specifies a timezone where time (range) is considered (timezone or location name can be accepted).

In the case of (3), formatted query (e.g., '2020-01-01 to 2020-01-05') or natural language-like query can be used (e.g., 'Jan. 1st to Jan. 5th'), where start and end must be separated by 'to'. The view option also works.

Parameters:

• query (str) – Query string (e.g., '2020-01-01 to 2020-01-05'). If 'today' (by default) or 'now' is specified, then time range of today or current time is computed, respectively.

• view (str) – Name of timezone (e.g., 'Asia/Tokyo' or 'UTC') or location with which timezone can be identified (e.g., 'Tokyo').

• freq (str) – 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) – 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) – 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) – Query timeout expressed in units of seconds (see notes).

Returns:

Time information as an instance of Time class.

Raises:

AzelyError – Raised if the function fails to parse query or timezone.

Return type:

Time

Notes

If location is specified as view, then azely.location.get_location function is used inside the function, which requires internet connection if the location is queried for the first time.

Examples

To get current time in Tokyo:

>>> time = azely.time.get_time('now', view="Tokyo")

To get current time in UTC:

>>> time = azely.time.get_time('now', view="UTC")

To get time range of today at ALMA AOS:

>>> time = azely.time.get_time('today', view="ALMA AOS")

To get time range from Jan. 1 to Jan. 5 in 2020 in UTC:

>>> time = azely.time.get_time('2020-01-01 to 2020-01-05', view='UTC')