Bibliography Tracking Module (sbpy.bib)

Introduction

sbpy classes and functions can automatically report citations to the user through a bibliography registry. The idea behind this service is to make it easier to properly acknowledge and reference those who designed methods and tools used.

ADS query requirements

The ads module is required for bib to transform bibcodes into readable citations. As stated in the documentation:

1. You’ll need an API key from NASA ADS labs. Get an ADS account, visit account settings and generate a new API token.

2. When you get your API key, save it to a file called ~/.ads/dev_key or save it as an environment variable named ADS_DEV_KEY.

3. Install the ads python module, e.g., if using pip: pip install ads.

How to use bib

Use track() to enable citation tracking. Every method called after activating the tracking will register any relevant citations. Each citation is associated with a tag that enables the user to identify which aspect of the method the citation is relevant to:

>>> from sbpy import bib, data
>>> bib.track()
>>> eph = data.Ephem.from_horizons('433')    
>>> print(bib.to_text())                     
sbpy.data.Ephem.from_horizons:
  data source:
      Giorgini, Yeomans, Chamberlin et al. 1996, AAS/Division for Planetary Sciences Meeting Abstracts #28, 25.04

In this case, Giorgini et al. 1996, 1996DPS....28.2504G describes the JPL Horizons data service that is queried by from_horizons(). to_text outputs the current citation registry in simple text form.

To disable tracking, use stop():

>>> bib.stop()

To clear any previous citations:

>>> bib.reset()

Bibliography tracking can also be used in a context manager:

>>> from sbpy import bib, data
>>> with bib.Tracking(bib.to_text):
...     eph = data.Ephem.from_horizons('Ceres')    
sbpy.data.Ephem.from_horizons:
  data source:
      Giorgini, Yeomans, Chamberlin et al. 1996, AAS/Division for Planetary Sciences Meeting Abstracts #28, 25.04

Automatic reporting

If tracking is enabled when Python exits, the bibliography will be automatically reported. ipython users can enable tracking at startup so that no citations are left behind. For example, add the following to a startup script, such as ~/.ipython/profile_default/startup/99-user.py:

import sbpy.bib
sbpy.bib.track()

Output formats

Bibliographies can be generated in different output formats:

Unformatted (show)

>>> bib.show() 
sbpy.data.Ephem.from_horizons:
  data source:
    1996DPS....28.2504G

Simple text (to_text)

>>> bib.to_text() 
sbpy.data.Ephem.from_horizons:
  data source:
      Giorgini, Yeomans, Chamberlin et al. 1996, AAS/Division for Planetary Sciences Meeting Abstracts #28, 25.04

BibTeX (to_bibtex)

>>> bib.to_bibtex() 
% sbpy.data.Ephem.from_horizons/data source:
@INPROCEEDINGS{1996DPS....28.2504G,
       author = {{Giorgini}, J.~D. and {Yeomans}, D.~K. and {Chamberlin}, A.~B. and
        {Chodas}, P.~W. and {Jacobson}, R.~A. and {Keesey}, M.~S. and
        {Lieske}, J.~H. and {Ostro}, S.~J. and {Standish}, E.~M. and
        {Wimberly}, R.~N.},
        title = "{JPL's On-Line Solar System Data Service}",
    booktitle = {AAS/Division for Planetary Sciences Meeting Abstracts \#28},
         year = 1996,
        month = Sep,
          eid = {25.04},
        pages = {25.04},
       adsurl = {https://ui.adsabs.harvard.edu/abs/1996DPS....28.2504G},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

AASTeX (to_aastex)

>>> bib.to_aastex() 
% sbpy.data.Ephem.from_horizons/data source:
\bibitem[Giorgini et al.(1996)]{1996DPS....28.2504G} Giorgini, J.~D.,
Yeomans, D.~K., Chamberlin, A.~B., et al.\ 1996, AAS/Division for
Planetary Sciences Meeting Abstracts \#28 , 25.04.

Icarus (to_icarus)

>>> bib.to_icarus() 
% sbpy.data.Ephem.from_horizons/data source:
\bibitem[Giorgini et al.(1996)]{1996DPS....28.2504G} Giorgini, J.~D.,
and 9 colleagues 1996.\ JPL's On-Line Solar System Data Service.\
AAS/Division for Planetary Sciences Meeting Abstracts \#28 25.04.

MNRAS (to_mnras)

>>> bib.to_mnras() 
% sbpy.data.Ephem.from_horizons/data source:
\bibitem[\protect\citeauthoryear{Giorgini, et al.}{1996}]{1996DPS....28.2504G}
Giorgini J.~D., et al., 1996, AAS/Division for Planetary Sciences
Meeting Abstracts \#28, 25.04

Please note that the NASA ADS API is still experimental and suffers from hickups. Queries might fail, leading to warnings. If you perform a query, please check if there are any warning messages included. If so, please re-try the query until it is successful.

Other bibliography styles, for instance in accordance to specific journal rules, can be readily implemented.

Filtering

The aforementioned output functions enable the filtering of references based on their relevance. For instance, in the examples show above, the relevance is data source. In order to properly use filter, only select keywords can be used a relevance: allowed is any string that must start with either of the following words: 'method' (acknowledge the original author of the method), 'data source' (acknowledge a service or publication providing data), 'software' (acknowledge existing software that was used), or 'parameter' (acknowledge specific parameter choices).

For instance, to create a list of software packages that were used, you can select only citations that are relevant to software by using:

>>> bib.to_aastex(filter='software')  

This list can be readily used in your publication to cite software packages that were used as part of session.

Reference/API

sbpy Bibliography Tracking Module

sbpy classes and functions can automatically report citations to the user through a bibliography registry.

Functions

cite(citations)	Decorator that registers citations within sbpy.
register(task, citations)	Register a citation with the sbpy bibliography tracker.
reset()	Reset sbpy bibliography tracking.
show([filter])	Show current bibliography.
status()	Report sbpy bibliography tracking status.
stop()	Disable sbpy bibliography tracking.
to_aastex([filter])	Convert bibliography to AASTeX format.
to_bibtex([filter])	Convert bibliography to BibTeX format.
to_icarus([filter])	Convert bibliography to Icarus LATeX format.
to_mnras([filter])	Convert bibliography to MNRAS LATeX format.
to_text([filter])	Convert bibcodes to human readable text.
track()	Enable sbpy bibliography tracking.

Classes

Tracking([reporter])

Class Inheritance Diagram