pub-analyzer 0.5.6__py3-none-any.whl

pub_analyzer/models/author.py

@@ -0,0 +1,87 @@
+"""Authors models from OpenAlex API Schema definition."""
+
+from typing import TypeAlias
+
+from pydantic import BaseModel, Field, HttpUrl
+
+from pub_analyzer.models.institution import DehydratedInstitution
+
+AuthorOpenAlexID: TypeAlias = HttpUrl
+"""OpenAlex ID for Author Objects with the format `https://openalex.org/A000000000`"""
+
+AuthorOpenAlexKey: TypeAlias = str
+"""OpenAlex author entity Key with the format `A000000000`"""
+
+
+class AuthorIDs(BaseModel):
+    """IDs from an Author."""
+
+    openalex: AuthorOpenAlexID
+    orcid: HttpUrl | None = None
+    scopus: HttpUrl | None = None
+    twitter: HttpUrl | None = None
+    wikipedia: HttpUrl | None = None
+
+
+class AuthorYearCount(BaseModel):
+    """Summary of published papers and number of citations in a year."""
+
+    year: int
+    works_count: int
+    cited_by_count: int
+
+
+class AuthorSummaryStats(BaseModel):
+    """Citation metrics for this author."""
+
+    two_yr_mean_citedness: float = Field(..., alias="2yr_mean_citedness")
+    h_index: int
+    i10_index: int
+
+
+class AuthorAffiliation(BaseModel):
+    """List of affiliations this author has claimed in their publications."""
+
+    institution: DehydratedInstitution
+    years: list[int]
+
+
+class Author(BaseModel):
+    """Author Model Object from OpenAlex API definition."""
+
+    id: AuthorOpenAlexID
+    ids: AuthorIDs
+    orcid: str | None = ""
+
+    display_name: str
+    display_name_alternatives: list[str]
+    last_known_institutions: list[DehydratedInstitution] | None = Field(default_factory=list)
+    affiliations: list[AuthorAffiliation]
+
+    works_count: int
+    cited_by_count: int
+
+    counts_by_year: list[AuthorYearCount]
+    summary_stats: AuthorSummaryStats
+
+    works_api_url: str
+
+
+class DehydratedAuthor(BaseModel):
+    """Stripped-down Author Model."""
+
+    id: AuthorOpenAlexID
+    display_name: str | None = None
+    orcid: HttpUrl | None = None
+
+
+class AuthorResult(BaseModel):
+    """Author result Model resulting from a search in OpenAlex."""
+
+    id: AuthorOpenAlexID
+    display_name: str
+    hint: str | None = None
+    cited_by_count: int
+    works_count: int
+    entity_type: str
+    external_id: str | None = None

pub_analyzer/models/concept.py

@@ -0,0 +1,19 @@
+"""Concept model from OpenAlex API Schema definition."""
+
+from pydantic import BaseModel, HttpUrl
+
+
+class DehydratedConcept(BaseModel):
+    """Stripped-down Concept Model."""
+
+    id: HttpUrl
+    """The OpenAlex ID for this concept."""
+    display_name: str
+    """The English-language label of the concept."""
+
+    wikidata: HttpUrl
+    """The Wikidata ID for this concept. All OpenAlex concepts are also Wikidata concepts."""
+    level: int
+    """The level in the concept. Lower-level concepts are more general, and higher-level concepts are more specific."""
+    score: float
+    """The strength of the connection between the work and this concept (higher is stronger)."""

pub_analyzer/models/institution.py

@@ -0,0 +1,138 @@
+"""Institutions models from OpenAlex API Schema definition."""
+
+from enum import Enum
+from typing import TypeAlias
+
+from pydantic import BaseModel, Field, HttpUrl
+
+InstitutionOpenAlexID: TypeAlias = HttpUrl
+"""OpenAlex ID for Institution Objects with the format `https://openalex.org/I000000000`"""
+
+InstitutionOpenAlexKey: TypeAlias = str
+"""OpenAlex Institution entity Key with the format `I000000000`"""
+
+
+class InstitutionIDs(BaseModel):
+    """IDs from an Institution."""
+
+    openalex: InstitutionOpenAlexID
+    grid: str | None = None
+    ror: HttpUrl | None = None
+    wikipedia: HttpUrl | None = None
+    wikidata: HttpUrl | None = None
+
+
+class InstitutionType(str, Enum):
+    """The institution's primary type, using the ROR "type" controlled vocabulary."""
+
+    Education = "education"
+    Healthcare = "healthcare"
+    Company = "company"
+    Archive = "archive"
+    Nonprofit = "nonprofit"
+    Government = "government"
+    Facility = "facility"
+    Funder = "funder"
+    Other = "other"
+
+
+class InstitutionSummaryStats(BaseModel):
+    """Citation metrics for this Institution."""
+
+    two_yr_mean_citedness: float = Field(..., alias="2yr_mean_citedness")
+    h_index: int
+    i10_index: int
+
+
+class InstitutionYearCount(BaseModel):
+    """Summary of published papers and number of citations in a year."""
+
+    year: int
+    works_count: int
+    cited_by_count: int
+
+
+class InstitutionGeo(BaseModel):
+    """Location of the institution."""
+
+    city: str
+    geonames_city_id: str
+
+    region: str | None = None
+    country_code: str | None = None
+    country: str
+
+    latitude: float
+    longitude: float
+
+
+class InstitutionRoleType(str, Enum):
+    """Possible institution roles."""
+
+    funder = "funder"
+    publisher = "publisher"
+    institution = "institution"
+
+
+class InstitutionRole(BaseModel):
+    """Institution role."""
+
+    role: InstitutionRoleType
+    id: HttpUrl
+    works_count: int
+
+
+class International(BaseModel):
+    """The institution's display name in different languages."""
+
+    display_name: dict[str, str] | None = None
+
+
+class Institution(BaseModel):
+    """Universities and other organizations to which authors claim affiliations."""
+
+    id: InstitutionOpenAlexID
+    ids: InstitutionIDs
+
+    display_name: str
+    country_code: str | None = None
+    type: InstitutionType
+    homepage_url: HttpUrl | None = None
+    image_url: HttpUrl | None = None
+
+    display_name_acronyms: list[str]
+    international: International
+
+    works_count: int
+    cited_by_count: int
+    summary_stats: InstitutionSummaryStats
+    counts_by_year: list[InstitutionYearCount]
+
+    geo: InstitutionGeo
+    roles: list[InstitutionRole]
+
+    works_api_url: str
+
+
+class DehydratedInstitution(BaseModel):
+    """Stripped-down Institution Model."""
+
+    id: InstitutionOpenAlexID
+    ror: str
+    display_name: str
+    country_code: str | None = None
+    type: InstitutionType
+
+
+class InstitutionResult(BaseModel):
+    """Institution result Model resulting from a search in OpenAlex."""
+
+    id: InstitutionOpenAlexID
+    display_name: str
+    hint: str | None = None
+
+    cited_by_count: int
+    works_count: int
+
+    entity_type: str
+    external_id: str | None = None

pub_analyzer/models/report.py

@@ -0,0 +1,111 @@
+"""Reports Structure Objects."""
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+from .author import Author
+from .institution import Institution
+from .source import Source
+from .work import OpenAccessStatus, Work
+
+
+class CitationType(Enum):
+    """Citation type Work."""
+
+    TypeA = 0
+    TypeB = 1
+
+
+class CitationReport(BaseModel):
+    """Cited by Works with stats."""
+
+    work: Work
+    citation_type: CitationType
+
+
+class CitationSummary(BaseModel):
+    """Summary of citation information in all works."""
+
+    type_a_count: int = 0
+    type_b_count: int = 0
+
+    def add_cite_type(self, cite_type: CitationType) -> None:
+        """Add the type of cite in the corresponding counter."""
+        if cite_type.value == CitationType.TypeA.value:
+            self.type_a_count += 1
+        elif cite_type.value == CitationType.TypeB.value:
+            self.type_b_count += 1
+
+
+class OpenAccessSummary(BaseModel):
+    """Open Access Type counter."""
+
+    diamond: int = 0
+    gold: int = 0
+    green: int = 0
+    hybrid: int = 0
+    bronze: int = 0
+    closed: int = 0
+
+    def add_oa_type(self, open_access_type: OpenAccessStatus) -> None:
+        """Add the type of Open Access in the corresponding counter."""
+        match open_access_type:
+            case OpenAccessStatus.diamond:
+                self.diamond += 1
+            case OpenAccessStatus.gold:
+                self.gold += 1
+            case OpenAccessStatus.green:
+                self.green += 1
+            case OpenAccessStatus.hybrid:
+                self.hybrid += 1
+            case OpenAccessStatus.bronze:
+                self.bronze += 1
+            case OpenAccessStatus.closed:
+                self.closed += 1
+
+
+class WorkTypeCounter(BaseModel):
+    """Work Type Counter."""
+
+    type_name: str
+    count: int
+
+
+class WorkReport(BaseModel):
+    """Work model with stats."""
+
+    work: Work
+    cited_by: list[CitationReport]
+
+    citation_summary: CitationSummary
+
+
+class SourcesSummary(BaseModel):
+    """Sources model with stats."""
+
+    sources: list[Source]
+
+
+class AuthorReport(BaseModel):
+    """Report of scientific production of an author."""
+
+    author: Author
+    works: list[WorkReport]
+
+    citation_summary: CitationSummary
+    open_access_summary: OpenAccessSummary
+    works_type_summary: list[WorkTypeCounter]
+    sources_summary: SourcesSummary
+
+
+class InstitutionReport(BaseModel):
+    """Scientific production report of the Institution."""
+
+    institution: Institution
+    works: list[WorkReport]
+
+    citation_summary: CitationSummary
+    open_access_summary: OpenAccessSummary
+    works_type_summary: list[WorkTypeCounter]
+    sources_summary: SourcesSummary

pub_analyzer/models/source.py

@@ -0,0 +1,77 @@
+"""Sources models from OpenAlex API Schema definition."""
+
+from pydantic import BaseModel, Field, HttpUrl
+
+
+class SourceSummaryStats(BaseModel):
+    """Citation metrics for this Source."""
+
+    two_yr_mean_citedness: float = Field(..., alias="2yr_mean_citedness")
+    """The 2-year mean citedness for this source. Also known as impact factor."""
+    h_index: int
+    """The h-index for this source."""
+    i10_index: int
+    """The i-10 index for this source."""
+
+
+class SourceYearCount(BaseModel):
+    """Summary of published papers and number of citations in a year."""
+
+    year: int
+    """Year."""
+    works_count: int
+    """The number of Works this source hosts in this year."""
+    cited_by_count: int
+    """The total number of Works that cite a Work hosted in this source in this year."""
+
+
+class DehydratedSource(BaseModel):
+    """Stripped-down Source Model."""
+
+    id: HttpUrl
+    """The OpenAlex ID for this source."""
+    display_name: str
+    """The name of the source."""
+
+    issn_l: str | None = None
+    """The ISSN-L identifying this source. The ISSN-L designating a single canonical ISSN
+       for all media versions of the title. It's usually the same as the print ISSN.
+    """
+    issn: list[str] | None = None
+    """The ISSNs used by this source. An ISSN identifies all continuing resources, irrespective
+       of their medium (print or electronic). [More info](https://www.issn.org/){target=_blank}.
+    """
+
+    is_oa: bool
+    """Whether this is currently fully-open-access source."""
+    is_in_doaj: bool
+    """Whether this is a journal listed in the [Directory of Open Access Journals](https://doaj.org){target=_blank} (DOAJ)."""
+
+    host_organization: HttpUrl | None = None
+    """The host organization for this source as an OpenAlex ID. This will be an
+       [Institution.id][pub_analyzer.models.institution.Institution.id] if the source is a repository,
+       and a Publisher.id if the source is a journal, conference, or eBook platform
+    """
+    host_organization_name: str | None = None
+    """The display_name from the host_organization."""
+
+    type: str | None = None
+    """The type of source, which will be one of: `journal`, `repository`, `conference`,
+       `ebook platform`, or `book series`.
+    """
+
+
+class Source(DehydratedSource):
+    """Where works are hosted."""
+
+    homepage_url: HttpUrl | None = None
+    """The homepage for this source's website."""
+
+    is_in_doaj: bool
+    """Whether this is a journal listed in the Directory of Open Access Journals (DOAJ)."""
+
+    summary_stats: SourceSummaryStats
+    """Citation metrics for this source."""
+
+    counts_by_year: list[SourceYearCount]
+    """works_count and cited_by_count for each of the last ten years, binned by year."""

pub_analyzer/models/topic.py

@@ -0,0 +1,59 @@
+"""Topics models from OpenAlex API Schema definition."""
+
+from pydantic import BaseModel, HttpUrl
+
+
+class TopicIDs(BaseModel):
+    """External identifiers for a Topic."""
+
+    openalex: HttpUrl
+    """The OpenAlex ID for this Topic."""
+    wikipedia: HttpUrl | None = None
+    """This topic's Wikipedia page URL."""
+
+
+class TopicLevel(BaseModel):
+    """Topic level information."""
+
+    id: HttpUrl
+    """ID for the topic level. For more info, consult the
+       [OpenAlex topic mapping table](https://docs.google.com/spreadsheets/d/1v-MAq64x4YjhO7RWcB-yrKV5D_2vOOsxl4u6GBKEXY8/){target=_blank}.
+    """
+    display_name: str
+    """The English-language label of the level."""
+
+
+class DehydratedTopic(BaseModel):
+    """Stripped-down Topic Model."""
+
+    id: HttpUrl
+    """The OpenAlex ID for this Topic."""
+    display_name: str
+    """The English-language label of the topic."""
+    score: float
+    """The strength of the connection between the work and this topic (higher is stronger)."""
+
+    domain: TopicLevel
+    """The highest level in the Topics structure."""
+    field: TopicLevel
+    """The second-highest level in the Topics structure."""
+    subfield: TopicLevel
+    """The third-highest level in the Topics structure."""
+
+
+class Topic(DehydratedTopic):
+    """Labels which can be used to describe what a paper is about."""
+
+    ids: TopicIDs
+    """All the external identifiers for a Topic."""
+    description: str
+    """A description of this topic, generated by AI."""
+    keywords: list[str]
+    """Keywords consisting of one or several words each, meant to represent
+       the content of the papers in the topic.
+    """
+
+    works_count: int
+    """The number of works tagged with this topic."""
+    cited_by_count: int
+    """The number of citations to works that have been tagged with this topic."""

pub_analyzer/models/work.py

@@ -0,0 +1,158 @@
+"""Works models from OpenAlex API Schema definition."""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, HttpUrl, field_validator
+
+from .author import DehydratedAuthor
+from .concept import DehydratedConcept
+from .source import DehydratedSource
+from .topic import DehydratedTopic
+
+
+class WorkIDs(BaseModel):
+    """IDs from a Work."""
+
+    openalex: HttpUrl
+    doi: HttpUrl | None = None
+    pmid: str | None = None
+    pmcid: str | None = None
+
+
+class WorkDrivenVersion(str, Enum):
+    """The version of the work, based on the Driver Guidelines versioning scheme."""
+
+    submitted = "submittedVersion"
+    accepted = "acceptedVersion"
+    published = "publishedVersion"
+
+
+class Location(BaseModel):
+    """Describes the location of a given work."""
+
+    is_oa: bool
+    landing_page_url: str
+    license: str | None
+    pdf_url: str | None
+    version: WorkDrivenVersion | None
+    source: DehydratedSource | None = None
+
+
+class OpenAccessStatus(str, Enum):
+    """The Open Access (OA) status of this work."""
+
+    diamond = "diamond"
+    gold = "gold"
+    green = "green"
+    hybrid = "hybrid"
+    bronze = "bronze"
+    closed = "closed"
+
+
+class WorkAccessInfo(BaseModel):
+    """Information about the access status of this work."""
+
+    is_oa: bool
+    oa_status: OpenAccessStatus
+    oa_url: str | None = None
+    any_repository_has_fulltext: bool
+
+
+class Authorship(BaseModel):
+    """Information of author and her institutional affiliations in the context of work."""
+
+    author_position: str
+    author: DehydratedAuthor
+
+
+class ArticleProcessingCharge(BaseModel):
+    """Information about the paid APC for this work."""
+
+    value: int
+    currency: str
+    provenance: str | None = None
+    value_usd: int | None
+
+
+class Grant(BaseModel):
+    """Grant Model Object from OpenAlex API definition."""
+
+    funder: HttpUrl
+    funder_display_name: str
+    award_id: str | None = None
+
+
+class Award(BaseModel):
+    """Award work details."""
+
+    id: HttpUrl
+    display_name: str | None = None
+    funder_award_id: str | None = None
+    funder_id: HttpUrl
+    funder_display_name: str
+    doi: str | None = None
+
+
+class Keyword(BaseModel):
+    """Keyword extracted from the work's title and confidence score."""
+
+    id: HttpUrl
+    display_name: str
+    score: float
+
+
+class Work(BaseModel):
+    """Work Model Object from OpenAlex API definition."""
+
+    id: HttpUrl
+    ids: WorkIDs
+
+    title: str
+    abstract: str | None = None
+    publication_year: int | None = None
+    publication_date: str | None = None
+    language: str | None = None
+    type: str
+
+    primary_location: Location | None = None
+    best_oa_location: Location | None = None
+    locations: list[Location]
+
+    open_access: WorkAccessInfo
+    authorships: list[Authorship]
+
+    cited_by_count: int
+    """This number comes from the OpenAlex API, represents ALL citations to this work, and may not always be correct.
+       To use a verified number that respects the applied filters use [WorkReport][pub_analyzer.models.report.WorkReport].
+    """
+
+    awards: list[Award]
+    keywords: list[Keyword]
+    concepts: list[DehydratedConcept]
+    topics: list[DehydratedTopic]
+
+    referenced_works: list[HttpUrl]
+
+    apc_list: ArticleProcessingCharge | None = None
+    """The price as listed by the journal's publisher."""
+    apc_paid: ArticleProcessingCharge | None = None
+    """APC actually paid by authors."""
+
+    @field_validator("locations", mode="before")
+    def valid_locations(cls, locations: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Skip locations that do not contain enough data."""
+        return [location for location in locations if location["landing_page_url"] is not None]
+
+    @field_validator("primary_location", "best_oa_location", mode="before")
+    def valid_location(cls, location: dict[str, Any]) -> dict[str, Any] | None:
+        """Skip location that do not contain enough data."""
+        if location and location["landing_page_url"] is None:
+            return None
+        else:
+            return location
+
+    @field_validator("authorships", mode="before")
+    def valid_authorships(cls, authorships: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Skip authorship's that do not contain enough data."""
+        return [authorship for authorship in authorships if authorship["author"].get("id") is not None]

pub_analyzer/widgets/__init__.py

@@ -0,0 +1 @@
+"""TUI module."""

pub_analyzer/widgets/author/__init__.py

@@ -0,0 +1 @@
+"""Author Widgets."""