Data Guide

AAS Journals encourage the enrichment of articles with data and other digital materials, including data links. Such materials are subject to the same peer-review standards as the articles as a whole, and their inclusion should be justified on scientific grounds.  Regardless of the format for providing such material, authors must familiarize themselves with resources such as the “Best Practices for Data Publication” (Chen et al. 2022, ApJS, doi:10.3847/1538-4365/ac6268) to guide the style and formatting of such data; the most recent version of these Best Practices guidelines can be found at NED (doi:10.26132/NED7).

The Journals also provide data services to authors, including data review, archiving data behind figures, and linking Journal data to outside repositories. This data guide provides instructions for including, and citing data in your articles. For more information on these options and services, authors should contact the AAS Journals’ data editors.

Machine Readable Tables

It is in the best interest of both the author and the reader for lengthy tables to appear in a machine readable table format. Machine readable tables (MRTs) consist of structured ASCII (non-binary) data with a meta-data header. Those MRTs published in the AAS Journals utilize very similar standards and styles as CDS’s VizieR tables. Indeed, VizieR harvests AAS Journal MRTs and makes these data discoverable and searchable via Virtual Observatory protocols, which is another benefit to using this data format.

When tables are longer than ~200 data rows or contain critical object related data, authors are strongly encouraged to deliver their tables at submission in a machine readable format. See the latest AASTeX guide for details on how to incorporate a machine readable table into a LaTeX manuscript.

Authors who deliver machine-readable tables should state this at the time of submission, and must include the data with the submission so that it can be evaluated during the review process. The data should be in the standardized CDS MRT format or in raw ASCII (formatted or delimited) or in the form of a LaTeX table. Word/RTF users should save the table as a tab-delimited ASCII file. It is desirable to include information regarding the format, units, and a short description of each column when an ASCII table is submitted. When submitting, authors should name the ASCII tables tab#.txt, where # is the table number.

Authors may create their own standardized machine-readable tables using a web-based converter. Alternatively, we maintain a partial list of programs that can read/write MRTs, and we provide a complete set of machine-readable table standards. Author created MRTs will be verified at acceptance and may also require “proofing” if significant changes were required to maintain the AAS standards and styles.

MRT Conversion and Proofing

Conversion to the MRT format will be done for all large tables after acceptance but before the manuscript is sent to the publisher for production. The data in a table will be evaluated against best practices for curated, archived data tables, and may be subsequently standardized. Authors will be queried at this point to “proof” the resulting AAS Journal MRT. Please review the full workflow and tips on MRT conversion and proofing.

Data behind the Figure

Our Data behind the Figure program archives the tabular or image data that comprise each figure in an article, and provides it for reuse in common astronomy formats (Machine readable tables or FITS). A few examples of DbF include: 1) the original FITS image that comprise an RGB color figure; 2) original FITS versions of 1-D spectra in a figure; 3) an MRT of the full catalog of sources displayed in a color-color diagram The DbF option makes more structured data available for the longterm and facilitates further use of the data, thus increasing long-term citations of articles. For readers the data that was once difficult to extract from a figure can now be on your desktop with one click. Note that DbF is not appropriate for all data, specifically extremely large data sets (> 100 MB) or data that is already available online (e.g., NASA archives). Presently authors wishing to take advantage of the DbF program should contact AAS Journals Staff Scientists in advance of submitting a manuscript.

Using Repositories

Our complete tutorial for using and citing repositories for data, software, and other research artifacts is available as a collaboratively-edited document on GitHub. The tutorial provides instructions on using and citing repositories and lists those repositories preferred by the AAS Journals.  The following considerations require your close attention when using such repositories:

  1. Ensure that the authorship of the data is complete. The authorship of the data does not need to match the authorship of the manuscript, but it should accurately reflect all contributions to the creation of that data, software or other research artifact;
  2. Ensure that there is sufficient description of the individual files that they may be understood and reused by the wider community;
  3. Ensure that there is a license assigned to the dataset on the repository. We prefer it be an open license such as CC-BY  (for data) or MIT (for software; see also https://choosealicense.com/). To release material in to the public domain the CC0 license for data or the Unlicense for software can be used.
  4. Be prepared to provide multiple versions or releases of your data and software. First, consider that it may change as the product of peer-review between the initial submission of your manuscript and the final published form. Changes to the deposit may also occur because the Data Editor requests additional documentation or file format improvements to the material deposited.

Another useful resource can be found in the appendices to the article, “Best Practices for Data Publication” (Chen et al. 2022, ApJS, doi:10.3847/1538-4365/ac6268) where the most recent version is hosted by NED (doi:10.26132/NED7). These appendices provide another listing of potential archives for your data as well as a list of resources to find DOIs for existing datasets.

Source Code(s)

Authors should review our AAS Journal software and computational notebook policies, which change substantially the recommended practice for including software in your article. Software and notebooks should be published, placed in a persistent archive, and cited in the manuscript to appear in the formal reference list of your final article. We are strongly discouraging the practice of embedding tar or zip archives of code material in the final published article.

If authors insist upon including any of their relevant source code with their article, then the following guidelines on its content, metadata, and licensing should be followed. The code can be written in any language, but extremely long and complex programs with numerous subroutines are not appropriate; again such codes should be published in a persistent repository. Executable files are not accepted.

Authors chosing to submit source codes as a part of their article need to be aware of the following:

  • Codes often change, but the published materials in the journal do not. Authors cannot update their code or fix bugs for codes published in support of their AAS Journal article. However, authors may include a URL in the article to link to updated versions of the code.
  • Source codes that use copyrighted material cannot be published with the copyrighted material included (e.g., a code that uses Numerical Recipes subroutines of Press et al.). In these cases, the author must exclude any copyrighted material and include a statement explaining where and how the missing material can be obtained and implemented into the code.
  • Authors must license their code.

Authors should attach the following metadata header to their source code. The metadata header provides information to the code users to help them compile and use the code. Authors should provide information, when appropriate, for each line of the metadata header given below. The information between the “[ ]”s provides instructions and examples for the author and should be removed before submission.


Title:
Authors:


Code names: [e.g., program.f]

Language: [e.g., Fortran 77]

License: [e.g. MIT License]

Code tested under the following compilers/operating systems: [e.g., gcc/Linux]

Description of input data: [include units and formatting]

Description of output data: [include units]

System requirements: [e.g., minimum floating point precision]

Calls to external routines: [e.g., SIMPLX.F from “Numerical Recipes” by Press et al.1992]

Additional comments: [e.g., Program calculates the minimum of a function]


The AAS gives permission to anyone who wishes to use these subroutines to run their own calculations.
Permission to republish or reuse these routines should be directed to permissions@aas.org.

Note that the AAS does not take responsibility for the content of the source code. Potential users should be wary of applying the code to conditions that the code was not written to model and the accuracy of the code may be affected when compiled and executed on different systems.


 

Tar Archives

As with source codes, the AAS Journals are strongly encouraging authors to place related content in a persistent repository and to link to that material through a DOI link. In the case that authors choose to not use such archives then all of the files can be packaged together and submitted as a UNIX tar file. Again, a metadata header should then be included in the packaged file as a separate file called ReadMe. The format of that ReadMe is as follows:


Title:
Authors:


Description of contents: ## Please replace this with description of the tar package that explains for the reader what types of files are included and how to use them. ##

System requirements: ## Please indicate if the files require any special programs (e.g. IRAF) to be used. ##

Additional comments: ## Please replace this with additional comments or even text from the main paper useful for the reader. ##