Introduction#
aastex lets you write an article for the journals of the American
Astronomical Society as a Python program.
It extends PyLaTeX with the pieces of the
AASTeX LaTeX package
that a manuscript needs: titles, authors and their affiliations, acronyms,
sections, figures, and bibliographies.
In an ordinary manuscript, the numbers quoted in the prose and the figures printed beside them are copied out of an analysis by hand, and they begin to drift from that analysis as soon as it changes. Writing the article as a program removes the copying step. Figures are drawn by the same code that produced the result, and quantities are declared as LaTeX macros computed from Python values, so the text cannot disagree with the analysis behind it.
Since aastex is built on PyLaTeX, anything that library can express is
available here as well;
see the PyLaTeX documentation
for the underlying model of documents, environments, and commands.
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 dependencies of the AASTeX class. On Debian and Ubuntu:
sudo apt-get install texlive-publishers texlive-science cm-super latexmk
Writing an article#
The example below builds a small but complete article, one piece at a time.
Each step appends to the same aastex.Document, which is compiled at the
end.
Start by configuring matplotlib to render text with LaTeX, so that the
figures use the same fonts as the surrounding article, and create the document.
aastex.Document defaults to the AASTeX class in its two column style.
import pathlib
import numpy as np
import matplotlib.pyplot as plt
import astropy.units as u
import astropy.constants
import aastex
plt.rcParams['text.usetex'] = True
plt.rcParams['font.family'] = 'serif'
plt.rcParams['font.size'] = 9
plt.rcParams['lines.linewidth'] = 1
doc = aastex.Document()
Every article needs a title, and one or more authors.
An aastex.Author carries an aastex.Affiliation, and optionally
an ORCID and an email address, which AASTeX prints in the front matter.
title = aastex.Title("An Interesting Article")
doc.append(title)
msu = aastex.Affiliation(
'Montana State University, Department of Physics, '
'P.O. Box 173840, Bozeman, MT 59717, USA'
)
author = aastex.Author(
name='Roy T. Smart',
affiliation=msu,
email="[email protected]",
corresponding=True,
)
doc.append(author)
An aastex.Acronym is defined once and then used in the prose through a
macro named after it, \NASA in this case.
The first use in the text expands to the full phrase followed by the
abbreviation, and later uses give the abbreviation alone, so the convention is
applied for you no matter how the text is later rearranged.
nasa = aastex.Acronym("NASA", "National Aeronautics and Space Administration")
doc.preamble.append(nasa)
The abstract is a container like any other section of the document, so text is
appended to it.
Here the LaTeX lipsum package provides placeholder prose.
abstract = aastex.Abstract()
abstract.packages.append(aastex.Package("lipsum"))
abstract.append("Some text summarizing the article. ")
abstract.append(r"\lipsum[1-1]")
doc.append(abstract)
This is the step that keeps the article honest.
aastex.Document.set_variable_quantity() defines a LaTeX macro from an
astropy.units.Quantity, formatting the value and its units, so the
prose can cite \speedOfLight instead of a number typed by hand.
Recompute the value and the article follows.
doc.set_variable_quantity(
name="speedOfLight",
value=astropy.constants.c.to(u.km / u.s),
scientific_notation=True,
digits_after_decimal=4,
)
Figures are created from matplotlib figures using
aastex.Figure.add_fig().
The label given to aastex.Figure names both the LaTeX label and the
image file saved next to the article, and the plot may be closed once it has
been added, since it is not saved until the document is compiled.
The constants aastex.column_width_inches and
aastex.text_width_inches give the width of a column and of the full page,
which are the two useful figure widths in a two column article.
fig, ax = plt.subplots(
figsize=(aastex.column_width_inches, 2),
constrained_layout=True,
)
x = np.linspace(-6, 6, num=101)[..., np.newaxis]
y = np.sinc(x) + np.random.normal(scale=0.1, size=(101, 11))
ax.plot(*np.broadcast_arrays(x, y))
figure = aastex.Figure("data")
figure.add_fig(fig, width=None)
plt.close(fig)
figure.add_caption(aastex.NoEscape(
r"Here is a figure caption. \lipsum[5-5]"
))
Now the body of the article.
Note how the section and the figure are formatted into the string:
aastex.Section and aastex.Figure render as references to
themselves, so numbering is never written by hand and never goes stale when the
document is reordered.
The acronym and the variable defined above are used here as \NASA and
\speedOfLight.
intro = aastex.Section("Introduction")
intro.packages.append(aastex.Package("lipsum"))
intro.append(
rf"Here is a citation \citep{{knuth:1984}}. "
rf"The speed of light is \speedOfLight. "
rf"Here is a reference to Section {intro}. "
rf"Here is a reference to Figure {figure}. "
rf"Here is an acronym: \NASA. "
rf"Here is the acronym again: \NASA. "
rf"\lipsum[2-2]"
)
intro.append(figure)
intro.append(r"\lipsum[3-5]")
doc.append(intro)
Finally the bibliography, which reads the BibTeX file sources.bib sitting
beside the article, and resolves the citation used above.
doc.append(aastex.Bibliography("sources"))
aastex.Document.generate_pdf() writes the .tex file, saves each figure
next to it, copies in the AASTeX class and bibliography style, and runs LaTeX.
path_pdf = pathlib.Path("an_interesting_article.pdf")
doc.generate_pdf(filepath=path_pdf.with_suffix(""))
Which outputs the following PDF:
Preparing a submission#
The AAS submission system
requires every file of a manuscript to sit at the same directory level, since it
cannot parse subdirectories.
aastex.Document.generate_archive() compiles the article and gathers the
.tex file, the .bbl file required by the AAS conversion software, the
AASTeX class and bibliography style files, and every figure into a flat archive
which is ready to upload:
doc.generate_archive(
pathlib.Path("an_interesting_article"),
bibliography="sources.bib",
)
Pass format="gztar" for a .tar.gz archive instead of a .zip.
Animated figures#
The AAS journals can accompany a figure with a movie, which they play in the online version of the article in place of the still frames printed in the PDF. Nothing else plays it: not the compiled PDF, and not the HTML version of the article made by arXiv. So until the article is published, the movie can only be watched wherever its authors have put it.
Give the figure an aastex.Animation, and add its still frames as usual.
If the animation has a url, the caption ends with a link to it, so that
readers of a draft can find the movie.
figure = aastex.Figure(
"evolution",
animation=aastex.Animation(
source="evolution.mp4",
url="https://example.org/article/evolution.mp4",
),
)
figure.add_image("evolution.pdf", width=None)
figure.add_caption(
"The evolution of the event. "
"The animation runs for 30 seconds and shows the whole event."
)
The journals ask the caption to describe what the animation shows, how long it
runs, and how it changes, rather than only saying that it exists.
aastex.Document.generate_pdf() copies each movie beside the PDF, so a
draft and its movies can be published together.
aastex.Document.generate_archive() leaves the movies out of the main
archive and packs each into an archive of its own, named after the number of its
figure, such as fig01anim.zip, since the journals ask for them to be
uploaded separately.
Citing software#
An article built by a program depends on particular versions of the packages it
uses, and later versions rename and remove what the article describes.
So the article should cite the version it was built with, and link to the
documentation of that version.
An aastex.PythonPackage does both, reading everything it needs from the
metadata of the installed package, so the citation and the links follow
whatever version the article is built with.
List each package in the aastex.Software command the AAS journals ask
for, and add software to the sources of the bibliography:
optika = aastex.PythonPackage("optika")
doc.append(aastex.Software([optika, r"astropy \citep{astropy}"]))
doc.append(aastex.Bibliography("sources,software"))
Then cite the package with \citep{optika}, and link to the documentation of
the version used with the macro \docs{optika}:
The model is implemented by
\href{\docs{optika}/_autosummary/optika.sensors.signal.html}{\texttt{optika.sensors.signal()}}
\citep{optika}.
A key which no listed package documents stops LaTeX with an error, rather than making a broken link.
aastex.Document.generate_pdf() writes the BibTeX entry of each package
into software.bib beside the article.
A release is cited by the DOI of its own archive on Zenodo, and a development
version by the concept DOI, which resolves to the latest release.
Each entry is reused by later builds for as long as the version stays the same,
so Zenodo is only asked when a version changes, and an unchanged article can be
rebuilt offline.
On Read the Docs, \docs links a release X.Y.Z to the documentation of
the tag vX.Y.Z, and anything else to the latest documentation.
A package whose tags have no v, or some other prefix, needs it given as
tag_prefix.
For this to work, the package declares where its documentation is, and the
concept DOI it is archived under on Zenodo, in its pyproject.toml:
[project.urls]
Documentation = "https://optika.readthedocs.io/en/latest"
DOI = "https://doi.org/10.5281/zenodo.23074621"
Its Read the Docs project also needs an automation rule which activates every
new tag matching SemVer versions, since Read the Docs only builds the
versions which are active.
A package which declares no DOI, or a release made before it did, can be given
one with aastex.PythonPackage("optika", doi="10.5281/zenodo.23074621").
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 the
GitHub page
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").
An article written with aastex can cite the version it was built with
by listing aastex.PythonPackage("aastex") in its aastex.Software,
as described in Citing software.
Otherwise, 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},
}
API Reference#
Write AAS journal articles as Python programs. |