Skip to content

sxs.cite#

For reasons of reproducibility — and for general academic integrity — it is important to cite the specific packages and data you use in your research. In particular, it is absolutely vital to cite the specific version of the catalog of SXS simulations you use, as well as the version of this sxs package that you use. The sxs.cite function provides those specific citations.

Cite this package and/or data

Prints out a citation for this package, the most recent paper describing the catalog, the catalog data itself, and optionally individual simulations.

Note that this function makes web requests to obtain the DOIs and corresponding BibTeX entries.

If you want to cite a specific version of the SXS catalog data, be sure to load it with sxs.load("dataframe", tag="v3.0.0") or similar before calling this function. Otherwise, the most recent version will be used.

Parameters:

Name Type Description Default
sxs_ids str

Any number of SXS IDs to include in the citation.

 ()
bibtex bool

If True — the default — returns full BibTeX entries. Otherwise, just returns a list of DOIs to cite.

 True

Returns:

Type Description
str or list[str]

A string containing BibTeX entries, or a list of DOI strings.
Source code in sxs/citation.py 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def cite(*sxs_ids, bibtex=True):
    """Cite this package and/or data

    Prints out a citation for this package, the most recent paper
    describing the catalog, the catalog data itself, and optionally
    individual simulations.

    Note that this function makes web requests to obtain the DOIs and
    corresponding BibTeX entries.

    If you want to cite a specific version of the SXS catalog data, be
    sure to load it with `sxs.load("dataframe", tag="v3.0.0")` or
    similar *before* calling this function.  Otherwise, the most recent
    version will be used.

    Parameters
    ----------
    sxs_ids : str
        Any number of SXS IDs to include in the citation.
    bibtex : bool, optional
        If True — the default — returns full BibTeX entries.
        Otherwise, just returns a list of DOIs to cite.

    Returns
    -------
    str or list[str]
        A string containing BibTeX entries, or a list of DOI strings.

    """
    from . import doi_prefix, load, __version__
    from . import sxs_id as sxs_identifier

    if len(sxs_ids) == 1 and isinstance(sxs_ids[0], (list, tuple)):
        sxs_ids = tuple(sxs_ids[0])

    simulations = load("simulations")

    # Get the DOI for this version of this package
    package_version = f"v{__version__}"
    package_doi = get_zenodo_doi("The sxs package", package_version)

    # Get the DOI for the paper
    paper_doi = f"{doi_prefix}/SXSCatalog3"

    # Get the DOI for this version of the catalog
    catalog_tag = getattr(simulations, "tag", "v3.0.0")
    catalog_doi = get_zenodo_doi(
        "The SXS catalog of simulations",
        catalog_tag
    )

    sxs_id_references = {
        doi
        for sxs_id in sxs_ids
        for doi in simulations[sxs_identifier(sxs_id)].get("citation_dois", [])
        if doi.startswith("10.")
    } - {package_doi, paper_doi, catalog_doi}

    if bibtex:
        package_bibtex = doi2bibtex(package_doi, key=f"SXSPackage_{package_version}")
        paper_bibtex = doi2bibtex(paper_doi, key="SXSCatalogPaper_3")
        catalog_bibtex = doi2bibtex(
            catalog_doi,
            key=f"SXSCatalogData_{catalog_tag[1:]}",
            title_suffix=f" {catalog_tag}"
        )
        sxs_id_references_bibtex = [
            doi2bibtex(doi) for doi in sxs_id_references
        ]
        sxs_id_bibtex = [
            doi2bibtex(f"{doi_prefix}/{sxs_id}", key=sxs_id)
            for sxs_id in sxs_ids
        ]
        return "\n".join(
            [package_bibtex, paper_bibtex, catalog_bibtex]
            + sxs_id_references_bibtex
            + sxs_id_bibtex
        )
    else:
        sxs_id_references_dois = list(sxs_id_references)
        sxs_id_dois = [f"{doi_prefix}/{sxs_id}" for sxs_id in sxs_ids]
        return [package_doi, paper_doi, catalog_doi] + sxs_id_references_dois + sxs_id_dois