Adding a Reference

A reference is a python (sub)module, and it can provide arbitrary data and functions. The only requirements are the bibliographic information.

Bibliographic Information

Each reference must emit a one-line logging info line the first time results from the reference are used. The logger must emit a full bibtex entry as a debug message the first time results from the reference are used.

This can be easy if you use

class tdg.references.citation.Citation(short, bibtex)[source]

A Citation is a collection bunch of bibliographic information.

On each call log the short name and a message if the message hasn’t been logged before; the first time it is called log the bibtex entry.

Parameters

short (string) – A plain-text rendering of the citation.
bibtex (string) – A bibtex key or complete bibtex entry that could be used to cite the reference. The key will be looked up in tdg’s master bibtex file.

__call__(message='')[source]: Call self as a function.

In your reference you can do

from tdg.references.citation import Citation
citation = Citation(
    'AUTHOR et al., JOURNAL ETC. (YEAR)',
    '''@article{bibtex,
        title={TITLE},
        author={AUTHOR},
        journal={JOURNAL},
        volume={VOL},
        number={N},
        pages={100-200},
        year={YEAR},
        publisher={PUBLISHER}
    }''')

# ... and then inside a piece of code that, if it's running, the authors deserve a citation:
citation()

Rather than the full bibtex entry you can pass the key of the reference in the master.bib. Each reference should set the label argument in each plot.

Results and Plotting

The tdg.references module provides some convenience functions such as contact_comparison() and energy_comparison(). To automatically include the results from a custom reference in the figure, you should provide a function with the same name and the signature (ax, **kwargs). If your module is included in the references contact_comparison() will call it, forwarding the axis and any kwargs it was given. For example,

tdg.references.PRA107043314.contact_comparison(ax, *, alpha, cutoff_variation=0.05, **kwargs)[source]

Plots contact_by_kF4() as a function of alpha.

Error bars are produced by varying the cutoff; see Ref. [1] Fig. 12.

requires the user to pass an alpha parameter to contact_comparison() and optionally understands the cutoff_variation.

Some references have data that has been superseded by works from the same author, or are far outside the typical parameter range. The convention in this case is to only plot if the kwarg include_all=True. (For an example see PRL106110403.)

But other references might only provide data points, or information about the critical temperature.