juliensimon/lunar-eclipse-catalog

---
license: cc-by-4.0
pretty_name: "Five Millennium Catalog of Lunar Eclipses"
language:
- en
description: "Complete catalog of lunar eclipses spanning five millennia (-1999 to +3000), computed by Fred Espenak as part of NASA's Five Millennium Canon of Lunar Eclipses. A lunar eclipse occurs when the Moon p"
task_categories:
- tabular-classification
tags:
- space
- lunar-eclipse
- eclipse
- moon
- astronomy
- nasa
- planetary-science
- open-data
- tabular-data
- parquet
size_categories:
- 10K<n<100K
configs:
- config_name: default
data_files:
- split: train
path: data/lunar_eclipses.parquet
default: true
---

# Five Millennium Catalog of Lunar Eclipses

<div align="center">
<img src="banner.jpg" alt="The Moon seen from Apollo 8, showing craters and surface detail" width="400">
<p><em>Credit: NASA/Apollo 8</em></p>
</div>

*Part of a [dataset collection](https://huggingface.co/collections/juliensimon/astronomy-datasets-69c24caf2f17e36128946743) on Hugging Face.*

## Dataset description

Complete catalog of lunar eclipses spanning five millennia (-1999 to +3000), computed by Fred Espenak as part of NASA's Five Millennium Canon of Lunar Eclipses.

A lunar eclipse occurs when the Moon passes through Earth's shadow. The Moon can enter the faint penumbral shadow (producing a subtle darkening), the darker umbral shadow (producing a clearly visible partial eclipse), or become fully immersed in the umbra (a total lunar eclipse, often dramatically colored red by sunlight refracted through Earth's atmosphere). Unlike solar eclipses, lunar eclipses are visible from the entire night side of Earth simultaneously, making them historically important for synchronizing calendars across civilizations.

This catalog is derived from Fred Espenak's Five Millennium Canon of Lunar Eclipses, using the same computational foundation as the companion solar eclipse catalog: Besselian elements with polynomial expressions from Chapront, Chapront-Touze, and Francou for lunar and solar coordinates, with corrections for the secular acceleration of the Moon and variable Earth rotation via Delta-T.

The **gamma** parameter measures the signed minimum distance of the Moon's center from Earth's shadow axis. When gamma is between -0.9972 and +0.9972, the Moon is fully immersed in the umbra (total eclipse); between ±1.0260 it is partially in the umbra (partial eclipse); and between ±1.0620 only the penumbra is intersected. The **umbral_magnitude** gives the fraction of the Moon's diameter immersed in the umbra — values above 1.0 indicate a total eclipse. Red coloring during totality depends on Earth's atmospheric transparency at the time, described qualitatively by the Danjon scale (0 = very dark, 4 = bright copper-red).

This dataset is suitable for **tabular classification** tasks.

## Schema

| Column | Type | Description | Sample | Null % |
|--------|------|-------------|--------|--------|
| `catalog_number` | Int64 | Sequential catalog number (1 to ~12,000), monotonically increasing with time | 1 | 0.0% |
| `date` | object | Date of greatest eclipse in ISO format (YYYY-MM-DD); negative year values indicate BCE dates | -1999-06-26 | 0.0% |
| `year` | Int64 | Calendar year; negative for BCE (e.g., -500 = 500 BCE); range -1999 to +3000 | -1999 | 0.0% |
| `td_greatest_eclipse` | object | Time of greatest eclipse in Terrestrial Dynamical Time (TDT), format HH:MM:SS | 14:13:28 | 0.0% |
| `delta_t` | float64 | Difference between Terrestrial Dynamical Time and Universal Time (TDT - UT) in seconds; large and uncertain for ancient dates (>10,000 s before 1000 CE) | 46437.0 | 0.0% |
| `luna_number` | Int64 | Lunation count in Brown's series (consecutive full-moon numbering since 1923-01-17) | -49456 | 0.0% |
| `saros_number` | Int64 | Saros series number; each series repeats every 18 years 11 days 8 hours and produces ~70-80 eclipses over ~1,300 years | 17 | 0.0% |
| `eclipse_type` | object | Eclipse type code: T (total), P (partial), N (penumbral); may include + or - suffix for exceptional duration, or x/b/e suffix for subtype | N | 0.0% |
| `eclipse_type_name` | object | Full English name of eclipse type corresponding to the eclipse_type code | Penumbral | 0.0% |
| `is_total` | bool | True if the eclipse is a total lunar eclipse (Moon fully within Earth's umbra) | False | 0.0% |
| `gamma` | float64 | Signed minimum distance of the Moon's center from Earth's shadow axis in Earth equatorial radii; \|gamma\| < 0.9972 for total, < 1.0260 for partial, < 1.0620 for penumbral | -1.0981 | 0.0% |
| `umbral_magnitude` | float64 | Eclipse magnitude in the umbral shadow: >1.0 for total, 0 to 1.0 for partial, negative for penumbral-only eclipses | -0.1922 | 0.0% |
| `penumbral_magnitude` | float64 | Eclipse magnitude in the penumbral shadow; always >= umbral_magnitude; >1.0 triggers easily visible penumbral shading | 0.8791 | 0.0% |
| `partial_duration` | float64 | Duration of partial phases (first/last umbral contact) in minutes; null for penumbral-only eclipses | 102.7 | 36.3% |
| `total_duration` | float64 | Duration of totality (both umbral contacts) in minutes; null for partial and penumbral eclipses | 98.2 | 71.2% |
| `penumbral_duration` | float64 | Total duration of penumbral contact in minutes from first to last penumbral contact | 268.8 | 0.0% |
| `latitude` | float64 | Geographic latitude at the point of greatest eclipse in decimal degrees (+ = North, - = South) | -24.0 | 0.0% |
| `longitude` | float64 | Geographic longitude at the point of greatest eclipse in decimal degrees (+ = East, - = West) | -22.0 | 0.0% |
| `century` | Int64 | Derived century computed as year // 100; useful for aggregating eclipses by historical period | -20 | 0.0% |

## Quick stats

- **12,064** lunar eclipses (-1999 to 3000)
- **3,479** total (28.8%), **4,207** partial (34.9%), **4,378** penumbral (36.3%)
- Average totality duration for total eclipses: **80.8 min**
- Longest total eclipse in catalog: **106.6 min** (~1.78 h)

## Usage

```python
from datasets import load_dataset

ds = load_dataset("juliensimon/lunar-eclipse-catalog", split="train")
df = ds.to_pandas()
```

```python
from datasets import load_dataset

ds = load_dataset("juliensimon/lunar-eclipse-catalog", split="train")
df = ds.to_pandas()

# Filter by eclipse type
total = df[df["is_total"] == True]
print(f"{len(total):,} total lunar eclipses across 5 millennia")

# Longest total eclipses (Blood Moons)
longest = total.nlargest(5, "total_duration")[["date", "total_duration", "gamma"]]
print(longest)

# Eclipses per century
import matplotlib.pyplot as plt
by_century = df.groupby("century")["eclipse_type_name"].value_counts().unstack(fill_value=0)
by_century.plot.bar(stacked=True, figsize=(14, 5), colormap="Set2")
plt.xlabel("Century")
plt.ylabel("Number of Eclipses")
plt.title("Lunar Eclipse Types by Century")
plt.tight_layout()
plt.show()
```

## Data source

https://eclipse.gsfc.nasa.gov/LEcat5/LEcatalog.html

## Related datasets

- [juliensimon/solar-eclipse-catalog](https://huggingface.co/datasets/juliensimon/solar-eclipse-catalog)

- [juliensimon/lunar-craters-robbins](https://huggingface.co/datasets/juliensimon/lunar-craters-robbins)

- [juliensimon/iers-earth-orientation](https://huggingface.co/datasets/juliensimon/iers-earth-orientation)

> If you find this dataset useful, please consider [giving it a like](https://huggingface.co/datasets/juliensimon/lunar-eclipse-catalog) on Hugging Face. It helps others discover it.

## About the author

Created by [Julien Simon](https://julien.org) — AI Operating Partner at Fortino Capital. Part of the [Space Datasets](https://julien.org/datasets) collection.

## Citation

```bibtex
@dataset{lunar_eclipse_catalog,
title = {Five Millennium Catalog of Lunar Eclipses},
author = {juliensimon},
year = {2026},
url = {https://huggingface.co/datasets/juliensimon/lunar-eclipse-catalog},
publisher = {Hugging Face}
}
```

## License

[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)