losalamos.references

Reference management utilities for bibliographic metadata.

This module defines a schema-driven Reference base class and a registry of entry-type subclasses (e.g., article, book, thesis). It provides tools for loading, standardizing, formatting, and exporting references, including BibTeX parsing, citation generation, and metadata templates.

Quick start

This section demonstrates a few common operations with the reference system.

Load a reference from a BibTeX file

from losalamos.references import Reference

ref = Reference.get_by_entry("article")
ref.load_data("path/to/file.bib")

print(ref.data)

Generate an in-text citation

citation = Reference.cite_line(ref.data)

print(citation)
# Example: "Smith et al. (2022)"

Generate a formatted bibliography entry

bibli = Reference.cite_bibli(
    ref.data,
    style="apa",
    text_format="plain",
)

print(bibli)

Export a BibTeX entry

ref.save()  # saves to the same file path used in load_data

Create a new reference manually

from losalamos.references import RefArticle

ref = RefArticle()

ref.setup_data({
    "name": "smith2022",
    "author": "Smith, John and Doe, Jane",
    "title": "Example Article",
    "year": "2022",
    "journal": "Journal of Examples",
    "volume": "10",
    "issue": "2",
    "pages": "100-110",
    "doi": "10.1000/example"
})

print(ref.get_str_bib())

Generate a BibTeX template

from losalamos.references import RefArticle

ref = RefArticle()
ref.export_template("path/to/file.bib")

Classes

RefArticle([name, alias])
RefBook([name, alias])
RefDataset([name, alias])
RefInbook([name, alias])
RefInproceedings([name, alias])
RefLegislation([name, alias])
RefMisc([name, alias])
RefOnline([name, alias])
RefSoftware([name, alias])
RefTechreport([name, alias])
RefThesis([name, alias])
Reference([name, alias])

class losalamos.references.Reference(name='MyReference', alias='Ref')

Bases: DataSet

ENTRY_TYPE = None

CORE_FIELDS = {'abstract': None, 'author': None, 'doi': None, 'entry_type': None, 'name': None, 'pdf': None, 'title': None, 'url': None, 'year': None}

SPECIFIC_FIELDS = None

TAIL_ENTRIES = ['abstract', 'pdf']

FORMAT_RULES = {'html': {'journal': '<b>{text}</b>', 'title': '<i>{text}</i>'}, 'md': {'journal': '**{text}**', 'title': '*{text}*'}, 'plain': {'journal': '{text}', 'title': '{text}'}, 'tex': {'journal': '\\textbf{{{text}}}', 'title': '\\textit{{{text}}}'}}

CITATION_TEMPLATES = {'abnt': '{authors}. {title}. {year}.', 'apa': '{authors} ({year}). {title}.', 'chicago': '{authors}. {title}. {year}.', 'harvard': '{authors} ({year}) {title}.', 'mla': '{authors}. {title}. {year}.', 'vancouver': '{authors}. {title}. {year}.'}

classmethod get_by_entry(entry_type: str, **kwargs)

Instantiates and returns a reference object based on the provided entry type from the registry.

Parameters:

entry_type (str) – The key representing the type of entry to retrieve.

Returns:

An instance of the requested entry class, or a RefMisc instance if the type is not found.

Return type:

Reference

load_data(file_data)

Loads and parses bibliography data from a specified file path into the instance.

Parameters:

file_data (str | pathlib.Path) – The file path or name containing the data to be loaded.

Returns:

No value is returned.

Return type:

None

setup_data(data)

Initializes the instance data by creating a copy of the input and applying standardization.

Parameters:

data (dict | pandas.Series) – The raw dictionary or object containing reference metadata.

Returns:

No value is returned.

Return type:

None

save()

Saves the current reference data to the file path defined in file_data using the appropriate format.

Returns:

No value is returned.

Return type:

None

to_bib(output)

Generates a bib file from the current item’s data and saves it to the specified output.

Parameters:

output (str or Path) – file Path to output

Returns:

The path to the saved bib file.

Return type:

Path

get_clean_data()

Returns a copy of the internal data dictionary excluding all keys with None values.

Returns:

A filtered dictionary containing only non-null reference data.

Return type:

dict

define_file_name(library_folder=None, extension='md')

Generates a unique filename based on author, year, and an alphabetic suffix to avoid collisions.

Note

This method extracts the primary author and year from the citation metadata to form a base filename. If a library_folder is provided and accessible, it scans the directory for existing files matching the {author}_{year}_* pattern, identifies the highest alphabetic suffix used (e.g., a, b, c), and increments it to ensure the new filename is unique.

Parameters:

• library_folder (str | pathlib.Path) – [optional] The directory path to check for existing files to determine the next suffix.

• extension (str) – The file extension to use when searching for existing patterns. Default value = md

Returns:

The generated filename string in the format {author}_{year}_{suffix}.

Return type:

str

get_str_bib()

Converts the dictionary representation of a BibTeX entry into a string.

Returns:

The BibTeX entry as a formatted string.

Return type:

str

standardize()

Standardizes the internal data dictionary by enforcing schema fields, ordering, and formatting rules.

Note

This method reconstructs the data attribute by merging CORE_FIELDS and SPECIFIC_FIELDS. It ensures all expected keys exist (defaulting to None), reorders specific metadata to the end of the dictionary based on TAIL_ENTRIES, and applies specific formatting logic to the abstract and author fields via harmonize_abstract and standardize_author.

Returns:

No value is returned.

Return type:

None

harmonize_abstract()

Ensures the abstract field is properly formatted by escaping LaTeX-specific percent symbols.

Returns:

No value is returned.

Return type:

None

export_template(output)

Generates an empty metadata template file based on the current class schema and exports it.

Note

This method temporarily replaces the instance data with a skeleton derived from CORE_FIELDS and SPECIFIC_FIELDS. It runs the standardize routine to ensure correct field ordering, clears all values except the entry type, and calls to_bib to write the template to the specified output path before restoring the original data state.

Parameters:

output (str | pathlib.Path | file-like object) – The file path or buffer where the template should be saved.

Returns:

No value is returned.

Return type:

None

static parse_bib(file_parse)

Parse a bib file and return a list of references as dictionaries.

Parameters:

file_parse – Path to the bib file.

Returns:

A list of dictionaries, each representing a BibTeX bib_dict.

static cite_line(bib_dict, text_format='plain', embed_link=False)

Format a dictionary of bibliometric parameters into an in-line citation string with optional DOI or URL links.

static cite_bibli(bib_dict, style='apa', text_format='plain')

Generate a formatted bibliographic citation string based on a dictionary of metadata and a specified style.

Parameters:

• bib_dict (dict) – Dictionary containing bibliographic fields such as author, year, title, and entry_type.

• style (str) – The citation style to use (e.g., apa). Default value = apa

• text_format (str) – The markup format for the output string (e.g., plain, html, or latex). Default value = plain

Returns:

A cleaned, single-line citation string.

Return type:

str

Note

Processing Logic

The function normalizes input dictionary values, handles author list formatting (splitting by and), and applies text formatting rules (e.g., italics or bold) based on the text_format. It then maps to a specific template defined in self.CITATION_TEMPLATES.

Warning

If the provided entry_type or style is not found in the internal templates, it defaults to the article type in apa style.

static standardize_author(bib_dict)

Standardizes the author field in a BibTeX entry.

Parameters:

bib_dict (dict) – The dictionary containing the BibTeX entry data, expected to have an author field.

Returns:

A formatted string of standardized author names.

Return type:

str

class losalamos.references.RefArticle(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'article'

SPECIFIC_FIELDS = {'issn': None, 'issue': None, 'journal': None, 'month': None, 'number': None, 'pages': None, 'volume': None}

CITATION_TEMPLATES = {'abnt': '{authors}. {title}. {journal}, {volume} ({issue}), p. {pages}, {year}. {doi}', 'apa': '{authors} ({year}). {title}. {journal}, {volume_issue}{pages}. {doi}', 'chicago': '{authors}. {raw_title}. {journal} {volume}, no. {issue} ({year}): {pages}. {doi}', 'harvard': '{authors} ({year}) {raw_title}, {journal}, vol. {volume}, no. {issue}, pp. {pages}. {doi}', 'mla': '{authors}. {raw_title}. {journal} {volume}. {issue} ({year}): {pages}. {doi}', 'vancouver': '{authors}. {title}. {journal}. {year}; {volume} ({issue}):{pages}. {doi}'}

load_data(file_data)

Loads and parses bibliography data from a specified file path into the instance.

Parameters:

file_data (str | pathlib.Path) – The file path or name containing the data to be loaded.

Returns:

No value is returned.

Return type:

None

harmonize_issue()

class losalamos.references.RefBook(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'book'

SPECIFIC_FIELDS = {'edition': None, 'isbn': None, 'publisher': None, 'subtitle': None}

CITATION_TEMPLATES = {'abnt': '{authors}. {title}. {publisher}, {year}.', 'apa': '{authors} ({year}). {title}. {publisher}.', 'chicago': '{authors}. {title}. {location}: {publisher}, {year}.', 'harvard': '{authors} ({year}) {title}, {publisher}.', 'mla': '{authors}. {title}. {publisher}, {year}.', 'vancouver': '{authors}. {title}. {publisher}; {year}.'}

class losalamos.references.RefTechreport(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'techreport'

SPECIFIC_FIELDS = {'institution': None, 'language': None, 'location': None, 'note': None, 'subtitle': None, 'version': None}

class losalamos.references.RefThesis(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'thesis'

SPECIFIC_FIELDS = {'institution': None, 'language': None, 'location': None, 'note': None, 'type': None}

class losalamos.references.RefDataset(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'dataset'

SPECIFIC_FIELDS = {'note': None, 'organization': None, 'version': None}

CITATION_TEMPLATES = {'abnt': '{authors}. {title}. {year}. {organization}. {version} [Data Set] {url}.', 'apa': '{authors} ({year}). {title}. {organization}. {version} [Data Set] {url}.', 'chicago': '{authors}. {title}. {year}. {organization}. {version} [Data Set] {url}.', 'harvard': '{authors} ({year}) {title}. {organization}. {version} [Data Set] {url}.', 'mla': '{authors}. {title}. {year}. {organization}. {version} [Data Set] {url}.', 'vancouver': '{authors}. {title}. {year}.  {organization}. {version} [Data Set] {url}.'}

class losalamos.references.RefInproceedings(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'inproceedings'

SPECIFIC_FIELDS = {'booktitle:': None, 'isbn': None, 'location': None, 'organization': None}

class losalamos.references.RefInbook(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'inbook'

SPECIFIC_FIELDS = {'booktitle:': None, 'chapter': None, 'edition': None, 'isbn': None, 'publisher': None, 'subtitle': None}

CITATION_TEMPLATES = {'abnt': '{authors}. {title}. {note}, {year}.', 'apa': '{authors} ({year}). {title}. {note}. {url}.', 'chicago': '{authors}. {title}. {note}, {year}.', 'harvard': '{authors} ({year}) {title}, {note}.', 'mla': '{authors}. {title}. {note}, {year}.', 'vancouver': '{authors}. {title}. {note}; {year}.'}

class losalamos.references.RefMisc(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'misc'

SPECIFIC_FIELDS = {'howpublished': None, 'note': None, 'organization': None}

class losalamos.references.RefOnline(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'online'

SPECIFIC_FIELDS = {'howpublished': None, 'note': None, 'organization': None}

class losalamos.references.RefSoftware(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'software'

SPECIFIC_FIELDS = {'howpublished': None, 'note': None, 'organization': None}

class losalamos.references.RefLegislation(name='MyReference', alias='Ref')

Bases: Reference

ENTRY_TYPE = 'legislation'

SPECIFIC_FIELDS = {'howpublished': None, 'note': None, 'organization': None}