pub-analyzer 0.1.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

pub_analyzer/models/institution.py

@@ -1,14 +1,21 @@
 """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 a Institution."""
 
-    openalex: HttpUrl
+    openalex: InstitutionOpenAlexID
     grid: str | None = None
     ror: HttpUrl | None = None
     wikipedia: HttpUrl | None = None
@@ -70,21 +77,31 @@ class InstitutionRole(BaseModel):
     works_count: int
 
 
+class International(BaseModel):
+    """The institution's display name in different languages."""
+
+    display_name: dict[str, str]
+
+
 class Institution(BaseModel):
     """Universities and other organizations to which authors claim affiliations."""
 
-    id: HttpUrl
+    id: InstitutionOpenAlexID
     ids: InstitutionIDs
 
     display_name: str
     country_code: str
     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
-    counts_by_year: list[InstitutionYearCount]
     summary_stats: InstitutionSummaryStats
+    counts_by_year: list[InstitutionYearCount]
 
     geo: InstitutionGeo
     roles: list[InstitutionRole]
@@ -95,7 +112,7 @@ class Institution(BaseModel):
 class DehydratedInstitution(BaseModel):
     """Stripped-down Institution Model."""
 
-    id: HttpUrl
+    id: InstitutionOpenAlexID
     ror: str
     display_name: str
     country_code: str
@@ -105,7 +122,7 @@ class DehydratedInstitution(BaseModel):
 class InstitutionResult(BaseModel):
     """Institution result Model resulting from a search in OpenAlex."""
 
-    id: HttpUrl
+    id: InstitutionOpenAlexID
     display_name: str
     hint: str | None = None
 

pub_analyzer/models/report.py

@@ -6,7 +6,7 @@ from pydantic import BaseModel
 
 from .author import Author
 from .institution import Institution
-from .source import DehydratedSource
+from .source import Source
 from .work import OpenAccessStatus, Work
 
 
@@ -24,7 +24,7 @@ class CitationReport(BaseModel):
     citation_type: CitationType
 
 
-class CitationResume(BaseModel):
+class CitationSummary(BaseModel):
     """Summary of citation information in all works."""
 
     type_a_count: int = 0
@@ -38,7 +38,7 @@ class CitationResume(BaseModel):
             self.type_b_count += 1
 
 
-class OpenAccessResume(BaseModel):
+class OpenAccessSummary(BaseModel):
     """Open Access Type counter."""
 
     gold: int = 0
@@ -75,13 +75,13 @@ class WorkReport(BaseModel):
     work: Work
     cited_by: list[CitationReport]
 
-    citation_resume: CitationResume
+    citation_summary: CitationSummary
 
 
-class SourcesResume(BaseModel):
+class SourcesSummary(BaseModel):
     """Sources model with stats."""
 
-    sources: list[DehydratedSource]
+    sources: list[Source]
 
 
 class AuthorReport(BaseModel):
@@ -90,10 +90,10 @@ class AuthorReport(BaseModel):
     author: Author
     works: list[WorkReport]
 
-    citation_resume: CitationResume
-    open_access_resume: OpenAccessResume
-    works_type_resume: list[WorkTypeCounter]
-    sources_resume: SourcesResume
+    citation_summary: CitationSummary
+    open_access_summary: OpenAccessSummary
+    works_type_summary: list[WorkTypeCounter]
+    sources_summary: SourcesSummary
 
 
 class InstitutionReport(BaseModel):
@@ -102,7 +102,7 @@ class InstitutionReport(BaseModel):
     institution: Institution
     works: list[WorkReport]
 
-    citation_resume: CitationResume
-    open_access_resume: OpenAccessResume
-    works_type_resume: list[WorkTypeCounter]
-    sources_resume: SourcesResume
+    citation_summary: CitationSummary
+    open_access_summary: OpenAccessSummary
+    works_type_summary: list[WorkTypeCounter]
+    sources_summary: SourcesSummary

pub_analyzer/models/source.py

@@ -1,21 +1,77 @@
 """Sources models from OpenAlex API Schema definition."""
 
-from pydantic import BaseModel, HttpUrl
+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 | None = False
-    is_in_doaj: bool | None = False
+    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
+    """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

@@ -6,7 +6,9 @@ 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):
@@ -34,7 +36,7 @@ class Location(BaseModel):
     license: str | None
     pdf_url: str | None
     version: WorkDrivenVersion | None
-    source: DehydratedSource  | None = None
+    source: DehydratedSource | None = None
 
 
 class OpenAccessStatus(str, Enum):
@@ -72,6 +74,22 @@ class ArticleProcessingCharge(BaseModel):
     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 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."""
 
@@ -97,6 +115,11 @@ class Work(BaseModel):
        To use a verified number that respects the applied filters use [WorkReport][pub_analyzer.models.report.WorkReport].
     """
 
+    grants: list[Grant]
+    keywords: list[Keyword]
+    concepts: list[DehydratedConcept]
+    topics: list[DehydratedTopic]
+
     referenced_works: list[HttpUrl]
     cited_by_api_url: HttpUrl
 
@@ -105,20 +128,20 @@ class Work(BaseModel):
     apc_paid: ArticleProcessingCharge | None = None
     """APC actually paid by authors."""
 
-    @field_validator('locations', mode='before')
+    @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]
+        return [location for location in locations if location["landing_page_url"] is not None]
 
-    @field_validator('primary_location', 'best_oa_location', mode='before')
+    @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:
+        if location and location["landing_page_url"] is None:
             return None
         else:
             return location
 
-    @field_validator('authorships', mode='before')
+    @field_validator("authorships", mode="before")
     def valid_authorships(cls, authorships: list[dict[str, Any]]) -> list[dict[str, Any]]:
         """Skip authorships that do not contain enough data."""
-        return [authorship for authorship in authorships if authorship['author'].get("id") is not None]
+        return [authorship for authorship in authorships if authorship["author"].get("id") is not None]

pub_analyzer/widgets/author/cards.py

@@ -19,12 +19,12 @@ class CitationMetricsCard(Card):
 
     def compose(self) -> ComposeResult:
         """Compose card."""
-        yield Label('[italic]Citation metrics:[/italic]', classes="card-title")
+        yield Label("[italic]Citation metrics:[/italic]", classes="card-title")
 
-        with Vertical(classes='card-container'):
-            yield Label(f'[bold]2-year mean:[/bold] {self.author.summary_stats.two_yr_mean_citedness:.5f}')
-            yield Label(f'[bold]h-index:[/bold] {self.author.summary_stats.h_index}')
-            yield Label(f'[bold]i10 index:[/bold] {self.author.summary_stats.i10_index}')
+        with Vertical(classes="card-container"):
+            yield Label(f"[bold]2-year mean:[/bold] {self.author.summary_stats.two_yr_mean_citedness:.5f}")
+            yield Label(f"[bold]h-index:[/bold] {self.author.summary_stats.h_index}")
+            yield Label(f"[bold]i10 index:[/bold] {self.author.summary_stats.i10_index}")
 
 
 class IdentifiersCard(Card):
@@ -36,7 +36,7 @@ class IdentifiersCard(Card):
 
     def compose(self) -> ComposeResult:
         """Compose card."""
-        yield Label('[italic]Identifiers:[/italic]', classes="card-title")
+        yield Label("[italic]Identifiers:[/italic]", classes="card-title")
 
         for platform, platform_url in self.author.ids.model_dump().items():
             if platform_url:
@@ -52,13 +52,14 @@ class LastInstitutionCard(Card):
 
     def compose(self) -> ComposeResult:
         """Compose card."""
-        yield Label('[italic]Last Institution:[/italic]', classes="card-title")
+        yield Label("[italic]Last Institution:[/italic]", classes="card-title")
 
-        if self.author.last_known_institution:
-            ror = self.author.last_known_institution.ror
-            institution_name = self.author.last_known_institution.display_name
+        if self.author.last_known_institutions:
+            last_known_institution = self.author.last_known_institutions[0]
+            ror = last_known_institution.ror
+            institution_name = last_known_institution.display_name
 
-            with Vertical(classes='card-container'):
-                yield Label(f'''[bold]Name:[/bold] [@click=app.open_link('{quote(str(ror))}')]{institution_name}[/]''')
-                yield Label(f'[bold]Country:[/bold] {self.author.last_known_institution.country_code}')
-                yield Label(f'[bold]Type:[/bold] {self.author.last_known_institution.type.value}')
+            with Vertical(classes="card-container"):
+                yield Label(f"""[bold]Name:[/bold] [@click=app.open_link('{quote(str(ror))}')]{institution_name}[/]""")
+                yield Label(f"[bold]Country:[/bold] {last_known_institution.country_code}")
+                yield Label(f"[bold]Type:[/bold] {last_known_institution.type.value}")

pub_analyzer/widgets/author/core.py

@@ -1,83 +1,84 @@
 """Module with Widgets that allows to display the complete information of an Author using OpenAlex."""
 
-import datetime
+from typing import Any
 
 import httpx
 from textual import on
 from textual.app import ComposeResult
-from textual.containers import Container, Horizontal, Vertical, VerticalScroll
-from textual.widgets import Button, Checkbox, Label, LoadingIndicator, Static
+from textual.containers import Container, Horizontal, Vertical
+from textual.widgets import Button, Collapsible, Label, Static
 
 from pub_analyzer.internal.identifier import get_author_id
 from pub_analyzer.models.author import Author, AuthorResult
-from pub_analyzer.widgets.common import DateInput
+from pub_analyzer.widgets.common.filters import DateRangeFilter, Filter
+from pub_analyzer.widgets.common.summary import SummaryWidget
 from pub_analyzer.widgets.report.core import CreateAuthorReportWidget
 
 from .cards import CitationMetricsCard, IdentifiersCard, LastInstitutionCard
 from .tables import AuthorWorksByYearTable
 
 
-class AuthorResumeWidget(Static):
-    """Author info resume."""
+class _AuthorSummaryWidget(Static):
+    """Author info summary."""
 
-    def __init__(self, author_result: AuthorResult) -> None:
-        self.author_result = author_result
-        self.author: Author
+    def __init__(self, author: Author) -> None:
+        self.author = author
         super().__init__()
 
     def compose(self) -> ComposeResult:
-        """Create main info container and showing a loading animation."""
-        yield LoadingIndicator()
-        yield VerticalScroll(id="main-container")
+        """Compose author info."""
+        is_report_not_available = self.author.works_count < 1
 
-    def on_mount(self) -> None:
-        """Hiding the empty container and calling the data in the background."""
-        self.query_one("#main-container", VerticalScroll).display = False
-        self.run_worker(self.load_data(), exclusive=True)
+        # Compose Cards
+        with Vertical(classes="block-container"):
+            yield Label("[bold]Author info:[/bold]", classes="block-title")
 
+            with Horizontal(classes="cards-container"):
+                yield LastInstitutionCard(author=self.author)
+                yield IdentifiersCard(author=self.author)
+                yield CitationMetricsCard(author=self.author)
 
-    @on(Checkbox.Changed, "#filters-checkbox")
-    async def toggle_filter(self, event: Checkbox.Changed) -> None:
-        """Toggle filters."""
-        if event.checkbox.value:
-            for date_input in self.query(DateInput).results(DateInput):
-                date_input.disabled = False
-                date_input.value = ""
-        else:
-            for date_input in self.query(DateInput).results(DateInput):
-                date_input.disabled = True
-                date_input.value = ""
-                self.query_one("#make-report-button", Button).disabled = False
-
-    @on(DateInput.Changed)
-    async def enable_make_report(self, event: DateInput.Changed) -> None:
-        """Enable make report button."""
-        checkbox = self.query_one("#filters-checkbox", Checkbox)
-
-        if event.validation_result:
-            if not event.validation_result.is_valid and checkbox.value:
-                self.query_one("#make-report-button", Button).disabled = True
-            else:
-                self.query_one("#make-report-button", Button).disabled = False
+        # Work realeted info
+        with Vertical(classes="block-container"):
+            yield Label("[bold]Work Info:[/bold]", classes="block-title")
 
-    @on(Button.Pressed, "#make-report-button")
-    async def make_report(self) -> None:
-        """Make the author report."""
-        checkbox = self.query_one("#filters-checkbox", Checkbox)
-        from_input = self.query_one("#from-date", DateInput)
-        to_input = self.query_one("#to-date", DateInput)
+            with Horizontal(classes="info-container"):
+                yield Label(f"[bold]Cited by count:[/bold] {self.author.cited_by_count}")
+                yield Label(f"[bold]Works count:[/bold] {self.author.works_count}")
 
-        if checkbox.value and (from_input.value or to_input.value):
-            date_format = "%Y-%m-%d"
-            from_date = datetime.datetime.strptime(from_input.value, date_format) if from_input.value else None
-            to_date = datetime.datetime.strptime(to_input.value, date_format) if to_input.value else None
+        # Count by year table section
+        with Container(classes="table-container"):
+            yield AuthorWorksByYearTable(author=self.author)
 
-            report_widget = CreateAuthorReportWidget(author=self.author, from_date=from_date, to_date=to_date)
-        else:
-            report_widget = CreateAuthorReportWidget(author=self.author)
+        # Make report section
+        with Vertical(classes="block-container", disabled=is_report_not_available):
+            yield Label("[bold]Make report:[/bold]", classes="block-title")
 
-        await self.app.query_one("MainContent").mount(report_widget)
-        await self.app.query_one("AuthorResumeWidget").remove()
+            # Filters
+            with Collapsible(title="Report filters.", classes="filter-collapsible"):
+                # Author publication Date Range
+                yield DateRangeFilter(checkbox_label="Publication date range:", id="author-date-range-filter")
+
+                # Cite Date Range
+                yield DateRangeFilter(checkbox_label="Cited date range:", id="cited-date-range-filter")
+
+            # Button
+            with Vertical(classes="button-container"):
+                yield Button("Make Report", variant="primary", id="make-report-button")
+
+
+class AuthorSummaryWidget(SummaryWidget):
+    """Author info summary container."""
+
+    def __init__(self, author_result: AuthorResult) -> None:
+        self.author_result = author_result
+        self.author: Author
+        super().__init__()
+
+    def on_mount(self) -> None:
+        """Hide the empty container and call data in the background."""
+        self.loading = True
+        self.run_worker(self.load_data(), exclusive=True)
 
     async def _get_info(self) -> None:
         """Query OpenAlex API."""
@@ -91,67 +92,31 @@ class AuthorResumeWidget(Static):
     async def load_data(self) -> None:
         """Query OpenAlex API and composing the widget."""
         await self._get_info()
-        container = self.query_one("#main-container", VerticalScroll)
-        is_report_not_available = self.author.works_count < 1
+        await self.mount(_AuthorSummaryWidget(author=self.author))
 
-        # Compose Cards
-        await container.mount(
-            Vertical(
-                Label('[bold]Author info:[/bold]', classes="block-title"),
-                Horizontal(
-                    LastInstitutionCard(author=self.author),
-                    IdentifiersCard(author=self.author),
-                    CitationMetricsCard(author=self.author),
-                    classes="cards-container"
-                ),
-                classes="block-container"
-            )
-        )
+        self.loading = False
 
-        # Work realeted info
-        await container.mount(
-            Vertical(
-                Label('[bold]Work Info:[/bold]', classes="block-title"),
-                Horizontal(
-                    Label(f'[bold]Cited by count:[/bold] {self.author.cited_by_count}'),
-                    Label(f'[bold]Works count:[/bold] {self.author.works_count}'),
-                    classes="info-container"
-                ),
-                classes="block-container"
-            )
-        )
+    @on(Filter.Changed)
+    def filter_change(self) -> None:
+        """Handle filter changes."""
+        filters = [filter for filter in self.query("_AuthorSummaryWidget Filter").results(Filter) if not filter.filter_disabled]
+        all_filters_valid = all(filter.validation_state for filter in filters)
 
-        # Count by year table section
-        await container.mount(
-            Container(
-                AuthorWorksByYearTable(author=self.author),
-                classes="table-container"
-            )
-        )
-
-        # Report Button
-        await container.mount(
-            Vertical(
-                Label('[bold]Make report:[/bold]', classes="block-title"),
-
-                # Filters
-                Horizontal(
-                    Checkbox("Filter", id="filters-checkbox"),
-                    DateInput(placeholder="From yyyy-mm-dd", disabled=True, id="from-date"),
-                    DateInput(placeholder="To yyyy-mm-dd", disabled=True, id="to-date"),
-                    classes="info-container filter-container",
-                ),
-
-                # Button
-                Vertical(
-                    Button("Make Report", variant="primary", id="make-report-button"),
-                    classes="block-container button-container"
-                ),
-                classes="block-container",
-                disabled=is_report_not_available
-            )
-        )
-
-        # Show results
-        self.query_one(LoadingIndicator).display = False
-        container.display = True
+        self.query_one("_AuthorSummaryWidget #make-report-button", Button).disabled = not all_filters_valid
+
+    @on(Button.Pressed, "#make-report-button")
+    async def make_report(self) -> None:
+        """Make the author report."""
+        filters: dict[str, Any] = {}
+        pub_date_range = self.query_one("#author-date-range-filter", DateRangeFilter)
+        cited_date_range = self.query_one("#cited-date-range-filter", DateRangeFilter)
+
+        if not pub_date_range.filter_disabled:
+            filters.update({"pub_from_date": pub_date_range.from_date, "pub_to_date": pub_date_range.to_date})
+
+        if not cited_date_range.filter_disabled:
+            filters.update({"cited_from_date": cited_date_range.from_date, "cited_to_date": cited_date_range.to_date})
+
+        report_widget = CreateAuthorReportWidget(author=self.author, **filters)
+        await self.app.query_one("MainContent").mount(report_widget)
+        await self.app.query_one("AuthorSummaryWidget").remove()

pub_analyzer/widgets/author/tables.py

@@ -16,7 +16,7 @@ class AuthorWorksByYearTable(Static):
 
     def compose(self) -> ComposeResult:
         """Compose Table."""
-        table = Table('Year', 'Works Count', 'Cited by Count', title="Counts by Year", expand=True)
+        table = Table("Year", "Works Count", "Cited by Count", title="Counts by Year", expand=True)
         for row in self.author.counts_by_year:
             year, works_count, cited_by_count = row.model_dump().values()
             table.add_row(str(year), str(works_count), str(cited_by_count))