Package: azely
azelyComputation and plotting of azimuth and elevation for astronomical objectsTL;DRAzely (pronounced as "as-elie") is a Python package for computation and plotting of horizontal coordinates (azimuth and elevation; az/el, hereafter) of astronomical objects at given location and time.
While computation and plotting are realized byAstropyandMatplotlib, what azely provides is high-level API to use them easily.
In fact azely offers one-liner to compute and plot, for example, one-day elevation of the Sun in Tokyo:>>>azely.compute('Sun','Tokyo').el.plot(ylim=(0,90))FeaturesHigh-level API:azely provides a simple yet powerfulcompute()function. Users can complete most of operation with it (e.g., information acquisition and computation).Handy output:azely's output (fromcompute()) ispandasDataFrame, a de facto standard data structure of Python. Users can convert it to other formats like CSV and plot it byMatplotlibusing builtin methods.Web information acquisition:azely can automatically acquire object and location information (i.e., longitude and latitude) from online services (e.g., catalogues or maps). Obtained information is cached in a localTOMLfile for an offline use.User-defined information:azely also offers to use user-defined object and location information written in aTOMLfile.RequirementsPython:3.7, 3.8, 3.9, and 3.10 (tested by author)Dependencies:Seepyproject.tomlInstallation$pipinstallazelyBasic usageThis section describes basic az/el computation usingcompute()function.Compute functionAzely'scompute()function receives the following parameters and returnspandasDataFrame (df):>>>importazely>>>df=azely.compute(object,site,time,view,**options)This means thatazelywillcomputeaz/el ofobjectobserved fromsiteat (on)timeinview.
For example, the following code will compute az/el of Sun observed from ALMA AOS on Jan. 1st 2020 in Tokyo.>>>df=azely.compute('Sun','ALMA AOS','2020-01-01','Tokyo')Acceptable formats of each parameter and examples are as follows.ParameterAcceptable formatDescriptionExamplesobject<obj. name>name of object to be searched'Sun','NGC1068'<toml>:<obj. name>user-defined object to be loaded (see below)'user.toml:M42','user:M42'(also valid)site'here'(default)current location (guess by IP address)<loc. name>name of location to be searched'ALMA AOS','Tokyo'<toml>:<loc. name>user-defined location to be loaded (see below)'user.toml:ASTE','user:ASTE'(also valid)time'today'(default)get one-day time range of today'now'get current time<time>start time of one-day time range'2020-01-01','1/1 12:00','Jan. 1st'<time> to <time>start and end of time range'1/1 to 1/3','Jan. 1st to Jan. 3rd'view''(default)use timezone ofsite<tz name>name of timezone database'Asia/Tokyo','UTC'<loc. name>name of location from which timezone is identifiedsame assite's examples<toml>:<loc. name>user-defined location from which timezone is identifiedsame assite's examplesOutput DataFrameThe output DataFrame contains az/el expressed in units of degrees and local sidereal time (LST) atsiteindexed by time inview:>>>print(df)az         el             lst
Asia/Tokyo
2020-01-01 00:00:00+09:00  94.820323  68.416756 17:07:59.405556
2020-01-01 00:10:00+09:00  94.333979  70.709575 17:18:01.048298
2020-01-01 00:20:00+09:00  93.856123  73.003864 17:28:02.691044
2020-01-01 00:30:00+09:00  93.388695  75.299436 17:38:04.333786
2020-01-01 00:40:00+09:00  92.935403  77.596109 17:48:05.976529
...                              ...        ...             ...
2020-01-01 23:20:00+09:00  96.711830  59.146249 16:31:49.389513
2020-01-01 23:30:00+09:00  96.185941  61.431823 16:41:51.032256
2020-01-01 23:40:00+09:00  95.664855  63.719668 16:51:52.674998
2020-01-01 23:50:00+09:00  95.147951  66.009577 17:01:54.317740
2020-01-02 00:00:00+09:00  94.634561  68.301349 17:11:55.960483

[145 rows x 3 columns]ExampleHere is a sample script which will plot one-day elevation of the Sun and candidates of black hole shadow observations at ALMA AOS on Apr. 11th 2017 in UTC.importazelyimportmatplotlib.pyplotaspltplt.style.use('seaborn-whitegrid')fig,ax=plt.subplots(figsize=(12,4))site='ALMA AOS'time='Apr. 11th 2017'view='UTC'forobjin('Sun','Sgr A*','M87','M104','Cen A'):df=azely.compute(obj,site,time,view)df.el.plot(ax=ax,label=obj)ax.set_title(f'site:{site}, view:{view}, time:{time}')ax.set_ylabel('Elevation (deg)')ax.set_ylim(0,90)ax.legend()Advanced usageThis section describes advanced usage of azely by special DataFrame accessor and localTOMLfiles.
Note that azely will create a config directory,$XDG_CONFIG_HOME/azely(if the environment variable exists) or~/.config/azely, after importingazelyfor the first time.TOMLfiles for configuration (config.toml) and cached information (objects.toml,locations.toml) will be automatically created in it.Plotting in local sidereal timeThecompute()function does not accept local sidereal time (LST) asview(i.e.,view='LST') because LST has no information on year and date.
Instead an output DataFrame hasin_lstproperty which provides az/el with a LST index converted from the original time index.
For example, the following code will plot elevation of an object in LST:>>>df.in_lst.el.plot()In order to use LST values as an index of DataFrame, LST has pseudo dates which start from1970-01-01.
Please ignore them or hide them by usingMatplotlibDateFormatter when you plot the result.
Here is a sample script which has JST time axis at the bottom and LST axis at the top of a figure, respectively.importmatplotlib.datesasmdatesfig,ax=plt.subplots(figsize=(12,4))twin=ax.twiny()df=azely.compute('Sun','Tokyo','2020-01-01')df.el.plot(ax=ax,label=df.object.name)df.in_lst.el.plot(ax=twin,alpha=0)ax.set_ylabel("Elevation (deg)")ax.set_ylim(0,90)ax.legend()formatter=mdates.DateFormatter('%H:%M')twin.xaxis.set_major_formatter(formatter)fig.autofmt_xdate(rotation=0)User-defined informationAzely offers to use user-defined information from aTOMLfile.
Here is a sample TOML file (e.g.,user.toml) which has custom object and location informaiton.# user.toml

[ASTE]
name = "ASTE Telescope"
longitude = "-67.70317915"
latitude = "-22.97163575"
altitude = "0"

[GC]
name = "Galactic center"
frame = "galactic"
longitude = "0deg"
latitude = "0deg"If it is located in a current directory or in the azely's config directory, users can use the information like:>>>df=azely.compute('user:GC','user:ASTE','2020-01-01')Cached informationObject and location information obtained from online services is cached toTOMLfiles (objects.toml,locations.toml) in the azely's config directory with the same format as user-defined files.
If a query argument is given with'!'at the end of it, then the cached values are forcibly updated by a new acquisition.
This is useful, for example, when users want to update a current location:>>>df=azely.compute('Sun','here!','2020-01-01')Customizing default valuesUsers can modify default values of thecompute()function by editing the azely's configTOMLfile (config.toml) in the azely's config directory like:# config.toml

[compute]
site = "Tokyo"
time = "now"Thencompute('Sun')becomes equivalent tocompute('Sun', 'Tokyo', 'now').