Scival submodule

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=bea5cd32b1ad6cf822f6dea4e6dd7413&httpAccept=application/json&insttoken=b6fdf867f748e53962ff8ff8b9a18ded
+    - 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,120 @@
+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]]:
+        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]]:
+        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]]:
+        """Sustainable Development Goals."""
+        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.
+                """
+        self._view = ''
+        self._refresh = refresh
+        Retrieval.__init__(self, identifier=str(identifier), **kwds)

pybliometrics/scival/tests/test_PublicationLookup.py

@@ -0,0 +1,26 @@
+from pybliometrics.scival import PublicationLookup
+from pybliometrics.utils import init
+
+init()
+
+# Base information
+pub1 = PublicationLookup(85036568406)
+
+
+def test_publication():
+    assert pub1.id == 85036568406
+    assert pub1.doi == "10.1002/anie.201709271"
+    assert pub1.type == "Article"
+    assert pub1.publication_year == 2017
+    assert pub1.source_title == 'Angewandte Chemie - International Edition'
+    assert pub1.citation_count > 0
+    assert len(pub1.authors) >= 7
+    assert pub1.authors[0].id == 7404861905
+    assert pub1.authors[0].name == "Lin, T.-E."
+    assert len(pub1.institutions) >= 3
+    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"
+    assert len(pub1.sdgs) >= 1
+    assert pub1.sdgs[0] == 'SDG 3: Good Health and Well-being'

pybliometrics/utils/constants.py

@@ -19,6 +19,9 @@
 # Location of ScienceDirect cache
 BASE_PATH_SCIENCEDIRECT = Path.home() / ".cache" / "pybliometrics" / "ScienceDirect"
 
+# Location of Scival cache
+BASE_PATH_SCIVAL = Path.home() / ".cache" / "pybliometrics" / "Scival"
+
 DEFAULT_PATHS = {
     'AbstractRetrieval': BASE_PATH_SCOPUS / 'abstract_retrieval',
     'AffiliationRetrieval': BASE_PATH_SCOPUS / 'affiliation_retrieval',
@@ -36,11 +39,16 @@
     'ArticleRetrieval': BASE_PATH_SCIENCEDIRECT / 'article_retrieval',
     'ScienceDirectSearch': BASE_PATH_SCIENCEDIRECT / 'science_direct_search',
     'ScDirSubjectClassifications': BASE_PATH_SCIENCEDIRECT / 'subject_classification',
+
+    'PublicationLookup': BASE_PATH_SCIVAL / 'publication_lookup',
 }
 
 # URLs for all classes
 RETRIEVAL_BASE = 'https://api.elsevier.com/content/'
 SEARCH_BASE = 'https://api.elsevier.com/content/search/'
+SCIVAL_BASE = 'https://api.elsevier.com/analytics/scival/'
+
+
 URLS = {
     'AbstractRetrieval': RETRIEVAL_BASE + 'abstract/',
     'AffiliationRetrieval': RETRIEVAL_BASE + 'affiliation/affiliation_id/',
@@ -58,6 +66,9 @@
     'ArticleRetrieval': RETRIEVAL_BASE + 'article/',
     'ScienceDirectSearch': SEARCH_BASE + 'sciencedirect/',
     'ScDirSubjectClassifications': RETRIEVAL_BASE + 'subject/scidir/',
+
+    'PublicationLookup': SCIVAL_BASE + 'publication/',
+    'PublicationMetrics': SCIVAL_BASE + 'publication/metrics/'
 }
 
 # Valid views for all classes
@@ -77,7 +88,9 @@
     "ArticleRetrieval": ["META", "META_ABS", "META_ABS_REF", "FULL", "ENTITLED"],
     "ArticleMetadata": ["STANDARD", "COMPLETE"],
     "ScienceDirectSearch": ["STANDARD"],
-    "ScDirSubjectClassifications": ['']
+    "ScDirSubjectClassifications": [''],
+
+    "PublicationLookup": ['']
 }
 
 # Throttling limits (in queries per second) // 0 = no limit
@@ -98,6 +111,8 @@
     'ArticleRetrieval': 10,
     'ScienceDirectSearch': 2,
     'ScDirSubjectClassifications': 0,
+
+    'PublicationLookup': 6
 }
 
 # Other API restrictions