omnibase/scholar

Installation and configuration

composer require omnibase/scholar:dev-main omnisense/omnischolar omnischolar/openalex omnischolar/hal omnischolar/crossref omnischolar/orcid

// config/bundles.php
Omnischolar\Bridge\Symfony\OmnischolarBundle::class => ['all' => true],
Base\Scholar\ScholarBundle::class => ['all' => true],

# config/routes.yaml
scholar_controller:
    resource: "@ScholarBundle/src/Controller/Client"
    type: attribute
    prefix: /

The sources (omnisense/omnischolar)

The names a scholar's profiles use are the configured sources:

# config/packages/omnischolar.yaml
omnischolar:
    sources:
        openalex: { factory: openalex, options: { mailto: '%env(OMNISCHOLAR_MAILTO)%' } }
        hal: { factory: hal }
        crossref: { factory: crossref, options: { mailto: '%env(OMNISCHOLAR_MAILTO)%' } }
        orcid: { factory: orcid }
        openlibrary: { factory: openlibrary, options: { mailto: '%env(OMNISCHOLAR_MAILTO)%' } }
    merger:
        preferences: { abstract: [hal, openalex], pdfUrl: [hal, openalex] }

The bundle (every key optional)

# config/packages/scholar.yaml
scholar:
    max_per_source: 2000          # works read from one source for one scholar
    metrics_source: openalex      # whose profile gives the counts (h-index...); ~ for none
    cv_source: orcid              # where the CV lines are read; ~: typed only
    per_page: 100                 # publications per page
    jsonld: true                  # Person, ScholarlyArticle, Book on the pages
    abstracts_in_exports: false

Then the tables (scholar_scholar, scholar_publication, scholar_publication_theme, scholar_theme, scholar_position, scholar_degree, scholar_award, scholar_grant, scholar_course, scholar_supervision):

bin/console doctrine:migrations:diff && bin/console doctrine:migrations:migrate
bin/console assets:install          # public/css/scholar.css

The scholar

In the back office (Identity and sources), or in the fixtures:

$scholar = (new Scholar('Keitaro Nakatani'))
    ->setOrcid('0009-0005-1387-7295')
    ->setProfiles([
        'openalex' => ['A5108007452'],
        'hal' => ['Keitaro Nakatani'],      // by the name he signs: by ORCID HAL finds only the deposits that carry it
        'crossref' => ['Keitaro Nakatani'],
    ]);

A profile names a configured source and one or several authors there: an OpenAlex id, an ORCID, an idHAL, a name - what that source's works() reads (omnisense/omnischolar's docs/sources.md).

The cron container

30 2 * * 1  php /srv/app/bin/console scholar:sync >> /srv/app/var/log/cron.scholar-sync.log 2>&1

No Symfony Scheduler: the sites' cron container runs it.

Requirements

• PHP 8.2 or later;
• doctrine/orm 2.15 or 3;
• omnisense/omnibase 3.0 or 4.0, omnibridge/symfony 1.x, omnibase/admin;
• omnisense/omnischolar 1.x, and the sources the site reads (suggested: omnischolar/openalex, omnischolar/hal, omnischolar/crossref, omnischolar/orcid, omnischolar/openlibrary);
• Symfony 6.4, 7 or 8 (config, console, dependency-injection, http-kernel, string).

Suggested as well: omnibase/agenda, for a scholar's talks and lectures as agenda events.

Concepts

The scholar

Base\Scholar\Entity\Scholar (scholar_scholar) is the person the site is about. The pages and the Twig functions read the first one.

getIdentityUrls() gathers the sameAs pages, the ORCID page, the OpenAlex author pages (ids like A5108007452) and the HAL CVs (an idHAL, not a name).

A publication

Base\Scholar\Entity\Publication (scholar_publication) is a work as the site shows it. It holds two kinds of fields:

• the sources' record: work (omnisense/omnischolar's Work, as JSON: the abstract, the sources, the identifiers, the editions, the PDF and the page the sources give), with its columns title, type, year, venue, authors, doi and citations, refreshed by every run (refresh($work)), and what the merge recognises it by (matchKeys, fingerprint, fetchedAt, lastSeenAt);
• the site's own: status, manual (typed by hand: its columns are the site's), hidden, pinned (first on the list), selected (the selection), pdf (an upload, 64 MB), pdfUrl, buyUrl, publisherUrl, cover (16 MB), note, themes.

Its type is one of omnisense/omnischolar's WorkType values: article, book, chapter, conference, preprint, thesis, report, dataset, software, review, editorial, other (an unknown value becomes other).

Themes and projects

Base\Scholar\Entity\Theme (scholar_theme) is a research theme or a project (ThemeKind: theme, project; isProject()): title, unique slug, summary, description (getParagraphs()), image, start and end years (getYears()), funder, address, position, visible. Publications are linked to themes (scholar_publication_theme).

The CV

Six entities share Base\Scholar\Entity\Cv\CvEntry: the scholar, title (required), organization, city, country (two letters), start and end (YYYY, YYYY-MM or YYYY-MM-DD), description, url, position, visible, origin (site, or the source it was read from) and externalKey (the source's key, so a line is read once).

getPeriod() writes "2019–2023", "2019–" for a current one, "2019" for one year; isCurrent() is started and not ended.

Base\Scholar\Service\Curriculum::sections($names) returns the visible entries of each section that has some (positions, degrees, awards, grants, courses, supervisions), by position, the current ones first, then the latest; a section whose table is not migrated yet is left out. countHidden() counts the hidden lines (a line read from the CV source waits hidden).

The three enums

PublicationStatus, ThemeKind and SupervisionLevel are PHP enums mapped with Doctrine's enumType on string columns; each case names itself in the scholar domain.

Synchronisation and validation

bin/console scholar:sync (--scholar=<id> for one) reads, for every scholar, every profile's works - every page, through omnischolar's Collector, merged by its Merger (same DOI, ISBN, arXiv id, HAL id, then title and year) - and lays them over the publications the site has:

A source that is down or rate limited is named in the summary (incomplete) and the others still answer; nothing is taken for "gone".

The same run reads the counts of the metrics source's profile (scholar.metrics_source: works, citations, h-index, i10-index, as OpenAlex computes them) and the CV source's lines (scholar.cv_source: ORCID's employments, education, distinctions - each once, by a key of its own; a new line waits hidden).

What the run did is kept on the scholar (lastSyncAt, lastSync) and shown in the widget.

Calling it yourself

$summary = $synchronizer->sync($scholar);           // read the sources, then merge, flush
$summary = $synchronizer->merge($scholar, $works);  // lay Works over the site's (persisted, not flushed)
$summary->created; $summary->updated; $summary->incomplete;

merge() is what a test or an import of a file calls.

Validating

The dashboard's scholar_pending widget lists the newest pending works with two buttons; the list Publications filters on the status and has the same actions on each row and record. Publication::approve(), reject().

Pages, Twig functions and the host's look

Only validated, not hidden publications are shown. The publication and theme pages are in /sitemap.xml (EventListener\SitemapListener).

What is not given yet

A portrait, a biography, a CV, research themes that nobody gave are never filled with an invented text: @Scholar/client/_draft.html.twig marks the place as a draft (scholar-draft, its tag Draft).

{% include '@Scholar/client/_draft.html.twig' with {kind: 'biography', message: 'The biography is being written.'} %}

Twig, for the host's own pages

{% include '@Scholar/client/_publication.html.twig' %} renders a publication as the list does; _theme_card.html.twig a theme.

The look

The templates extend layout1.html.twig and fill title, description, stylesheets and content. public/css/scholar.css follows the host's custom properties: --scholar-accent, --scholar-on-accent, --scholar-ink, --scholar-soft, --scholar-line, --scholar-surface, --scholar-font-display, --scholar-measure. Templates may be overridden in templates/bundles/ScholarBundle/.

Structured data and exports

JSON-LD (Service\JsonLd, scholar.jsonld)

Citing

Service\Citations::reference() writes the line to copy (authors with initials, year, title, journal, volume(issue), pages, DOI - or ISBN). export('bibtex'|'ris'|'csl-json', $publications) writes the files through omnisense/omnischolar's Export, from what the site shows: a PDF or a publisher's page given on the site goes into the file.

An example

use Base\Scholar\Entity\Publication;
use Base\Scholar\Entity\Scholar;
use Base\Scholar\Service\Citations;

$scholar = (new Scholar('Keitaro Nakatani'))->setOrcid('0009-0005-1387-7295');
$publication = (new Publication($scholar))
    ->setTitle('Acid-sensitive photoswitches')
    ->setType('article')
    ->setYear(2024)
    ->setVenue('Chemical Science')
    ->setAuthors('Lucas Chocron, Keitaro Nakatani')
    ->setDoi('10.1039/d4sc04973j');

$citations = new Citations();
echo $citations->reference($publication), "\n\n";
echo $citations->export('bibtex', $publication), "\n";
echo $citations->export('ris', $publication), "\n";

Its output, run in omnisense/omnibase-harness with omnisense/omnischolar on the autoloader:

Chocron, L., Nakatani, K. (2024). Acid-sensitive photoswitches. Chemical Science. https://doi.org/10.1039/d4sc04973j

@article{chocron2024acid,
  author = {Chocron, Lucas and Nakatani, Keitaro},
  title = {{Acid-sensitive photoswitches}},
  journal = {Chemical Science},
  year = {2024},
  doi = {10.1039/d4sc04973j}
}

TY  - JOUR
ID  - chocron2024acid
AU  - Chocron, Lucas
AU  - Nakatani, Keitaro
TI  - Acid-sensitive photoswitches
T2  - Chemical Science
PY  - 2024
DO  - 10.1039/d4sc04973j
UR  - https://doi.org/10.1039/d4sc04973j
ER  -

scholar.abstracts_in_exports: true writes the abstracts into the BibTeX and RIS files as well.

The back office (omnibase/admin)

CRUD screens, under /admin/scholars/...:

Who writes

These screens are the site's administrator's (ROLE_ADMIN: the researcher whose site it is), not the super-admin's only - each controller carries omnibase/admin's #[OpenToAdmins]: creating, editing and deleting, and the screens' own buttons (approve, reject on a publication, sync on the scholar). An application's CRUD extending one of them is opened too, and may close an action again in its configureActions() (->setPermission(Action::DELETE, 'ROLE_SUPERADMIN')). The attribute is omnibase/admin's from 7474f85.

// DashboardController
yield MenuItem::block('scholar_pending', 'Publications à valider', 'fa-solid fa-book-open')->setSize(4);
yield MenuItem::linkToCrud(\Base\Scholar\Entity\Publication::class, 'Publications', 'fa-solid fa-book-open');
yield MenuItem::linkToCrud(\Base\Scholar\Entity\Scholar::class, 'Identité et sources', 'fa-solid fa-id-card');
yield MenuItem::linkToCrud(\Base\Scholar\Entity\Cv\Position::class, 'CV · Postes', 'fa-solid fa-briefcase');

The widget's buttons post to admin_crud_scholars_publications_approve and _reject with the admin-action-approve / admin-action-reject tokens (omnibase/admin's #[AdminAction]), and come back to where they were.

A publication's status, a theme's kind and a supervision's level are PHP enums (PublicationStatus, ThemeKind, SupervisionLevel), mapped with Doctrine's enumType: on their string columns; in the back office each is a select of its cases (SelectField::new('status')), which name themselves in the scholar domain (TranslatableInterface). (They were kept as strings, with statusValue / kindValue / levelValue accessors for the selects, until omnibase could put an enum back into an entity's previous state and build a select from one: same columns, no migration.)

Configuration reference

The scholar tree

Dumped with Symfony's YamlReferenceDumper from Base\Scholar\DependencyInjection\ScholarConfiguration:

scholar:

    # The most works scholar:sync reads from one source for one scholar.
    max_per_source:       2000

    # The omnischolar source whose author profile gives the counts (works, citations, h-index); null: none.
    metrics_source:       openalex

    # The omnischolar source the CV is read from (positions, degrees, distinctions), when the scholar has a profile there; null: the CV is typed only.
    cv_source:            orcid

    # Publications listed per page.
    per_page:             100

    # schema.org Person, ScholarlyArticle and Book on the pages.
    jsonld:               true

    # Write the abstracts into the BibTeX and RIS exports.
    abstracts_in_exports: false

Each key is a container parameter: %scholar.max_per_source%, %scholar.metrics_source%, %scholar.cv_source%, %scholar.per_page%, %scholar.jsonld%, %scholar.abstracts_in_exports%.

The sources themselves are omnisense/omnischolar's (omnischolar.sources, Installation and configuration): a profile's source name is one of them.

Services

Base\Scholar\Service\PublicationIndex is built by the synchronizer from a scholar's publications, not taken from the container: it finds the site's publication for a Work by any identifier ever seen for it (a DOI, a HAL id, an ISBN of any edition), else by its title and year, unless both carry a DOI and they differ (two versions of a dataset, an erratum).

Translations

The domain scholar, in English, French and German (ICU format). A site overrides a message in its own translations/scholar+intl-icu.<locale>.yaml.

Testing

Running the suite

From the package's checkout, with its dev dependencies:

vendor/bin/phpunit

Inside a host application:

php vendor/bin/phpunit -c vendor/omnibase/scholar/phpunit.xml.dist

The suite needs omnisense/omnischolar. omnisense/omnibase-harness does not have it, and its test scholar stops when the kernel boots (Class "Omnischolar\Export" not found); with omnisense/omnischolar's packages added to the harness's autoloader (its checkouts mounted), the suite on this checkout gives:

OK (40 tests, 257 assertions)

What the tests check