aastex

Write AAS journal articles as Python programs.

This library extends PyLaTeX with the pieces of the AASTeX class used by the journals of the American Astronomical Society: titles, authors and their affiliations, acronyms, sections, figures, and bibliographies.

Why write a paper as a program?

In a normal manuscript, the numbers in the prose and the figures beside them are copied from an analysis by hand, and they start drifting from that analysis the moment it changes. Writing the article as a program removes the copying step: figures are generated by the same code that produced the result, and quantities are defined as LaTeX macros computed from Python values, so the text cannot disagree with the analysis behind it.

doc.set_variable_quantity(
    name="speedOfLight",
    value=astropy.constants.c.to(u.km / u.s),
    scientific_notation=True,
)

The prose then refers to \speedOfLight, and the compiled article shows whatever the code computed, correctly formatted with its units.

Installation

aastex is available on PyPI and can be installed using pip:

pip install aastex

Compiling an article also requires a LaTeX installation providing the AASTeX class dependencies. On Debian and Ubuntu:

sudo apt-get install texlive-publishers texlive-science cm-super latexmk

Getting started

import pathlib
import aastex

doc = aastex.Document()
doc.append(aastex.Title("An Interesting Article"))
doc += [
    aastex.Author(
        name="Jane Doe",
        affiliation=aastex.Affiliation("Fancy University"),
        email="jane.doe@fancy.edu",
    )
]

section = aastex.Section("Introduction")
section.append("Some text.")
doc.append(section)

doc.generate_pdf(pathlib.Path("an_interesting_article"))

The documentation walks through a complete example that adds figures, acronyms, computed variables, and a bibliography.

What the library provides

• Document — the article itself. generate_pdf() writes the .tex file, saves every figure beside it, copies in the AASTeX class and bibliography style, and compiles the result.
• Title, Author, Affiliation, Abstract, Section — the parts of a manuscript, which can be referenced from the prose by formatting them into a string, so section and figure numbers are never written by hand.
• Figure, FigureStar, Fig, Gridline — figures built directly from matplotlib figures via add_fig(), or from existing image files via add_image().
• Variable — a numeric value from the analysis, exposed to the prose as a LaTeX macro.
• Acronym — an acronym that expands on first use and is abbreviated afterwards.
• Bibliography — the reference list, from a BibTeX file.

Preparing a submission

The AAS submission system requires every file of a manuscript at the same directory level, since it cannot parse subdirectories. Document.generate_archive() compiles the article and collects the .tex file, the .bbl file required by the AAS conversion software, the class and bibliography style files, and every figure into a flat archive ready to upload:

doc.generate_archive(pathlib.Path("an_interesting_article"), bibliography="sources.bib")

Citation

If you use aastex in your research, please cite it. The citation metadata is kept in CITATION.cff, which the "Cite this repository" button on GitHub can export as BibTeX or APA.

Every release of aastex is archived on Zenodo with its own DOI. The concept DOI, 10.5281/zenodo.23108302, always resolves to the latest version, and the Zenodo page lists the DOI of every version. Please include the version of aastex that you used, which is given by importlib.metadata.version("aastex"). The BibTeX entry below uses the concept DOI. To cite a specific version instead, replace doi with the DOI of that version.

@software{aastex,
  author = {Smart, Roy T.},
  title = {aastex},
  version = {X.Y.Z},
  doi = {10.5281/zenodo.23108302},
  url = {https://github.com/sun-data/aastex},
}