Report

If you're using pub analyzer as an external library, you'll find pretty much everything you need here. This is where all the magic happens.

Suppose you already have an author model. Let's see how to generate a scientific production report of that author.

import asyncio

from pub_analyzer.internal.report import make_author_report
from pub_analyzer.models.author import Author

author = Author(**kwargs) # (1)!
report = asyncio.run(make_author_report(author=author)) # (2)!

1. Use real information instead of **kwargs placeholder.
2. Functions are defined as asynchronous since their primary use occurs within a TUI context. We apologize for any inconvenience this may cause.

And that's it! that's all. Well, maybe you want to export the report to a format like JSON, that's where pydantic does its magic.

with open("report.json", mode="w", encoding="utf-8") as file:
    file.write(report.model_dump_json(indent=2, by_alias=True)) # (1)!

1. It is important that you use the by_alias=True parameter, otherwise you will not be able to import correctly using the pub analyzer models.

ta-da!

Early stages

In the early phases of the project, before Pub Analyzer existed as a TUI, the main goal was to emulate an Excel file. This file, based on input tables containing the works of an author and the works that reference them, categorized the types of citations. Later, the idea was expanded to encompass automating works retrieval. It was during this period that I stumbled across OpenAlex, and as they say, one thing led to another.

Functions to make reports.

FromDate module-attribute

FromDate = NewType('FromDate', datetime.datetime)

DateTime marker for works published from this date.

ToDate module-attribute

ToDate = NewType('ToDate', datetime.datetime)

DateTime marker for works published up to this date.

make_author_report async

make_author_report(
    author: Author,
    extra_profiles: list[
        Author | AuthorResult | DehydratedAuthor
    ]
    | None = None,
    pub_from_date: FromDate | None = None,
    pub_to_date: ToDate | None = None,
    cited_from_date: FromDate | None = None,
    cited_to_date: ToDate | None = None,
    on_progress: ProgressCallback = ignore_progress,
) -> AuthorReport

Make a scientific production report by Author.

Parameters:

Name	Type	Description	Default
author	Author	Author to whom the report is generated.	required
extra_profiles	list[Author | AuthorResult | DehydratedAuthor] | None	List of author profiles whose works will be attached.	None
pub_from_date	FromDate | None	Filter works published from this date.	None
pub_to_date	ToDate | None	Filter works published up to this date.	None
cited_from_date	FromDate | None	Filter works that cite the author, published after this date.	None
cited_to_date	ToDate | None	Filter works that cite the author, published up to this date.	None
on_progress	ProgressCallback	Called as the report advances, to follow a long running report.	ignore_progress

Returns:

Type	Description
AuthorReport	Author's scientific production report Model.

Raises:

Type	Description
HTTPStatusError	One response from OpenAlex API had an error HTTP status of 4xx or 5xx.

Info

The Author in the report carries the year counts observed while building it, which respect the date filters applied. The Author passed in is left untouched.

make_institution_report async

make_institution_report(
    institution: Institution,
    extra_profiles: list[
        Institution
        | InstitutionResult
        | DehydratedInstitution
    ]
    | None = None,
    pub_from_date: FromDate | None = None,
    pub_to_date: ToDate | None = None,
    cited_from_date: FromDate | None = None,
    cited_to_date: ToDate | None = None,
    on_progress: ProgressCallback = ignore_progress,
) -> InstitutionReport

Make a scientific production report by Institution.

Parameters:

Name	Type	Description	Default
institution	Institution	Institution to which the report is generated.	required
extra_profiles	list[Institution | InstitutionResult | DehydratedInstitution] | None	List of institutions profiles whose works will be attached.	None
pub_from_date	FromDate | None	Filter works published from this date.	None
pub_to_date	ToDate | None	Filter works published up to this date.	None
cited_from_date	FromDate | None	Filter works that cite the institution, published after this date.	None
cited_to_date	ToDate | None	Filter works that cite the institution, published up to this date.	None
on_progress	ProgressCallback	Called as the report advances, to follow a long running report.	ignore_progress

Returns:

Type	Description
InstitutionReport	Institution's scientific production report Model.

Raises:

Type	Description
HTTPStatusError	One response from OpenAlex API had an error HTTP status of 4xx or 5xx.

Info

The Institution in the report carries the year counts observed while building it, which respect the date filters applied. The Institution passed in is left untouched.