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 `~sbpy.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 `~sbpy.bib`
----------------------
Use `~sbpy.bib.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') # doctest: +SKIP
>>> print(bib.to_text()) # doctest: +SKIP
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 :func:`~sbpy.data.Ephem.from_horizons`. `~sbpy.bib.to_text` outputs the current citation registry in simple text form.
To disable tracking, use `~sbpy.bib.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') # doctest: +SKIP
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``:
.. code-block:: python
import sbpy.bib
sbpy.bib.track()
Output formats
--------------
Bibliographies can be generated in different output formats:
Unformatted (`~sbpy.bib.show`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>> bib.show() # doctest: +SKIP
sbpy.data.Ephem.from_horizons:
data source:
1996DPS....28.2504G
Simple text (`~sbpy.bib.to_text`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>> bib.to_text() # doctest: +SKIP
sbpy.data.Ephem.from_horizons:
data source:
Giorgini, Yeomans, Chamberlin et al. 1996, AAS/Division for Planetary Sciences Meeting Abstracts #28, 25.04
BibTeX (`~sbpy.bib.to_bibtex`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>> bib.to_bibtex() # doctest: +SKIP
% 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 (`~sbpy.bib.to_aastex`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>> bib.to_aastex() # doctest: +SKIP
% 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 (`~sbpy.bib.to_icarus`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>> bib.to_icarus() # doctest: +SKIP
% 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 (`~sbpy.bib.to_mnras`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>> bib.to_mnras() # doctest: +SKIP
% 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') # doctest: +SKIP
This list can be readily used in your publication to cite software
packages that were used as part of session.
Reference/API
-------------
.. automodapi:: sbpy.bib
:no-heading: