Merge pull request #55 from LinkedEarth/pangaea-publications

Improve PANGAEA Publication Extraction Logic

Author: khider

pyleotups/core/PangaeaDataset.py

@@ -540,21 +540,118 @@ def get_publications(
         verbose: bool = False,
     ):
         """
-        Retrieve publication information in BibTeX and DataFrame format.
+        Retrieve publication information for all registered PANGAEA studies.
+
+        This method aggregates publication metadata across all studies currently
+        registered in the dataset. It returns both a structured pandas DataFrame
+        and a BibTeX-compatible ``pybtex.database.BibliographyData`` object.
+
+        Publication extraction is performed at the study level via the internal
+        ``PangaeaStudy._extract_publications()`` method, and results are combined
+        across studies.
+
+        Publication Sources
+        -------------------
+        Publications are collected from three metadata sources within each
+        ``PanDataSet`` object:
+
+        1. **Dataset Citation (Primary Source)**
+        - Extracted directly from ``PanDataSet.citation``.
+        - No external API calls are made for this source.
+        - The citation string is treated as authoritative dataset metadata.
+        - Parsed minimally into:
+            - ``Title`` → full citation string
+            - ``Year`` → extracted using regex
+        - Other structured fields (authors, journal, etc.) may be unavailable.
+        - Assigned:
+            ``Type = "citation"``
+
+        2. **Supplementary Publications**
+        - Extracted from ``PanDataSet.supplement_to["uri"]``.
+        - Represents the publication to which the dataset is a supplement.
+        - If the URI contains a valid DOI, metadata is fetched via Crossref.
+        - Assigned:
+            ``Type = "supplement to"``
+
+        3. **Related Publications**
+        - Extracted from ``PanDataSet.relations``.
+        - Each relation is expected to have:
+            ``{"id", "title", "uri", "type"}``
+        - Only relations with DOI-containing URIs are processed.
+        - Metadata is fetched via Crossref.
+        - Assigned:
+            ``Type = relation["type"]``
+
+        Crossref Integration
+        --------------------
+        For supplement and relation publications, metadata is retrieved using
+        ``doi2bib.crossref.get_bib()`` and parsed via ``bibtexparser``.
+
+        The helper method ``_fetch_publication_from_doi()``:
+        - Normalizes DOI strings
+        - Retrieves BibTeX from Crossref
+        - Parses BibTeX into structured fields
+        - Converts entries into:
+            - Row dictionaries for DataFrame output
+            - ``pybtex.database.Entry`` objects for BibTeX export
+
+        Dataset citations are intentionally excluded from Crossref resolution
+        to avoid inconsistencies and API failures.
+
+        Deduplication
+        -------------
+        Duplicate DOIs across citation, supplement, and relations are removed
+        within each study using a DOI-based uniqueness check.
+
+        Returns
+        -------
+        tuple
+            A tuple containing:
+
+            - ``BibliographyData`` :
+                A pybtex bibliography object containing all publication entries,
+                suitable for BibTeX export.
+
+            - ``pandas.DataFrame`` :
+                Tabular representation of publications with columns:
+
+                - ``Author`` : str or None
+                - ``Title`` : str
+                - ``Journal`` : str or None
+                - ``Year`` : str or None
+                - ``Volume`` : str or None
+                - ``Number`` : str or None
+                - ``Pages`` : str or None
+                - ``Type`` : str
+                    One of {"citation", "supplement to", relation type}
+                - ``DOI`` : str or None
+                - ``URL`` : str or None
 
         Parameters
         ----------
-        save : bool, default=False
-            If True, save BibTeX file.
+        save : bool, optional, default=False
+            If True, saves the BibTeX output to disk.
+
         path : str or None, optional
-            Output path.
-        verbose : bool, default=False
-            Print BibTeX content.
+            Output file path or directory. If a directory is provided, a timestamped
+            filename is generated.
 
-        Returns
-        -------
-        tuple
-            (BibliographyData, pandas.DataFrame)
+        verbose : bool, optional, default=False
+            If True, prints the BibTeX content to stdout.
+
+        Notes
+        -----
+        - The dataset citation is always included, even if supplement or relation
+        publications are present.
+        - Crossref lookups are only performed for supplement and relation DOIs.
+        - Some fields may be missing depending on metadata availability.
+        - BibTeX entry keys are auto-generated and guaranteed to be unique
+        within the returned bibliography.
+
+        See Also
+        --------
+        PangaeaStudy._extract_publications : Study-level publication extraction logic
+        _fetch_publication_from_doi : DOI-based metadata retrieval helper
         """
         all_rows = []
         all_entries = {}

pyleotups/tests/test_PangaeaDataset.py

@@ -243,14 +243,27 @@ def test_get_funding(self, mock_panquery, mock_requests):
         assert isinstance(df_funding, pd.DataFrame)
 
 
+    @patch("doi2bib.crossref.get_bib")
     @patch("pangaeapy.pandataset.requests.get", side_effect=mock_requests_get)
     @patch("pyleotups.core.PangaeaDataset.PanQuery")
-    def test_get_publications(self, mock_panquery, mock_requests):
+    def test_get_publications(self, mock_panquery, mock_requests, mock_crossref):
 
         mock_panquery.return_value.result = [
             {"URI": "10.1594/PANGAEA.830586"}
         ]
 
+        mock_crossref.return_value = (
+            200,
+            """
+            @article{test,
+                author = {Smith, John},
+                title = {Test Paper},
+                journal = {Nature},
+                year = {2020}
+            }
+            """
+        )
+
         ds = PangaeaDataset()
         ds.search_studies(search_text="test")