Dataset#

class astrolore.dataset.astrolore_dataset[source]#

Bases: object

Dataset of real astronomical objects referenced in science fiction, with methods to query it.

The bundled CSV (astrolore/data/scifi_dataset.csv) contains entries for stars, galaxies, nebulae, and other astrophysical objects that appear in science fiction works. Each row stores the object’s name, ICRS RA/DEC coordinates (in degrees), object type, the sci-fi titles that reference it, and a short lore description.

Typical usage:

ds = astrolore_dataset()
closest = ds.find_closest_object(name="Betelgeuse")
print(ds.output_lore(closest))
fig, ax = ds.get_catalog_map()

convert_to_plotting_rad(coords_in_deg)[source]#

Convert a single SkyCoord to matplotlib Aitoff-projection radian convention.

The standard RA→x mapping for an Aitoff projection used by matplotlib negates RA so that east appears on the left (as seen on the sky), then wraps the result into [-π, π]. This helper encapsulates that transformation for a single coordinate.

Parameters:

coords_in_deg (astropy.coordinates.SkyCoord) – The sky position to convert. The .ra and .dec attributes are read in degrees.

Returns:

ra_rad (float): RA in radians, remapped to [-π, π] with east-left orientation.
dec_rad (float): DEC in radians.

Return type:

tuple[float, float]

find_closest_object(name: str = None, coords=None)[source]#

Find the catalog object with the smallest angular separation from a given position.

Exactly one of name or coords must be provided. When name is given, the position is resolved via the CDS Sesame name resolver (requires a network connection). When coords is given, the position is parsed directly without any network call.

The angular separation between the resolved position and every row in scifi_dataframe is computed using astropy.coordinates.SkyCoord.separation and stored in a temporary ang_sep column (degrees). The row with the minimum separation is returned.

Side effects:: Sets self.name, self.name_flag, and self.user_coords on the instance so that output_lore and get_catalog_map can reference them.

Parameters:

name (str, optional) – Common or catalogue name of the target object, e.g. "Arcturus" or "M31". Defaults to None.
coords (tuple[str, str], optional) – Sky position as a (ra, dec) pair of sexagesimal strings in the format ('HHhMMmSSs', 'DDdMMmSSs'), e.g. ('10h8m22.3s', '11d58m1.95s'). The frame is assumed to be ICRS. Defaults to None.

Returns:

The row from scifi_dataframe that is closest on the sky to the input position, including the computed ang_sep value in degrees.

Return type:

pandas.Series

Raises:

astropy.coordinates.name_resolve.NameResolveError – If name is given but cannot be resolved.
ValueError – If the coordinate strings in coords are malformed.

static format_sources(sources: list)[source]#

Format a list of sci-fi source titles into a human-readable Oxford-comma string.

Converts a raw list produced by splitting the scifi_source CSV field into a grammatically correct English enumeration.

Parameters:

sources (list[str]) – Sci-fi titles, e.g. ['Star Trek', 'Star Wars', 'Dune'].

Returns:

Formatted string. Examples:

[] → ""
['Dune'] → "Dune"
['Star Trek', 'Dune'] → "Star Trek and Dune"
['Star Trek', 'Star Wars', 'Dune'] → "Star Trek, Star Wars, and Dune"

Return type:

str

get_catalog_map()[source]#

Generate a full-sky Aitoff projection map showing the search results.

Plots three layers on a dark background:

White stars — all objects in the sci-fi catalog.
Gold star — the nearest catalog object to the user’s input.
Red star — the user’s input position.

A dashed white arrow connects the user’s position to the nearest catalog object (omitted when both points are at the same sky location). Labels in gold and white identify the two highlighted points.

Must be called after both find_closest_object and output_lore, as it reads self.user_coords, self.close_object, and self.name from instance state set by those methods.

Returns:: The figure and axes objects. The figure is closed before returning (plt.close(fig)), so it can safely be passed to FigureCanvasTkAgg without being displayed in a separate matplotlib window.
Return type:: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

static get_coords_from_name(name)[source]#

Resolve an astronomical object name to sky coordinates via CDS Sesame.

Delegates to astropy.coordinates.SkyCoord.from_name, which queries the Simbad/NED name resolver over the network.

Parameters:: name (str) – Common or catalogue name of the object, e.g. "Andromeda" or "NGC 224".
Returns:: ICRS coordinates of the resolved object.
Return type:: astropy.coordinates.SkyCoord
Raises:: astropy.coordinates.name_resolve.NameResolveError – If the name cannot be found in any of the queried catalogues.

index_of_object(object)[source]#

Return the integer position of a catalog object within scifi_dataframe.

Parameters:

object (str) – The name of the object to look up. Must match exactly one entry in the name column of scifi_dataframe.

Returns:

Zero-based index of the object in scifi_dataframe.

Return type:

int

Raises:

NotImplementedError – If object is a pandas.Series (lookup by Series is not yet implemented).
ValueError – If object is neither a str nor a pandas.Series.

init_catalog_map(closest_object: Series)[source]#

Pre-compute plotting coordinates for every catalog object and for the closest match.

Converts all RA/DEC values in scifi_dataframe from degrees to the radian convention used by matplotlib’s Aitoff projection (RA negated and remapped to [-π, π] so that east is to the left, matching the standard celestial orientation).

Parameters:

closest_object (pandas.Series) – The catalog row for the nearest sci-fi object, as returned by find_closest_object.

Returns:

ra_rad (pandas.DataFrame): Plotting RA values (radians, Aitoff convention) for all catalog objects.
dec_rad (pandas.DataFrame): Plotting DEC values (radians) for all catalog objects.
closest_ra_rad (float): Plotting RA (radians) for closest_object.
closest_dec_rad (float): Plotting DEC (radians) for closest_object.

Return type:

tuple

name_of_object(object)[source]#

Return the name field of a catalog row.

Parameters:: object (pandas.Series) – A single row from scifi_dataframe, as returned by find_closest_object.
Returns:: The name column value for that row.
Return type:: str
Raises:: ValueError – If object is not a pandas.Series.

output_lore(close_object: Series)[source]#

Build a human-readable lore string for the closest sci-fi object.

Produces one of two message styles:

Exact match (ang_sep < 0.01°): Announces that the user’s own object is referenced in science fiction and quotes its lore text directly.
Nearest match: Reports the angular distance to the closest catalog object and quotes its sci-fi references and lore.

Side effects:: Sets self.close_object on the instance so that get_catalog_map can reference it without re-running the search.

Parameters:: close_object (pandas.Series) – The catalog row returned by find_closest_object. Must contain the fields ang_sep, scifi_source, name, object_type, and lore.
Returns:: Formatted multi-line string ready to display in the GUI or print to the terminal.
Return type:: str

Dataset

Contents

Dataset#