Source code for energy_methods.references

"""One citation catalogue for the repository and generated analysis reports.

The thesis inspired the project and its early work. Later additions have their
own sources. A catalogue entry records where a work is used; its presence alone
does not mean a particular run used its data or algorithm. Sources marked as
background are not implementations.
"""

from __future__ import annotations

import json
from collections.abc import Iterable
from dataclasses import asdict, dataclass
from importlib.resources import files
from typing import cast
from urllib.parse import quote

# Retain the public identifier and catalogue order for existing report consumers.
# The thesis provides project context, not a claim of lineage for every method.
PRIMARY_REFERENCE_ID = "ascencio_vasquez_2021_thesis"


[docs] @dataclass(frozen=True, slots=True) class Reference: """Verified bibliographic metadata, with a transparent implementation role.""" id: str title: str authors: tuple[str, ...] year: int | None doi: str | None url: str kind: str role: str used_by: tuple[str, ...] note: str publication: str = "" volume: str = "" issue: str = "" pages: str = "" institution: str = "" verified_at: str = "2026-10-29" @property def key(self) -> str: """BibTeX/citation key; identical to the stable catalogue ID.""" return self.id
[docs] def as_dict(self) -> dict[str, object]: """Return independent JSON-serializable metadata for a report manifest.""" return asdict(self)
def _load() -> tuple[Reference, ...]: raw = json.loads(files("energy_methods").joinpath("references.json").read_text("utf-8")) return tuple( Reference( id=str(item["id"]), title=str(item["title"]), authors=tuple(item["authors"]), year=cast(int | None, item["year"]), doi=cast(str | None, item["doi"]), url=str(item["url"]), kind=str(item["kind"]), role=str(item["role"]), used_by=tuple(item["used_by"]), note=str(item["note"]), publication=str(item.get("publication", "")), volume=str(item.get("volume", "")), issue=str(item.get("issue", "")), pages=str(item.get("pages", "")), institution=str(item.get("institution", "")), verified_at=str(item["verified_at"]), ) for item in raw ) REFERENCES = _load()
[docs] def get_references(ids: Iterable[str] | None = None) -> tuple[Reference, ...]: """Select known IDs, retaining the thesis first as project context. Unknown IDs fail instead of silently losing attribution. The full catalogue includes optional-source and background entries; consult ``role`` and ``note`` before describing a source as used by an individual analysis run. """ if ids is None: return REFERENCES requested = set(ids) known = {reference.id for reference in REFERENCES} if missing := requested - known: raise ValueError(f"Unknown reference IDs: {', '.join(sorted(missing))}") requested.add(PRIMARY_REFERENCE_ID) return tuple(reference for reference in REFERENCES if reference.id in requested)
[docs] def references_markdown(ids: Iterable[str] | None = None) -> str: """Render complete citations and their use without fetching external content.""" sections = [] for reference in get_references(ids): year = str(reference.year) if reference.year is not None else "n.d." citation = f"{'; '.join(reference.authors)} ({year}). **{reference.title}**." if reference.publication: citation += f" {reference.publication}" if reference.volume: citation += f", {reference.volume}" if reference.issue: citation += f"({reference.issue})" if reference.pages: citation += f", {reference.pages}" citation += "." if reference.institution: citation += f" {reference.institution}." locator = ( f"[DOI: {reference.doi}](https://doi.org/{quote(reference.doi, safe='/')})" if reference.doi else f"[Source]({reference.url})" ) sections.append( f"### {reference.id}\n\n{citation} {locator}\n\n" f"**Role:** {reference.role}. {reference.note}\n\n" f"**Used by:** {', '.join(f'`{path}`' for path in reference.used_by)}.\n" ) return "\n".join(sections)
def _bibtex_escape(value: str) -> str: return value.replace("&", r"\&").replace("%", r"\%").replace("_", r"\_")
[docs] def references_bibtex(ids: Iterable[str] | None = None) -> str: """Render UTF-8 BibTeX; unknown identifiers and DOIs are never invented.""" kinds = { "thesis": "phdthesis", "article": "article", "conference-paper": "inproceedings", "report": "techreport", } entries = [] for reference in get_references(ids): kind = kinds.get(reference.kind, "misc") authors = " and ".join( _bibtex_escape(author) if "," in author else "{" + _bibtex_escape(author) + "}" for author in reference.authors ) fields = {"author": authors, "title": "{" + _bibtex_escape(reference.title) + "}"} if reference.year is not None: fields["year"] = str(reference.year) if reference.publication: field = { "article": "journal", "inproceedings": "booktitle", "techreport": "number", }.get(kind, "howpublished") fields[field] = _bibtex_escape(reference.publication) for field, value in ( ("volume", reference.volume), ("number", reference.issue), ("pages", reference.pages.replace("-", "--")), ("school" if kind == "phdthesis" else "institution", reference.institution), ("doi", reference.doi), ("url", reference.url), ): if value: fields[field] = value fields["note"] = _bibtex_escape(f"Role: {reference.role}. {reference.note}") body = ",\n".join(f" {key} = {{{value}}}" for key, value in fields.items()) entries.append(f"@{kind}{{{reference.id},\n{body}\n}}\n") return "\n".join(entries)
def _cff_reference(reference: Reference) -> dict[str, object]: authors: list[dict[str, str]] = [] for author in reference.authors: if "," in author: family, given = author.split(",", 1) authors.append({"family-names": family.strip(), "given-names": given.strip()}) else: authors.append({"name": author}) result: dict[str, object] = { "type": reference.kind, "title": reference.title, "authors": authors, "url": reference.url, "notes": f"Role: {reference.role}. {reference.note}", } if reference.year is not None: result["year"] = reference.year if reference.doi: result["doi"] = reference.doi if reference.publication: result["journal" if reference.kind == "article" else "collection-title"] = ( reference.publication ) for key, value in (("volume", reference.volume), ("issue", reference.issue)): if value: result[key] = value if reference.institution: result["institution"] = {"name": reference.institution} if reference.kind == "thesis": result["thesis-type"] = "Doctoral dissertation" return result
[docs] def citation_cff() -> dict[str, object]: """Build software citation metadata with all scientific sources retained.""" return { "cff-version": "1.2.0", "message": ( "Please cite this software using the repository URL and exact commit, " "plus the method, software and data references actually used. Cite " "Julián Andrés Ascencio Vásquez's doctoral thesis for work derived from it; " "it inspired the project and its early studies, while later additions " "have their own scientific sources." ), "title": "energy-data-insights", "type": "software", "authors": [{"name": "energy-data-insights contributors"}], "repository-code": "https://github.com/julianascencio/energy-data-insights", "references": [_cff_reference(reference) for reference in REFERENCES], }