Skip to content

Update example plots #104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
astropenguin merged 2 commits into from
Jul 6, 2025
Merged

Update example plots #104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e12d992
#103 Update example plots
astropenguin Jul 6, 2025
bb7a914
#103 Update README
astropenguin Jul 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 22 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,22 @@ Azimuth/elevation calculator for astronomical objects

## Overview

**Azely** (pronounced "as-elie") is a Python package for calculation and plotting of horizontal coordinates (azimuth and elevation) of astronomical objects at given location and time.
Azely (pronounced "as-elie") is a Python package for calculation and plotting of horizontal coordinates (azimuth and elevation) of astronomical objects at given location and time.
While the core calculation and plotting are handled by [Astropy](https://astropy.org) and [Matplotlib](https://matplotlib.org), Azely provides a simple API for easier and more intuitive use.
For example, calculating and plotting the elevation of the Sun in Tokyo for today can be done in a single line:

```python
import azely

azely.calc('Sun', 'Tokyo').el.plot(ylim=(0, 90))
azely.calc('Sun', 'Tokyo').el.plot(ylabel='Elevation (deg)', ylim=(0, 90))
```

![one-liner.svg](https://raw.githubusercontent.com/astropenguin/azely/1.0.0/docs/_static/one-liner.svg)

## Features

- **Simple API:** Just pass query strings for the object, location, and time information to the `azely.calc()` function. The output is a [pandas](https://pandas.pydata.org) DataFrame of the calculated azimuth and elevation, which makes it easy to convert to other formats like CSV or plot with Matplotlib.
- **Information Retrieval and Cache:** Azely automatically fetches object coordinates and location details from online services. The fetched information is cached in a local TOML file for offline use.
- Simple API: Just pass query strings for the object, location, and time information to the `azely.calc()` function. The output is a [pandas](https://pandas.pydata.org) DataFrame of the calculated azimuth and elevation, which makes it easy to convert to other formats like CSV or plot with Matplotlib.
- Information Retrieval and Cache: Azely automatically fetches object coordinates and location details from online services. The fetched information is cached in a local TOML file for offline use.

## Installation

Expand All @@ -45,15 +45,15 @@ df = azely.calc(object, location, time)

### Query Specification

Parameter | Format & Description | Examples
Parameter | Format and Description | Examples
--- | --- | ---
`location`| **`''`**: Current location inferred from your IP address (default; not cached). | `''`
`location`| **`'<name>'`**: Name of the location to be searched online. | `'ALMA AOS'`, `'Tokyo'`
`location`| **`'<name>;<longitude>;<latitude>[;altitude]'`**: Full location information (not cached). A dictionary is also accepted. | `'ASTE; -67.70d; -22.97d; 4860m'`, `{'name': 'ASTE', 'longitude': '-67.70d', 'latitude': '-22.97d', 'altitude': '4860m'}`
`object` | **`'<name>'`**: Name of the object to be searched online. | `'Sun'`, `'3C 273'`
`object` | **`'<name>;<longitude>;<latitude>[;<frame>]'`**: Full object information (not cached). A dictionary is also accepted. Frame defaults to `'icrs'`. | `'M42; 5h35m; -5d23m'`, `{'name': 'M42', 'longitude': '5h35m', 'latitude': '-5d23m'}`
`time` | **`''`**: 00:00 today to 00:00 tomorrow at a 10-minute step (default; not cached). Timezone follows given location. | `''`
`time` | **`'[<start>][;<stop>][;<step>][;<timezone>]'`**: Full time information (not cached). A dictionary is also accepted. Omitted parts fall back to defaults (`'00:00 today'`, `'00:00 tomorrow'`, `'10min'`, `''`). Timezone follows given location unless not specified. | `'2025-01-01'`, `'09:00 JST today; in 2 days; 1h'`, `{'start': '09:00 JST today', 'stop': 'in 2 days', 'step': '1h'}`
`location`| `''`: Current location inferred from your IP address (default; not cached). | `''`
`location`| `'<name>'`: Name of the location to be searched online. | `'ALMA AOS'`, `'Tokyo'`
`location`| `'<name>;<longitude>;<latitude>[;altitude]'`: Full location information (not cached). A dictionary is also accepted. | `'ASTE; -67.70d; -22.97d; 4860m'`, `{'name': 'ASTE', 'longitude': '-67.70d', 'latitude': '-22.97d', 'altitude': '4860m'}`
`object` | `'<name>'`: Name of the object to be searched online. | `'Sun'`, `'3C 273'`
`object` | `'<name>;<longitude>;<latitude>[;<frame>]'`: Full object information (not cached). A dictionary is also accepted. Frame defaults to `'icrs'`. | `'M42; 5h35m; -5d23m'`, `{'name': 'M42', 'longitude': '5h35m', 'latitude': '-5d23m'}`
`time` | `''`: 00:00 today to 00:00 tomorrow at a 10-minute step (default; not cached). Timezone follows given location. | `''`
`time` | `'[<start>][;<stop>][;<step>][;<timezone>]'`: Full time information (not cached). A dictionary is also accepted. Omitted parts fall back to defaults (`'00:00 today'`, `'00:00 tomorrow'`, `'10min'`, `''`). Timezone follows given location unless not specified. | `'2025-01-01'`, `'09:00 JST today; in 2 days; 1h'`, `{'start': '09:00 JST today', 'stop': 'in 2 days', 'step': '1h'}`

### DataFrame Example

Expand Down Expand Up @@ -90,7 +90,7 @@ import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(12, 4))

for obj in ('Sun', 'Sgr A*', 'M87', 'M104', 'Cen A'):
df = azely.calc(obj, 'ALMA AOS', '2017 Apr 11th UTC')
df = azely.calc(obj, 'ALMA AOS', '2017 April 11 UTC')
df.el.plot(ax=ax, label=df.object.name)

ax.set_title(f'Location: {df.location.name}')
Expand All @@ -117,8 +117,10 @@ from matplotlib.dates import DateFormatter
fig, ax_jst = plt.subplots(figsize=(12, 4))
ax_lst = ax_jst.twiny()

df = azely.calc('Sun', 'Tokyo', '2020-01-01')
df.el.plot(ax=ax_jst, label=df.object.name)
for obj in ('M78', 'M87'):
df = azely.calc(obj, 'Tokyo', '2025-07-07')
df.el.plot(ax=ax_jst, label=df.object.name)

ax_jst.set_title(f'Location: {df.location.name}')
ax_jst.set_ylabel('Elevation (deg)')
ax_jst.set_ylim(0, 90)
Expand Down Expand Up @@ -199,19 +201,20 @@ If you are migrating from Azely version 0.7.0, please check the following change

### The main function and its options have been renamed.

- **0.7.0:** `azely.compute(object, site, time, view)`
- **1.0.0:** `azely.calc(object, location, time)`
- 0.7.0: `azely.compute(object, site, time, view)`
- 1.0.0: `azely.calc(object, location, time)`
- The `site` options has been renamed to `location`.
- The `view` option has been removed. The timezone is inferred from the `location` or can be specified within the `time`.
- The default value settings via `config.toml` has been removed.

### The `in_lst` property of the output DataFrame has become a method.

- **0.7.0:** `df.in_lst` (and `df.in_utc`)
- **1.0.0:** `df.in_lst()` (and `df.in_utc()`)
- 0.7.0: `df.in_lst` (and `df.in_utc`)
- 1.0.0: `df.in_lst()` (and `df.in_utc()`)

### The information cache has been totally changed.

- The separate cache TOML files (`objects.toml`, `locations.toml`) are now merged into a single `cache.toml`.
- The new `source` option specifies the source TOML file instead of prepending to `'<toml>:'` to the query string.
- The new `overwrite` option force-updates cached information instead of appending `'!'` to the query string.
- The new `append` and `source` options provide finer control over the cache behavior.
Loading