Metadata-Version: 2.4
Name: scholarimpact
Version: 0.0.17rc221779154021
Summary: A bibliometric tool to analyse, visualise, and share your research impact, output and scholarly influence using Google Scholar and OpenAlex data
Author-email: Abhishek Tiwari <abhishek@abhishek-tiwari.com>
License: MIT
Project-URL: Homepage, https://github.com/abhishektiwari/scholarimpact
Project-URL: Repository, https://github.com/abhishektiwari/scholarimpact.git
Project-URL: Issues, https://github.com/abhishektiwari/scholarimpact/issues
Keywords: citations,google-scholar,research,dashboard,analysis,academic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit>=1.28.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: plotly>=5.14.0
Requires-Dist: click>=8.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: beautifulsoup4>=4.11.0
Requires-Dist: selenium>=4.10.0
Requires-Dist: scholarly>=1.7.11
Requires-Dist: pyalex>=0.21
Requires-Dist: pycountry>=22.0.0
Requires-Dist: geopy>=2.4.1
Requires-Dist: tqdm>=4.65.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Provides-Extra: build
Requires-Dist: build>=0.8.0; extra == "build"
Requires-Dist: twine>=4.0.0; extra == "build"
Requires-Dist: setuptools-scm>=6.2.0; extra == "build"
Dynamic: license-file

# _ScholarImpact_
A bibliometric tool to analyse, visualise, and share your research impact, output and scholarly influence using Google Scholar and OpenAlex data.

![GitHub Release](https://img.shields.io/github/v/release/abhishektiwari/scholarimpact)
![GitHub Actions Test Workflow Status](https://img.shields.io/github/actions/workflow/status/abhishektiwari/scholarimpact/test.yml?label=tests)
![PyPI - Version](https://img.shields.io/pypi/v/scholarimpact)
![Python Wheels](https://img.shields.io/pypi/wheel/scholarimpact)
![Python Versions](https://img.shields.io/pypi/pyversions/scholarimpact?logo=python&logoColor=white)
![GitHub last commit](https://img.shields.io/github/last-commit/abhishektiwari/scholarimpact)
![PyPI - Status](https://img.shields.io/pypi/status/scholarimpact)
![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/abhishektiwari/scholarimpact/total?label=GitHub%20Downloads)
![PyPI Downloads](https://img.shields.io/pepy/dt/scholarimpact?label=PyPI%20Downloads)

For each article under your Google Scholar Profile, **_ScholarImpact_** provides comprehensive analysis including: (1) total citation count with percentile rankings, (2) unique citing authors and institutions, (3) geographic distribution of citations by country, (4) top Scimago-ranked institutions citing your work with prestige metrics, (5) notable citations—the most influential articles (top 10%) that cite your work, (6) research domain analysis with field diversity scoring, (7) citation trends over time, (8) interdisciplinary impact metrics including patent citations, Wikipedia mentions, and social media engagement, and (9) customizable dashboard with widget visibility control and theme personalization.

![Example Dashboard](https://static.abhishek-tiwari.com/scholarimpact/example-dashboard-v4.png)

![Example Dashboard](https://static.abhishek-tiwari.com/scholarimpact/geo-trends-v4.png)

![Research Domains Analysis](https://static.abhishek-tiwari.com/scholarimpact/research-domains-v4.png)

## Workflow Overview

ScholarImpact follows a three-stage workflow to analyze and visualize your research impact:

### Stage 1: Extract & Enrich Author Data
Extract your publication list from Google Scholar and enrich with OpenAlex and Altmetric metrics:

```mermaid
flowchart LR
    A["🎓 Google Scholar<br/>Profile"] --> B["📄 Your Articles<br/>extraction"]
    B --> C["🔗 OpenAlex API<br/>(optional enrichment)"]
    B --> D["📊 Altmetric API<br/>(optional enrichment)"]
    C --> E["✨ Enhanced<br/>Scholar Data"]
    D --> E
    
    style A fill:#0ea5e9,stroke:#0ea5e9,color:#ffffff
    style B fill:#ecebe3,stroke:#3d3a2a
    style C fill:#059669,stroke:#059669,color:#ffffff
    style D fill:#059669,stroke:#059669,color:#ffffff
    style E fill:#cb785c,stroke:#cb785c,color:#ffffff
```

### Stage 2: Crawl & Analyze Citations
Retrieve citing articles and enrich with detailed author, institutional, and ranking data:

```mermaid
flowchart LR
    A["✨ Enhanced<br/>Scholar Data"] --> B["🔍 Citing Articles<br/>crawl from Google Scholar"]
    B --> C["🔗 OpenAlex API<br/>enrichment"]
    B --> D["👤 Google Scholar<br/>Author Profiles"]
    C --> E["🏆 Enhanced<br/>Citation Data"]
    D --> E
    C -.-> F["🌍 Affiliations<br/>& Countries"]
    C -.-> G["🔬 Research<br/>Domains"]
    C -.-> I["🎓 Scimago<br/>Institution Ranking"]
    D -.-> H["✓ Verified<br/>Institutions"]
    F --> E
    G --> E
    H --> E
    I --> E
    
    style A fill:#cb785c,stroke:#cb785c,color:#ffffff
    style B fill:#ecebe3,stroke:#3d3a2a
    style C fill:#059669,stroke:#059669,color:#ffffff
    style D fill:#fbbf24,stroke:#fbbf24,color:#3d3a2a
    style E fill:#cb785c,stroke:#cb785c,color:#ffffff
    style I fill:#059669,stroke:#059669,color:#ffffff
```

### Stage 3: Visualize & Share Impact
Interactive Streamlit dashboard with customizable widgets and comprehensive analytics:

```mermaid
flowchart LR
    A["🏆 Enhanced<br/>Citation Data"] --> B["📊 Streamlit Dashboard"]
    B --> C["📈 Citation Metrics"]
    B --> D["🌍 Geographic<br/>Distribution"]
    B --> E["🏫 Institutions &<br/>Rankings"]
    B --> F["⭐ Notable<br/>Citations"]
    B --> G["🔬 Research<br/>Domains"]
    B --> H["📱 Alt Metrics &<br/>Social Impact"]
    
    style A fill:#cb785c,stroke:#cb785c,color:#ffffff
    style B fill:#cb785c,stroke:#cb785c,color:#ffffff
    style C fill:#ecebe3,stroke:#3d3a2a
    style D fill:#ecebe3,stroke:#3d3a2a
    style E fill:#ecebe3,stroke:#3d3a2a
    style F fill:#ecebe3,stroke:#3d3a2a
    style G fill:#ecebe3,stroke:#3d3a2a
    style H fill:#ecebe3,stroke:#3d3a2a
```

## Quick Start

### Prerequisites

Install 
```bash
pip install scholarimpact
```

## Caution
This system is designed for academic research purposes and personal usage. Please use responsibly and in accordance with Google Scholar, OpenAlex, Altmetric terms of services with appropriate attribution.

## Breaking Changes (v0.0.13+)

### API Key Requirements
As of version v0.0.13+, both OpenAlex and Altmetric now require API keys. This is a breaking change from previous versions.

#### What Changed:

**OpenAlex:**
- **Previous:** Email-based authentication with `--openalex-email` flag
- **Current:** API key-based authentication with `--openalex-api-key` option
- **Impact:** OpenAlex enrichment now requires an API key

**Altmetric:**
- **Previous:** Altmetric worked with just `--use-altmetric` flag (public API)
- **Current:** Altmetric requires API key with `--altmetric-api-key` option
- **Impact:** Altmetric enrichment now requires an explicit API key

## Getting API Keys

### OpenAlex API Key

OpenAlex data is and will remain available at no cost. The API is a freemium service:
- **$1 free credit daily** - sufficient for most research use cases
- **Pay as you go** after daily limit - only charged for usage beyond free tier
- **No API key required** for the free tier (limited rate)
- **Free API key** - create an account in 30 seconds for higher rate limits

**To get your OpenAlex API key:**
1. Go to [openalex.org/settings/api](https://openalex.org/settings/api)
2. Create a free account (takes 30 seconds)
3. Copy your API key from the settings page
4. Use it with the `--openalex-api-key` flag in ScholarImpact commands

**Documentation:** [OpenAlex API Authentication](https://developers.openalex.org/api-reference/authentication)

### Altmetric API Key

Altmetric offers free access for university scientometric researchers through their Details Page API - Counts Only, which is optimized for querying publication identifiers.

**Features:**
- Query by DOI, PMID, or other identifiers
- Returns publication attention metrics (citations, social media mentions, etc.)
- Free access available for university researchers

**To get Altmetric API key:**
1. Visit [Altmetric Research Access](https://www.altmetric.com/our-audience/researchers/research-access/)
2. Complete the researcher access request form
3. Specify your institution and research project
4. Altmetric will provide your API key
5. Use it with the `--altmetric-api-key` flag in ScholarImpact commands

**Documentation:** [Altmetric Details Page API - Counts Only](https://help.altmetric.com/en/articles/9806465)

**Note:** Free university researcher access is available through the research access program. Contact Altmetric for details on eligibility and access.

## Step-by-Step Guide

### Option 1: For Deployment (Recommended)

This approach creates a standalone project suitable for deployment to Streamlit Cloud or local development.

#### Step 1: Generate Dashboard Project

```bash
# Generate a dashboard project
scholarimpact generate-dashboard --output-dir my-research-dashboard --name app.py

# Navigate to the generated folder
cd my-research-dashboard
```

This creates a complete project structure with `app.py`, `requirements.txt`, `.streamlit/config.toml`, and a `static` folder containing fonts used by default theme.

#### Step 2: Extract Author Publications

```bash
# Extract your publications from Google Scholar
scholarimpact extract-author "YOUR_SCHOLAR_USER_ID"

# With OpenAlex API key (required for OpenAlex enrichment and Altmetric)
scholarimpact extract-author "YOUR_SCHOLAR_USER_ID" --openalex-api-key YOUR_API_KEY

# Or use full URL
scholarimpact extract-author "https://scholar.google.com/citations?user=YOUR_SCHOLAR_USER_ID" --openalex-api-key YOUR_API_KEY
```

This creates `data/author.json` with your publication list. Add `--openalex-api-key` to enrich with OpenAlex and Altmetric metrics (API key required).

#### Step 3: Crawl Citation Data

```bash
# Crawl citations with OpenAlex enrichment (API key required)
scholarimpact crawl-citations data/author.json --openalex-api-key YOUR_API_KEY
```

This creates `data/cites-{ID}.json` files for each publication.

#### Step 4: Test Locally

```bash
# Run the dashboard locally
streamlit run app.py

# Or alternatively
python app.py
```

Open `http://localhost:8501`to view your dashboard.

#### Step 5: Push your changes to a Github Repository

```bash
# Initialize git repository
git init
git add .
git commit -m "Initial research dashboard"

# Create GitHub repository and push
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
git branch -M main
git push -u origin main
```

#### Step 6: Deploy on Streamlit Cloud

1. Go to [share.streamlit.io](https://share.streamlit.io)
2. Click "New app"
3. Connect your GitHub account
4. Select your repository and branch
5. Set main file path: `app.py` (or your custom name)
6. Click "Deploy"

#### Step 7: Project Structure for Deployment

Your repository should contain:
```
my-research-dashboard/
├── app.py                    # Main dashboard file
├── requirements.txt          # Python dependencies
├── Dockerfile                # Docker container configuration
├── docker-compose.yml        # Docker Compose orchestration (optional)
├── .streamlit/
│   └── config.toml          # Streamlit configuration
├── static/                  # Static assets (fonts from scholarimpact/assets/fonts)
│   ├── SpaceGrotesk-SemiBold.ttf
│   ├── SpaceGrotesk-VariableFont_wght.ttf
│   ├── SpaceMono-Regular.ttf
│   ├── SpaceMono-Bold.ttf
│   ├── SpaceMono-Italic.ttf
│   ├── SpaceMono-BoldItalic.ttf
│   └── OFL-*.txt           # Font licenses
└── data/
    ├── author.json                           # Author profile data
    ├── cites-*.json                          # Citation data files
    └── ScimagoIR 2026 - Overall Rank.csv     # Scimago Institutions Ranking (for institution prestige metrics)
```

#### Step 8: Docker Deployment (Alternative to Streamlit Cloud)

The generated project includes `Dockerfile` and `docker-compose.yml` for containerized deployment:

**Using Docker Compose (Recommended):**
```bash
# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down
```

**Using Docker directly:**
```bash
# Build the image
docker build -t scholarimpact-dashboard .

# Run the container
docker run -p 8501:8501 scholarimpact-dashboard

# Or run in background
docker run -d -p 8501:8501 scholarimpact-dashboard
```

Access your dashboard at `http://localhost:8501`

#### Step 9: Update Data

To update citation data:

1. Re-run step-2 and step-3 to update data files
2. Commit changes and push them to your GitHub repository
3. For Streamlit Cloud: automatic restart on push
4. For Docker: rebuild and redeploy the container

#### Tips for Streamlit Cloud Deployment

- Keep data files under 100MB each for optimal performance
- Use `.gitignore` to exclude unnecessary files
- Set secrets in Streamlit Cloud settings if needed
- Monitor app logs in Streamlit Cloud dashboard for debugging

#### Tips for Docker Deployment

- Resource limits are configured in `docker-compose.yml` (1 CPU, 512MB RAM)
- Use environment variables for configuration (see `docker-compose.yml`)
- For production, update the `x-ports` section with your domain
- Mount data volume for persistent storage: `docker run -v ./data:/app/data -p 8501:8501 scholarimpact-dashboard`

### Option 2: For Quick Local Testing

This approach is fastest for local analysis without deployment needs.

#### Step 1: Extract Author Publications

```bash
# Extract publications directly
scholarimpact extract-author "YOUR_SCHOLAR_USER_ID"
```

#### Step 2: Crawl Citation Data

```bash
# Crawl citations with OpenAlex enrichment (API key required)
scholarimpact crawl-citations data/author.json --openalex-api-key YOUR_API_KEY
```

#### Step 3: Launch Dashboard

```bash
# Run dashboard directly
ScholarImpact
```

The dashboard opens at `http://localhost:8501`.

## CLI Options Reference

### `scholarimpact extract-author` Command

Extract author publications from Google Scholar with OpenAlex and Altmetric enrichment:

```bash
scholarimpact extract-author [OPTIONS] SCHOLAR_ID
```

Arguments:
- `SCHOLAR_ID`: Google Scholar author ID or full profile URL

Options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--max-papers N` | int | None | Maximum number of papers to analyze (default: all) |
| `--delay X` | float | 2.0 | Delay between requests in seconds |
| `--output-dir DIR` | str | ./data | Output directory for author.json |
| `--output-file FILE` | str | None | Custom output file path (overrides output-dir) |
| `--openalex-api-key KEY` | str | None | API key for OpenAlex (enables OpenAlex enrichment) |
| `--altmetric-api-key KEY` | str | None | API key for Altmetric (enables Altmetric enrichment) |

OpenAlex enrichment adds (all fields prefixed with `openalex_`):
- `openalex_ids`: Object containing all identifiers:
  - `openalex`: OpenAlex work URL
  - `doi`: Digital Object Identifier URL
  - `mag`: Microsoft Academic Graph ID
  - `pmid`: PubMed ID URL
- `openalex_type`: Publication type (article, book, etc.)
- `openalex_citation_normalized_percentile`: Percentile ranking of citations
- `openalex_cited_by_percentile_year`: Citation percentile by year
- `openalex_fwci`: Field-Weighted Citation Impact
- `openalex_cited_by_count`: OpenAlex citation count
- `openalex_primary_topic`: Main research topic
- `openalex_domain`, `openalex_field`, `openalex_subfield`: Hierarchical classification

Altmetric enrichment adds (all fields prefixed with `altmetric_`):
- `altmetric_score`: Overall Altmetric attention score
- `altmetric_cited_by_wikipedia_count`: Citations in Wikipedia
- `altmetric_cited_by_patents_count`: Citations in patents
- `altmetric_cited_by_accounts_count`: Social media accounts mentioning
- `altmetric_cited_by_posts_count`: Social media posts mentioning
- `altmetric_scopus_subjects`: Scopus subject classifications
- `altmetric_readers`: Reader counts by platform (Mendeley, CiteULike, etc.)
- `altmetric_readers_count`: Total reader count
- `altmetric_images`: Altmetric badge images (small, medium, large)
- `altmetric_details_url`: Link to detailed Altmetric page

Examples:
```bash
# Basic usage (Google Scholar only, no enrichment)
scholarimpact extract-author "ABC123DEF"

# With OpenAlex API key for enrichment
scholarimpact extract-author "ABC123DEF" --openalex-api-key YOUR_OPENALEX_KEY

# With both OpenAlex and Altmetric enrichment
scholarimpact extract-author "ABC123DEF" --openalex-api-key YOUR_OPENALEX_KEY --altmetric-api-key YOUR_ALTMETRIC_KEY

# Limit to first 20 papers with 3-second delays
scholarimpact extract-author "ABC123DEF" --openalex-api-key YOUR_OPENALEX_KEY --max-papers 20 --delay 3

# Custom output file with OpenAlex API key
scholarimpact extract-author "ABC123DEF" --output-file data/my_author.json --openalex-api-key YOUR_OPENALEX_KEY

# Full URL format
scholarimpact extract-author "https://scholar.google.com/citations?user=ABC123DEF" --openalex-api-key YOUR_OPENALEX_KEY
```

### `scholarimpact list-articles` Command

List all articles from author.json with their cites_id and title:

```bash
scholarimpact list-articles [OPTIONS] AUTHOR_JSON
```

Arguments:
- `AUTHOR_JSON`: Path to author.json file containing publications

Options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--format FORMAT` | str | table | Output format: `table` or `json` |

Examples:
```bash
# List articles in table format
scholarimpact list-articles data/author.json

# List articles in JSON format
scholarimpact list-articles data/author.json --format json

# Copy cites_id from table output and use it to crawl specific article
scholarimpact crawl-citations data/author.json --cites-id "ABC123,XYZ789"
```

The table shows:
- `#`: Article index (0-based)
- `Cites ID`: Google Scholar citation ID (use with `--cites-id` flag)
- `Title`: Article title
- `Year`: Publication year
- `Cit`: Total citations count

### `scholarimpact crawl-citations` Command

Crawl citations with OpenAlex integration:

```bash
scholarimpact crawl-citations [OPTIONS] AUTHOR_JSON
```

Arguments:
- `AUTHOR_JSON`: Path to author.json file containing publications

Options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--openalex-api-key KEY` | str | None | API key for OpenAlex (required to use OpenAlex) |
| `--max-citations N` | int | None | Maximum citations per paper |
| `--delay-min X` | float | 5.0 | Minimum delay between requests (seconds) |
| `--delay-max Y` | float | 10.0 | Maximum delay between requests (seconds) |
| `--output-dir DIR` | str | None | Output directory (defaults to author.json directory) |
| `--cites-id CITES_ID` | str | None | Crawl only a specific article by cites_id (auto-enables `--force`) |
| `--force` | flag | False | Force re-crawl of articles when citation counts don't match expectations |

**Smart Skipping Logic:**

The crawler compares citation counts in `author.json` with counts in the crawled citation files:

1. **Citations match** (e.g., 10 in both):
   - Skip by default
   - Skip with `--force` (data is up to date)
   - Message: `Citation count unchanged - 10 citations in author.json, 10 citations in file`

2. **New citations found** (e.g., 4 in author.json, 3 in file):
   - **Always crawl** to get the new citation (even without `--force`)
   - Message: `Citation count increased - 4 citations in author.json, 3 in file (crawling to get new citations)`

3. **File has more citations** (e.g., 3 in author.json, 4 in file) [unusual]:
   - Skip by default
   - Crawl with `--force` to refresh
   - Message: `File has more citations - 3 in author.json, 4 in file (use --force to recrawl)`

**Special behavior with `--cites-id`:**
- Always **crawls** the specified article (ignores existing file)
- Automatically enables `--force` mode
- Gets fresh citation data regardless of file existence or citation count
- Useful for testing, re-crawling specific articles, or updating individual articles

**When to use `--force`:**
- Re-crawl all articles when citation counts seem out of sync
- Refresh corrupted citation files
- Override automatic skipping for articles with matching counts (if you want fresh data for all articles)

Examples:
```bash
# Basic usage - skips articles with matching citation counts, crawls new citations
scholarimpact crawl-citations data/author.json --openalex-api-key YOUR_API_KEY

# Crawl only a single article (always gets fresh data, auto-enables force)
scholarimpact crawl-citations data/author.json --openalex-api-key YOUR_API_KEY --cites-id "ABC123,XYZ789"

# Force re-crawl articles when citation counts differ or to refresh data
scholarimpact crawl-citations data/author.json --openalex-api-key YOUR_API_KEY --force

# Custom delays
scholarimpact crawl-citations data/author.json --openalex-api-key YOUR_API_KEY --delay-min 3 --delay-max 8

# Custom output directory
scholarimpact crawl-citations data/author.json --openalex-api-key YOUR_API_KEY --output-dir custom_data

# Limit citations per paper
scholarimpact crawl-citations data/author.json --openalex-api-key YOUR_API_KEY --max-citations 100
```

### `scholarimpact add-rankings` Command

Add Scimago Institution Ranking to citation data for dashboard visualization:

```bash
scholarimpact add-rankings [OPTIONS] CITATIONS_JSON
```

Arguments:
- `CITATIONS_JSON`: Path to citations JSON file (from `crawl-citations` command)

Options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--rankings-file FILE` | str | ./data/ScimagoIR2026-OverallRank.csv | Path to Scimago rankings CSV file |

**Download Instructions**

To use the institution ranking features in ScholarImpact, you need to download the Scimago IR data:

1. **Visit Scimago IR Portal** [Scimago IR](https://www.scimagoir.com/rankings.php)
2. **Select Data**: Choose "Overall Rank" for global research rankings ([Direct Link](https://www.scimagoir.com/getdata.php?ranking=Overall&area=&sector=&country=&year=2026&top=0&format=csv&type=download))
3. **Download CSV**: Download the CSV file with your preferred settings
4. **Place File**: Save the file as `ScimagoIR2026-OverallRank.csv` in the `data/` directory

**Direct Download Link** (Overall Rank 2026):
```
https://www.scimagoir.com/getdata.php?ranking=Overall&area=&sector=&country=&year=2026&top=0&format=csv&type=download
```

**What it does:**
- Reads citation JSON file from `crawl-citations`
- Matches each citing institution against Scimago 2026 global rankings (15,000+ institutions)
- Adds `institution_rank` (integer 1-15000+) and `institution_rank_weight` (0.0-1.0) to each citing author
- Updates the citations file in place
- Displays enrichment summary with statistics

**Data Structure After Enrichment:**
Each citing author now includes ranking information:
```json
{
  "citing_authors_details": [
    {
      "name": "Oliver Meyer",
      "institution_display_name": "Arizona State University",
      "institution_rank": 186,           // Scimago global rank
      "institution_rank_weight": 0.74,   // Normalized 0-1
      "country": "US",
      "openalex_author_id": "..."
    }
  ]
}
```

Examples:
```bash
# Add rankings using default location (./data/ScimagoIR2026-OverallRank.csv)
scholarimpact add-rankings data/cites-12862953873024122861.json

# Specify custom rankings file location
scholarimpact add-rankings data/cites-12862953873024122861.json --rankings-file /path/to/rankings.csv

# Bulk process all citation files
for file in data/cites-*.json; do
  scholarimpact add-rankings "$file"
done
```

### `ScholarImpact` Command

Launch the interactive dashboard:

```bash
ScholarImpact [OPTIONS]
```

Options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--port N` | int | 8501 | Port to run the dashboard on |
| `--address ADDR` | str | localhost | Address to bind the server to |
| `--data-dir DIR` | str | ./data | Directory containing citation data files |

Examples:
```bash
# Basic usage
ScholarImpact

# Custom port
ScholarImpact --port 8502

# External access
ScholarImpact --address 0.0.0.0

# Different data directory
ScholarImpact --data-dir custom_data
```

### `scholarimpact quick-start` Command

Complete analysis pipeline from Scholar ID to dashboard:

```bash
scholarimpact quick-start [OPTIONS] SCHOLAR_ID
```

Arguments:
- `SCHOLAR_ID`: Google Scholar author ID or full profile URL

Options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--openalex-api-key KEY` | str | None | OpenAlex API key (enables OpenAlex enrichment) |
| `--altmetric-api-key KEY` | str | None | Altmetric API key (enables Altmetric enrichment) |
| `--output-dir DIR` | str | ./data | Output directory for all data |
| `--launch-dashboard/--no-dashboard` | flag | True | Launch dashboard after analysis |

Examples:
```bash
# Complete pipeline with OpenAlex enrichment
scholarimpact quick-start "ABC123DEF" --openalex-api-key YOUR_OPENALEX_KEY

# Complete pipeline with both OpenAlex and Altmetric enrichment
scholarimpact quick-start "ABC123DEF" --openalex-api-key YOUR_OPENALEX_KEY --altmetric-api-key YOUR_ALTMETRIC_KEY

# Skip dashboard launch
scholarimpact quick-start "ABC123DEF" --no-dashboard

# Custom output directory with enrichment
scholarimpact quick-start "ABC123DEF" --output-dir results --openalex-api-key YOUR_OPENALEX_KEY
```

### `scholarimpact generate-dashboard` Command

Generate a standalone dashboard project for deployment to Streamlit Cloud or Docker:

```bash
scholarimpact generate-dashboard [OPTIONS]
```

Options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--output-dir DIR` | str | . | Output directory for generated files |
| `--name FILE` | str | my_dashboard.py | Name of the dashboard file |
| `--data-dir DIR` | str | ./data | Data directory path for dashboard |
| `--title TEXT` | str | My Citation Dashboard | Dashboard title |

Examples:
```bash
# Generate dashboard in current directory
scholarimpact generate-dashboard

# Custom output directory and title
scholarimpact generate-dashboard --output-dir my-project --title "Research Impact Analysis"

# Custom data directory location
scholarimpact generate-dashboard --data-dir ../citation_data --name app.py
```

This command generates:

- A dashboard Python file (default: `my_dashboard.py`)
- `Dockerfile` for containerization (Python 3.13-slim base)
- `docker-compose.yml` for orchestration with resource limits
- `.streamlit/config.toml` with theme configuration
- `requirements.txt` for dependencies
- `static` folder containing fonts used by default theme

The generated project is ready for deployment to:
- **Streamlit Cloud**: Push to GitHub and deploy via share.streamlit.io
- **Docker**: Build and run locally or on any Docker-compatible server
- **Docker Compose**: Orchestrate with resource limits and environment configuration

## Customize Your Dashboard

Customize your dashboard's appearance and content by editing `.streamlit/config.toml`. All changes take effect when you refresh the dashboard - no restart needed!

### Hide/Show Dashboard Sections (Widgets)

Control which analysis sections appear on your dashboard using the `[widgets]` section:

```toml
[widgets]
# Hide specific sections using snake_case names
hideWidgets = ["Altmetric_Attention"]
```

**Available Widget Names:**
- `Top_Citing_Countries` - Bar chart of countries with most citations
- `Citation_Distribution_by_Country` - World map showing geographic distribution  
- `Citations_Distribution_by_Year` - Citation trends over time
- `Research_Domain_Analysis` - Analysis of research domains, fields, and subfields
- `Interdisciplinary_Impact_Metrics` - Diversity score, patent citations, domain count
- `Altmetric_Attention` - Social media mentions and public engagement metrics
- `Notable_Citations` - Top 10% most-cited papers citing this work
- `Top_Citing_Institutions` - Scimago-ranked institutions citing this work
- `Detailed_Citations_Table` - Complete paginated table of all citing papers

**Examples:**
```toml
# Show all sections
[widgets]
hideWidgets = []

# Hide Altmetric section
[widgets]
hideWidgets = ["Altmetric_Attention"]

# Hide multiple sections to focus on geographic analysis
[widgets]
hideWidgets = ["Research_Domain_Analysis", "Altmetric_Attention", "Notable_Citations"]
```

### Customize Theme Colors

Modify the `[theme]` section to customize your color scheme. Here are the default colors:

```toml
[theme]
primaryColor = "#cb785c"              # Main accent color
backgroundColor = "#fdfdf8"            # Main background
secondaryBackgroundColor = "#ecebe3"   # Secondary background (sidebars, containers)
textColor = "#3d3a2a"                  # Primary text color
linkColor = "#3d3a2a"                  # Link color
borderColor = "#d3d2ca"                # Border/divider color
codeBackgroundColor = "#ecebe4"        # Code block background
```

### Customize Fonts and Text Sizes

The generated project includes custom fonts (SpaceGrotesk and SpaceMono) in the `static/` folder. Here are the default settings:

```toml
[theme]
font = "SpaceGrotesk"                  # Default font family
codeFont = "SpaceMono"                 # Code block font
codeFontSize = ".75rem"                # Code text size
headingFontSizes = ["3rem", "2rem"]    # H1 and H2 sizes
headingFontWeights = [600,500,500,500,500,500]  # Font weights for headings
```

### Customize Layout and Styling

```toml
[theme]
showWidgetBorder = true                # Show borders around widgets
showSidebarBorder = true               # Show sidebar border
baseRadius = "0.75rem"                 # Corner radius for elements
buttonRadius = "full"                  # Button border radius ("full" = pill-shaped)
chartCategoricalColors = ["#0ea5e9", "#059669", "#fbbf24"]  # Chart colors
```

### Customize Sidebar

```toml
[theme.sidebar]
backgroundColor = "#f0f0ec"            # Sidebar background
secondaryBackgroundColor = "#ecebe3"   # Secondary sidebar background
headingFontSizes = ["1.6rem", "1.4rem", "1.2rem"]  # Heading sizes in sidebar
dataframeHeaderBackgroundColor = "#e4e4e0"  # Table header background
```

## Citation

[![zenodo.17282762](https://zenodo.org/badge/DOI/10.5281/zenodo.17282708.svg)](https://doi.org/10.5281/zenodo.17282708)

If you use ScholarImpact in your research, please cite it as:

```bibtex
@software{tiwari_2025_17282762,
  author       = {Tiwari, Abhishek},
  title        = {ScholarImpact: A Python tool to analyse, visualise, and share individual research impact, output and scholarly influence using bibliometric data},
  month        = oct,
  year         = 2025,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.17282708},
  url          = {https://doi.org/10.5281/zenodo.17282708},
}
```

**APA Format:**
```
Tiwari, A. (2025). ScholarImpact: A Python tool to analyse, visualise, and share individual research impact, output and scholarly influence using bibliometric data. Zenodo. https://doi.org/10.5281/zenodo.17282708
```

**MLA Format:**
```
Tiwari, A. ScholarImpact: A Python tool to analyse, visualise, and share individual research impact, output and scholarly influence using bibliometric data. Zenodo, 7 Oct. 2025, https://doi.org/10.5281/zenodo.17282708.
```
