Metadata-Version: 2.4
Name: chronotome
Version: 0.1.0
Summary: A reproducible local bibliometric workflow for Scopus and Web of Science exports.
Author: L.-E. Popescu-Apreutesei, M.-S. Iosupescu
License-Expression: MIT
Project-URL: Homepage, https://github.com/AthenaP21/Chronotome
Project-URL: Repository, https://github.com/AthenaP21/Chronotome
Project-URL: Issues, https://github.com/AthenaP21/Chronotome/issues
Keywords: bibliometrics,scientometrics,streamlit,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit<2,>=1.36
Requires-Dist: pandas<3,>=2.0
Requires-Dist: numpy<3,>=1.24
Requires-Dist: matplotlib<4,>=3.7
Requires-Dist: seaborn<1,>=0.12
Requires-Dist: scipy<1.14,>=1.10
Requires-Dist: networkx<4,>=3.1
Requires-Dist: pycountry>=23.12
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: xlrd<3,>=2.0
Requires-Dist: scikit-learn<2,>=1.3
Requires-Dist: adjustText<2,>=1.0
Requires-Dist: nltk<4,>=3.8
Requires-Dist: wordcloud<2,>=1.9
Requires-Dist: gensim==4.3.3
Dynamic: license-file

# Chronotome

Chronotome is a Streamlit conversion of the original reproducible Jupyter/Kaggle bibliometric workflow. It accepts Scopus and Web of Science exports, harmonizes their schemas, fuses and deduplicates records, corrects for collection-year indexing lag, and produces the notebook's descriptive, citation, source, author, country, thematic, and institutional-network outputs.

## Run locally

Chronotome is installable as a local Python package. Python 3.11 is recommended.

```bash
git clone https://github.com/AthenaP21/Chronotome.git
cd Chronotome
python3.11 -m venv .venv
source .venv/bin/activate              # Windows: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --only-binary=:all: .
chronotome
```

The `chronotome` command starts the app at `http://127.0.0.1:8501`; it is deliberately limited to the local machine. Use `chronotome --port 8502` if port 8501 is already occupied. For local development, the familiar command remains available:

```bash
pip install -r requirements.txt
streamlit run app.py --server.address 127.0.0.1
```

No notebook interface or local data paths are required. All uploaded and generated files are handled in memory. See the in-app **Local installation** page and [SECURITY.md](SECURITY.md) for the installation and release-safety guidance.

## App pages

- **Home** introduces Chronotome, its expected outputs, the Zenodo open-science release, the bundled institution aliases, and the suggested citation.
- **Data ingestion** provides separate Scopus and WoS configuration, Single file and Appendage modes, upload verification, deterministic preprocessing, schema harmonization, deduplication, textual PRISMA reporting, and final CSV/Excel/ZIP downloads.
- **Entity resolution** explodes affiliations, standardizes institutions and countries, accepts the bundled or an uploaded `institutions.json`, reports alias conflicts and unresolved geography, and exports affiliation/article-level tables.
- **Corpus & production** uses the current entity-resolved article summary and starts only when **Generate corpus analysis** is selected. It reproduces notebook sections 9 and 11–16: corpus characteristics, internal MNCS, document typology, author productivity/contribution, annual growth, citation dynamics, and local journal/source impact.
- **Geographic analysis** starts only when **Generate geographic analysis** is selected. It reproduces notebook Sections 17–18 and 20–21: country distribution, SCP/MCP collaboration, country MNCS, citation prestige, the productivity-impact matrix, the international collaboration network, and clickable country case studies.
- **Advanced analyses** runs after the geographic phase and produces the final paper-ready dataset summary, article and author impact rankings, Bradford scattering, hot papers, team-size impact, and the journal landscape.
- **Thematic analysis** uses the current geographic dataset or prepares one uploaded Chronotome dataset in the background. It provides staged NLTK setup, optional query-term removal, visible editable noise-list categories, 1–4 gram extraction and word clouds, automatic LDA/NMF topic selection, longitudinal topic evolution, topic impact/co-occurrence, canonical papers, and country specialization.
- **Institutional analysis** uses the current geographic dataset or the unchanged `article_summary_with_country_classification` handoff file. Choose one Global/EU × All/MCP/SCP scope and select **Generate institutional network** to create it. Completed scopes can be compared side by side using their original network graphs; the page also offers community visualizations, GraphML/CSV/Excel exports, and optional topic-specific networks.
- **Full workflow** provides a single **Run all workflow** action. It starts from raw Scopus/WoS files or the current ingestion result, executes every modern stage through all six institutional community visualizations, and returns one structured ZIP containing the workflow's Excel files, plots, network exports, and manifest.
  The background runner streams stage artifacts directly into the master archive, releases completed figures and graphs, avoids nested ZIP/dataset duplication, and records process-memory usage after every stage.
- **Local installation** is a step-by-step guide to installing, launching, updating, and securing Chronotome on your own computer.

## Input files

Upload one or more exports in `.csv`, `.txt`, `.xls`, or `.xlsx` format:

- Scopus CSV is recommended. The app recognizes fields such as `Title`, `Source title`, `Year`, `Cited by`, `Authors`, and `Affiliations`.
- Web of Science tab-delimited TXT, CSV, XLS, and XLSX are supported. WoS files with an `.xls` extension that are actually tab-delimited text use the notebook's fallback parser.
- Tagged WoS plain text (`PT`, `AU`, `TI`, …, `ER`) is also parsed.
- Split files from the same database can be uploaded together and are appended before harmonization.
- At minimum, the export must contain the source-specific title field (`Title` for Scopus or `Article Title` for WoS). Full records with cited references are strongly recommended.

The app detects the database from the export columns. It does not infer or fetch missing records from external services.

In **Appendage** mode, files must represent one numbered split-export series, such as `query_1.csv`, `query_2.csv`, and `query_3.csv`. Chronotome verifies the common base name and extension, checks for duplicate or missing part numbers, and sorts parts numerically before stacking them. Scopus and WoS appendages are always processed separately.

## Supported workflow

The Streamlit app preserves the notebook's current methods:

- Scopus/WoS schema mapping and merged common schema
- author-name and cited-reference preprocessing
- preprocessing audit tables for author delimiter changes, removed Scopus IDs, parsed references, and mapped fields
- DOI normalization, citation-prioritized DOI data fusion, and title/year deduplication for records without DOI
- optional collection-year cutoff for indexing-lag correction
- PRISMA-style identification, screening, and included counts
- notebook-style textual PRISMA report with an arithmetic integrity check (no PRISMA diagram)
- curated institution alias resolution using `chronotome_core/institutions.json`
- optional runtime upload of a manually updated or newer Zenodo `institutions.json`; uploaded JSON is validated and treated as authoritative
- affiliation-based institution and country extraction, including SCP/MCP classification
- internal year-normalized citation score (MNCS relative to the uploaded corpus)
- corpus summary, annual production, citation dynamics, and document-type taxonomy
- author full/fractional counts, citations, MNCS, and local h-index
- source productivity and local h-, g-, m-index and MNCS rankings, with the notebook's composite and prestige-versus-efficiency figures
- country-level full-counted production, SCP/MCP collaboration shares, total citations, and internal MNCS rankings
- advanced country citation distribution, productivity-impact matrix, and weighted international collaboration topology
- click-to-open country case studies with temporal dashboards and statistical field-guide exports
- final corpus summary plus advanced article, author, source, Bradford, hot-paper, and collaboration-impact outputs
- most-cited articles, recent highly cited papers, Bradford scattering, and team-size impact
- country productivity, collaboration, impact, and temporal tables
- Global and EU-only institutional networks for All, MCP, and SCP records
- optional topic-level institutional collaboration networks after LDA modeling
- one-click background execution from ingestion through six institutional community visualizations, with a consolidated non-nested ZIP package
- unigram, bigram, trigram, quadgram, LDA/NMF evaluation, topic-assignment, and topic-evolution tables
- CSV, Excel, 600-DPI PNG, vector SVG/PDF, and complete ZIP exports

The main entry point is:

```python
from chronotome_core import run_chronotome

results = run_chronotome(uploaded_files, config)
```

`results` contains processed data, tables, figures, warnings, metadata, network objects, PRISMA counts, and in-memory export files.

## Notebook assumptions retained

- DOI duplicates retain the most-cited record as the base and fill its missing fields from duplicates.
- Records without DOI are deduplicated by normalized title plus publication year.
- Citation normalization uses the uploaded corpus's mean citations for each publication year; it is not an external field benchmark.
- The collection year and later are excluded by default because those years may be incompletely indexed.
- Country and institution extraction uses semicolon-separated affiliations and comma-separated address components.
- Multi-country publications are MCP; one-country publications are SCP.
- EU network subsets include publications whose detected countries are exclusively EU member states.
- At most 50 institutions per paper are used to construct collaboration pairs by default.
- “Hot papers” means papers from the current year and previous three years, ranked by raw citations.
- Source and country impact rankings default to a minimum of five papers.
- Thematic analysis combines title, abstract, author keywords, and Keywords Plus.

## Not yet supported

- **OpenAlex integration is not implemented yet.**
- No APIs are called to enrich incomplete metadata.
- The app does not replace missing affiliations, abstracts, references, or citation counts.

## Deploy on Streamlit Community Cloud

1. Push this repository to GitHub, including `app.py`, `requirements.txt`, `chronotome_core/`, and `chronotome_core/institutions.json`.
2. In [Streamlit Community Cloud](https://streamlit.io/cloud), create an app from the repository.
3. Set the main file path to `app.py`.
4. Deploy. No secrets or external API keys are needed.

Large exports and dense networks can approach Community Cloud memory/time limits. For those datasets, disable thematic analysis or reduce the number of institutions displayed in network plots.

Analytical figure downloads preserve the notebook styling and filenames. Standard figures are exported as 600-DPI PNG plus vector SVG and PDF; oversized network rasters are safely bounded while SVG/PDF remain resolution-independent. Tables are available as individual CSV files and combined Excel workbooks inside ZIP folders organized into `Plots/` and `Results/`.

For memory safety, oversized raster figures use an adaptive pixel ceiling while retaining their original aspect ratio and layout. Full-resolution SVG and PDF remain the publication masters. The one-click background workflow uses a stricter raster budget, streams outputs stage by stage, and keeps only its final archive and manifest in session memory.
