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', root_only=False)

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

The filename follows the pattern {author}_{year}_{suffix}, where suffix starts at "a" and increments through "b", "c", …, "z", "aa", "ab", and so on — supporting an unlimited number of collisions via variable-length base-26 suffixes.

If library_folder is provided and exists, the directory is scanned for files matching {author}_{year}_*.{extension}. By default the scan is recursive (all subfolders included); set root_only=True to restrict the search to the top-level folder only. The highest existing suffix (ordered by length first, then alphabetically) is identified and incremented to produce the next unique name. If no matching files are found, the suffix defaults to "a".

The table below illustrates the filename suffix sequence:

Filename	Entry index
Smith_2020_a	1st
Smith_2020_b	2nd
Smith_2020_z	26th
Smith_2020_aa	27th
Smith_2020_az	52nd
Smith_2020_ba	53rd
Smith_2020_aaa	703rd

Parameters:

• library_folder (str or pathlib.Path, optional) – Directory to scan for existing files when determining the next suffix. If None or the path does not exist, the suffix defaults to "a".

• extension (str) – File extension used when globbing for existing filename collisions. Defaults to "md".

• root_only (bool) – If True, restricts the search to the top-level of library_folder, ignoring subfolders. Defaults to False (recursive scan).

Returns:

The generated filename string in the format {author}_{year}_{suffix}, without a file extension.

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}