Journals

When the ads Python package is first installed, a local SQLite database is created that stores the names and abbreviations of journals, as well as curated affiliations. You can access the records from this local database in the same way that you would access a ads.Document or ads.Library.

You will need the following imports in order to execute all code blocks on this page:

from ads import Document, Journal

The ads.Journal object

The ads.Journal data model has only two fields:

ads.Journal.abbreviation

A unique abbreviation string for the journal, which can be up to five characters long.

ads.Journal.title

The full title of the journal.

Selecting journals

You can select a single ads.Journal object with the ads.Journal.get() method, or select multiple records using the ads.Journal.select() method. Here are a few examples:

# Retrieve a single journal based on an exact expression.
mnras = Journal.get(abbreviation="MNRAS")

# Get a single journal, but we don't care which one.
journal = Journal.get()

# List every journal with a title containing "astro" (case-insensitive),
# and sort by reverse abbreviation.
astro_journals = Journal.select()\
                        .where(Journal.title.contains("astro"))\
                        .order_by(Journal.abbreviation.desc())

The ads.Document.journal field

If a document is published (or posted to a pre-print server) then the ads.Document object for that document will have a journal field (ads.Document.journal) that represents the document publisher. For example:

from ads import Document

# Retrieve a specific document.
doc = Document.get(id=12312494)

# See where it was published.
print(f"# {doc.journal} ({type(doc.journal)})")
# ApJ (<Model: Journal>)

# We can see that the type() of doc.journal is a ads.Journal object
# so we can access properties of that object:
print(f"# {doc} published in {doc.journal.abbreviation} - {doc.journal.title}")
# <Document: bibcode=2015ApJ...808...16N> published in ApJ - The Astrophysical Journal

The ads.Document.journal field does not exist on the ADS server. You can’t search for it, and it’s not an attribute that is returned by the ADS server. It is a special foreign key field of the ads.Document data model.

The ads package request the ads.Document.bibcode from ADS with every search (even if you didn’t ask for it, because it is needed for uniquely identifying documents, among other things), parses the journal’s bibliographic abbreviation from the bibcode, and returns an ads.Journal object. When searching for documents, any expression referencing ads.Journal is resolved into a search filter on ads.Document.bibstem. That allows us to access the ads.Document.journal attribute, and to create expressions using that attribute.

That’s why you won’t find the journal field on the NASA ADS API documentation, or on the comphrensive list of operators.

Search for documents by Journal

The primary use for the ads.Journal object is to allow for more complex document searches.

When you use a ads.Journal object as an expression in ads.Document.select().where, the ads.Journal object will be resolved to search for the ads.Document.bibstem of the journal abbreviation. This is done automatically by the interface to the search service, without the need for explicit joins between the ads.Document and ads.Journal data models, even if your query on ads.Journal is complex.

For example, let’s say we wanted to search for documents published in any journal with a title that contains the word ‘gravitation’. First let’s see which journals match this phrase:

for journal in Journal.select().where(Journal.title.contains("gravitation")):
    print(f"# {journal.abbreviation}: {journal.title}")

# GReGr: General Relativity and Gravitation
# GrCo: Gravitation and Cosmology
# JGrPh: Journal of Gravitational Physics
# StHCG: Studies in High Energy Physics Cosmology and Gravitation

If we wanted to search ADS for documents in these journals we would normally have to construct a specific search phrase. But we don’t have to do that, because the ads.Journal and ads.Document data models know about each other, and know how to resolve relationships between each other in any expression. For example, let’s see how this expression is translated:

from ads import Journal
from ads.services.search import SolrQuery

expression = Journal.title.contains("gravitation")

# Translate this expression into a search query for Solr.
print(f"# The Solr query for this expression is:\n# {SolrQuery(expression)}")
# The Solr query for this expression is:
# bibstem:(GReGr OR GrCo OR JGrPh OR StHCG)

Instead we can simply search by any of the ads.Document.journal attributes:

# Search ADS for documents in gravitation journals
docs = Document.select()\
               .where(Document.journal.title.contains("gravitation"))


# Search for ApJ papers
apj = Journal.get(abbreviation="ApJ")
docs = Document.select()\
               .where(Document.journal == apj)
# or
docs = Document.select()\
               .where(Document.journal.abbreviation == "ApJ")
# or
docs = Document.select()\
               .where(Document.journal.title == "The Astrophysical Journal")


# You can use the Document.journal attribute as sub-expressions in any complex query.
# For example: search for (MNRAS papers in 2019) or (ApJ papers in 2018)
docs = Document.select()\
               .where(
                   ((Document.journal.abbreviation == "MNRAS") & (Document.year == 2019))
                   | ((Document.journal == apj) & (Document.year == 2018))
               )

Bibliographic codes

Every document in ADS that appears in a peer-reviewed journal will have a bibliographic code (bibcode) that includes an abbreviation of the journal name. The bibliographic code is a 19 character string and follows the syntax YYYYJJJJJVVVVMPPPPA, where:

  • YYYY: Year of publication

  • JJJJJ: A standard abbreviation for the journal (e.g. ApJ, AJ, MNRAS, Sci, PASP, etc.). A list of abbreviations is available.

  • VVVV: The volume number (for a serial) or an abbreviation that specifies what type of publication it is (e.g. conf for conference proceedings, meet for Meeting proceedings, book for a book, coll for colloquium proceedings, proc for any other type of proceedings).

  • M: Qualifier for publication:

    • E: Electronic Abstract (usually a counter, not a page number)

    • L: Letter

    • P: Pink page

    • Q-Z: Unduplicating character for identical codes

  • PPPP: Page number. Note that for page numbers greater than 9999, the page number is continued in the m column.

  • A: The first letter of the last name of the first author.

You can read more about bibliographic codes here.

Contributions

Simon J. Murphy (University of Sydney) first proposed the idea of accessing the interpreted journal name as an attribute of ads.Document.