scival publication lookup added

Author: mpanday-deakin

docs/reference/PublicationLookup.rst

@@ -0,0 +1,92 @@
+pybliometrics.scival.PublicationLookup
+======================================
+
+`PublicationLookup()` implements the `Scival Publication Lookup API <https://dev.elsevier.com/documentation/SciValPublicationAPI.wadl>`_.
+
+It accepts any identifier as the main argument which is Scopus ID (the last part of the EID).
+
+.. currentmodule:: pybliometrics.scival
+.. contents:: Table of Contents
+    :local:
+
+Documentation
+-------------
+
+.. autoclass:: PublicationLookup
+   :members:
+   :inherited-members:
+
+Examples
+--------
+You initialize the class with an ID that Scopus uses, e.g. the ID:
+
+.. code-block:: python
+
+    >>> import pybliometrics
+    >>> from pybliometrics.scival import PublicationLookup
+    >>> pybliometrics.scival.init()
+    >>> pub = PublicationLookup(85036568406)
+
+
+You can obtain basic information just by printing the object:
+
+.. code-block:: python
+
+    >>> print(pub)
+    - ID: 85036568406
+    - Title: Soft Electrochemical Probes for Mapping the Distribution of Biomarkers and Injected Nanomaterials in Animal and Human Tissues
+    - DOI: 10.1002/anie.201709271
+    - Type: Article
+    - Year: 2017
+    - Citation Count: 34
+    - Source Title: Angewandte Chemie - International Edition
+    - Topic ID: 7563
+    - Topic Cluster ID: 157
+    - Link: https://api.elsevier.com/analytics/scival/publication/85036568406?view=&apiKey=&httpAccept=application/json&insttoken=
+    - Authors: Lin, T.-E., Lu, Y.-J., Sun, C.-L., Pick, H., Chen, J.-P., Lesch, A., Girault, H.H.
+    - Institutions: Chang Gung University, Swiss Federal Institute of Technology Lausanne, Chang Gung Memorial Hospital
+    - SDGs: SDG 3: Good Health and Well-being
+
+
+You can access different attributes of the publication
+
+.. code-block:: python
+
+    >>> pub.id
+    '85036568406'
+    >>> pub.type
+    'Article'
+    >>> pub.title
+    'Soft Electrochemical Probes for Mapping the Distribution of Biomarkers and Injected Nanomaterials in Animal and Human Tissues'
+    >>> pub.doi
+    '10.1002/anie.201709271'
+    >>> pub.publication_year
+    2017
+    >>> pub.citation_count
+    34
+    >>> pub.source_title
+    'Angewandte Chemie - International Edition'
+
+
+The attributes `authors`, `institutions` and `sdgs` offer insights into the document's content:
+
+.. code-block:: python
+
+    >>> pub.authors
+    [Author(id=7404861905, name='Lin, T.-E.', link='https://api.elsevier.com/analytics/scival/author/7404861905'),
+    Author(id=24537666700, name='Lu, Y.-J.', link='https://api.elsevier.com/analytics/scival/author/24537666700'),
+    Author(id=7404248170, name='Sun, C.-L.', link='https://api.elsevier.com/analytics/scival/author/7404248170'),
+    Author(id=7004202515, name='Pick, H.', link='https://api.elsevier.com/analytics/scival/author/7004202515'),
+    Author(id=58307174900, name='Chen, J.-P.', link='https://api.elsevier.com/analytics/scival/author/58307174900'),
+    Author(id=36246291500, name='Lesch, A.', link='https://api.elsevier.com/analytics/scival/author/36246291500'),
+    Author(id=7102360867, name='Girault, H.H.', link='https://api.elsevier.com/analytics/scival/author/7102360867')]
+
+    >>> pub.institutions
+    [Institution(id=217002, name='Chang Gung University', country='Taiwan', country_code='TWN', link='https://api.elsevier.com/analytics/scival/institution/217002'),
+    Institution(id=306002, name='Swiss Federal Institute of Technology Lausanne', country='Switzerland', country_code='CHE', link='https://api.elsevier.com/analytics/scival/institution/306002'), Institution(id=725104, name='Chang Gung Memorial Hospital', country='Taiwan', country_code='TWN', link='https://api.elsevier.com/analytics/scival/institution/725104')]
+
+    >>> pub.sdgs
+    ['SDG 3: Good Health and Well-being']
+
+
+Downloaded results are cached to expedite subsequent analyses.  This information may become outdated.  To refresh the cached results if they exist, set `refresh=True`, or provide an integer that will be interpreted as maximum allowed number of days since the last modification date.  For example, if you want to refresh all cached results older than 100 days, set `refresh=100`.  Use `ab.get_cache_file_mdate()` to obtain the date of last modification, and `ab.get_cache_file_age()` to determine the number of days since the last modification.

pybliometrics/__init__.py

@@ -8,3 +8,4 @@
 
 import pybliometrics.scopus
 import pybliometrics.sciencedirect
+import pybliometrics.scival

pybliometrics/scival/__init__.py

@@ -0,0 +1,3 @@
+from pybliometrics.utils import *
+
+from pybliometrics.scival.publication_lookup import *

pybliometrics/scival/publication_lookup.py

@@ -0,0 +1,121 @@
+"""Module with the PublicationLookup class."""
+from collections import namedtuple
+from typing import Union, Optional
+
+from pybliometrics.superclasses import Retrieval
+from pybliometrics.utils import make_int_if_possible, chained_get
+
+
+class PublicationLookup(Retrieval):
+
+    @property
+    def id(self) -> Optional[int]:
+        """ID of the document (same as EID without "2-s2.0-")."""
+        return make_int_if_possible(chained_get(self._json, ['publication', 'id']))
+
+    @property
+    def title(self) -> Optional[str]:
+        """Publication title."""
+        return chained_get(self._json, ['publication', 'title'])
+
+    @property
+    def doi(self) -> Optional[str]:
+        """Digital Object Identifier (DOI)."""
+        return chained_get(self._json, ['publication', 'doi'])
+
+    @property
+    def type(self) -> Optional[str]:
+        """Type of publication."""
+        return chained_get(self._json, ['publication', 'type'])
+
+    @property
+    def publication_year(self) -> Optional[int]:
+        """Year of publication."""
+        return make_int_if_possible(chained_get(self._json, ['publication', 'publicationYear']))
+
+    @property
+    def citation_count(self) -> Optional[int]:
+        """Count of citations."""
+        return make_int_if_possible(chained_get(self._json, ['publication', 'citationCount']))
+
+    @property
+    def source_title(self) -> Optional[str]:
+        """Title of source."""
+        return chained_get(self._json, ['publication', 'sourceTitle'])
+
+    @property
+    def topic_id(self) -> Optional[int]:
+        """Topic id."""
+        return make_int_if_possible(chained_get(self._json, ['publication', 'topicId']))
+
+    @property
+    def topic_cluster_id(self) -> Optional[int]:
+        """Topic cluster id."""
+        return make_int_if_possible(chained_get(self._json, ['publication', 'topicClusterId']))
+
+    @property
+    def link(self) -> Optional[str]:
+        """URL link."""
+        return chained_get(self._json, ['link', '@href'])
+
+    @property
+    def authors(self) -> Optional[list[namedtuple]]:
+        """Publication authors."""
+        out = []
+        fields = 'id name link'
+        auth = namedtuple('Author', fields)
+        for item in chained_get(self._json, ['publication', 'authors'], []):
+            new = auth(id=make_int_if_possible(item['id']), name=item.get('name'),
+                       link=chained_get(item, ['link', '@href']))
+            out.append(new)
+        return out or None
+
+    @property
+    def institutions(self) -> Optional[list[namedtuple]]:
+        """Institutions linked to publication authors."""
+        out = []
+        fields = 'id name country country_code link'
+        auth = namedtuple('Institution', fields)
+        for item in chained_get(self._json, ['publication', 'institutions'], []):
+            new = auth(id=make_int_if_possible(item['id']), name=item.get('name'), country=item.get('country'),
+                       country_code=item.get('countryCode'), link=chained_get(item, ['link', '@href']))
+            out.append(new)
+        return out or None
+
+    @property
+    def sdgs(self) -> Optional[list[str]]:
+        """List of Sustainable Development Goals (SDG)."""
+        return chained_get(self._json, ['publication', 'sdg'])
+
+    def __str__(self):
+        """Print a summary string."""
+        authors = ', '.join(a.name for a in self.authors) if self.authors else "N/A"
+        institutions = ', '.join(i.name for i in self.institutions) if self.institutions else "N/A"
+        sdgs = ', '.join(self.sdgs) if self.sdgs else "N/A"
+        s = (f"Publication Summary:\n"
+             f"- ID: {self.id or 'N/A'}\n"
+             f"- Title: {self.title or 'N/A'}\n"
+             f"- DOI: {self.doi or 'N/A'}\n"
+             f"- Type: {self.type or 'N/A'}\n"
+             f"- Year: {self.publication_year or 'N/A'}\n"
+             f"- Citation Count: {self.citation_count or 'N/A'}\n"
+             f"- Source Title: {self.source_title or 'N/A'}\n"
+             f"- Topic ID: {self.topic_id or 'N/A'}\n"
+             f"- Topic Cluster ID: {self.topic_cluster_id or 'N/A'}\n"
+             f"- Link: {self.link or 'N/A'}\n"
+             f"- Authors: {authors}\n"
+             f"- Institutions: {institutions}\n"
+             f"- SDGs: {sdgs}\n")
+        return s
+
+    def __init__(self, identifier: int = None, refresh: Union[bool, int] = False, **kwds: str) -> None:
+        """Interaction with the Publication Lookup API.
+        :param identifier: The Scopus ID of the object.
+        :param refresh: Whether to refresh the cached file if it exists. Default: `False`.
+        :param kwds: Keywords passed on to requests header.  Must contain
+                     fields and values specified in the respective
+                     API specification.
+                """
+        self._view = ''
+        self._refresh = refresh
+        Retrieval.__init__(self, identifier=str(identifier), **kwds)

pybliometrics/scival/tests/__init__.py

@@ -0,0 +1,58 @@
+"""Tests for the PublicationLookup() class."""
+
+from pybliometrics.scival import PublicationLookup
+from pybliometrics.utils import init
+
+init()
+
+# Base information
+pub1 = PublicationLookup(85036568406)
+
+
+def test_publication_id():
+    assert pub1.id == 85036568406
+
+
+def test_publication_doi():
+    assert pub1.doi == "10.1002/anie.201709271"
+
+
+def test_publication_type():
+    assert pub1.type == "Article"
+
+
+def test_publication_year():
+    assert pub1.publication_year == 2017
+
+
+def test_publication_source_title():
+    assert pub1.source_title == 'Angewandte Chemie - International Edition'
+
+
+def test_publication_citation_count():
+    assert pub1.citation_count > 0
+
+
+def test_publication_authors_count():
+    assert len(pub1.authors) >= 7
+
+
+def test_publication_first_author():
+    assert pub1.authors[0].id == 7404861905
+    assert pub1.authors[0].name == "Lin, T.-E."
+
+
+def test_publication_institutions_count():
+    assert len(pub1.institutions) >= 3
+
+
+def test_publication_first_institution():
+    assert pub1.institutions[0].id == 217002
+    assert pub1.institutions[0].name == "Chang Gung University"
+    assert pub1.institutions[0].country == "Taiwan"
+    assert pub1.institutions[0].country_code == "TWN"
+
+
+def test_publication_sdgs():
+    assert len(pub1.sdgs) >= 1
+    assert pub1.sdgs[0] == 'SDG 3: Good Health and Well-being'

pybliometrics/scival/tests/test_PublicationLookup.py

@@ -47,5 +47,7 @@ def __init__(self,
         self._cache_file_path = parent/self._view/stem
 
         # Parse file contents
-        params = {'view': self._view, **kwds}
+        params = {**kwds}
+        if self._view:
+            params['view'] = self._view
         Base.__init__(self, params=params, url=url)