scholarimpact 0.0.1.dev1__py3-none-any.whl

scholarimpact/__init__.py

@@ -0,0 +1,80 @@
+"""
+ScholarImpact: Citation Analysis and Dashboard Package
+
+A comprehensive tool for analyzing Google Scholar citations with geographic
+and institutional insights, featuring interactive Streamlit dashboards.
+"""
+
+from .core.crawler import CitationCrawler
+from .core.extractor import AuthorExtractor
+from .dashboard.app import Dashboard
+from .data.loader import load_data
+
+# Version handling with setuptools-scm
+try:
+    from ._version import version as __version__
+    from ._version import version_tuple
+except ImportError:
+    # Fallback for development or when _version.py doesn't exist
+    __version__ = "0.0.0+unknown"
+    version_tuple = (0, 0, 0, "unknown", "unknown")
+
+__author__ = "Abhishek Tiwari"
+__email__ = "schoscholarimpact@abhishek-tiwari.com"
+
+
+# Main convenience functions
+def extract_author(scholar_id, **kwargs):
+    """Extract author publications from Google Scholar."""
+    extractor = AuthorExtractor()
+    return extractor.extract(scholar_id, **kwargs)
+
+
+def crawl_citations(url_or_data, **kwargs):
+    """Crawl citations from Google Scholar."""
+    crawler = CitationCrawler(**kwargs)
+    return crawler.crawl_all_citations(url_or_data)
+
+
+def create_dashboard(data_dir, **kwargs):
+    """Create a Streamlit dashboard for citation analysis."""
+    return Dashboard(data_dir=data_dir, **kwargs)
+
+
+# Quick start function
+def quick_analysis(scholar_id, openalex_email=None, launch_dashboard=True, data_dir="./data"):
+    """Complete analysis pipeline from Scholar ID to dashboard."""
+    import os
+
+    # Set default data directory
+    os.makedirs(data_dir, exist_ok=True)
+
+    # Extract author data
+    print(f"Extracting author data for {scholar_id}...")
+    author_data = extract_author(scholar_id, output_dir=data_dir)
+
+    # Crawl citations
+    print("Crawling citations...")
+    citation_data = crawl_citations(f"{data_dir}/author.json", openalex_email=openalex_email)
+
+    # Create and optionally launch dashboard
+    print("Creating dashboard...")
+    dashboard = create_dashboard(data_dir)
+
+    if launch_dashboard:
+        print("Launching dashboard...")
+        dashboard.run()
+
+    return {"author": author_data, "citations": citation_data, "dashboard": dashboard}
+
+
+__all__ = [
+    "CitationCrawler",
+    "AuthorExtractor",
+    "Dashboard",
+    "load_data",
+    "extract_author",
+    "crawl_citations",
+    "create_dashboard",
+    "quick_analysis",
+]

scholarimpact/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.1.dev1'
+__version_tuple__ = version_tuple = (0, 0, 1, 'dev1')

scholarimpact/assets/README.md

@@ -0,0 +1,36 @@
+# ScholarImpact Assets
+
+This directory contains bundled assets for the ScholarImpact package.
+
+## Files
+
+- `config.toml` - Default Streamlit configuration with optimized settings
+- Font files (*.ttf, *.otf, *.woff) - Custom fonts for dashboard theming
+
+## Usage
+
+Assets are automatically copied when using:
+
+```bash
+scholarimpact generate-dashboard
+```
+
+Or programmatically:
+
+```python
+from scholarimpact.assets import copy_streamlit_config, copy_fonts
+
+# Copy config
+copy_streamlit_config('.streamlit/')
+
+# Copy fonts  
+copy_fonts('.streamlit/')
+```
+
+## Adding Custom Assets
+
+To add custom fonts or configurations:
+
+1. Place font files in this directory
+2. Update config.toml as needed
+3. Reinstall package: `pip install -e .`

scholarimpact/assets/__init__.py

@@ -0,0 +1,136 @@
+"""
+Assets module for ScholarImpact package.
+
+Contains bundled configuration files, fonts, and other static assets.
+"""
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from importlib.resources import files
+
+
+def get_asset_path(asset_name: str) -> Optional[Path]:
+    """
+    Get path to bundled asset.
+
+    Args:
+        asset_name: Name of asset file
+
+    Returns:
+        Path to asset or None if not found
+    """
+    try:
+        # Try to get asset from package using importlib.resources
+        assets_pkg = files("scholarimpact.assets")
+        asset_ref = assets_pkg / asset_name
+        if asset_ref.is_file():
+            # Return a Path object that can be used directly
+            return Path(str(asset_ref))
+    except Exception:
+        pass
+
+    # Fallback to local assets
+    assets_dir = Path(__file__).parent
+    asset_file = assets_dir / asset_name
+    if asset_file.exists():
+        return asset_file
+
+    return None
+
+
+def copy_streamlit_config(output_dir: str, config_name: str = "config.toml") -> bool:
+    """
+    Copy bundled Streamlit config to output directory.
+
+    Args:
+        output_dir: Output directory path
+        config_name: Config file name (default: config.toml)
+
+    Returns:
+        True if successful, False otherwise
+    """
+    config_path = get_asset_path(config_name)
+    if not config_path:
+        return False
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Extract just the filename if config_name has a path
+        target_name = Path(config_name).name
+        shutil.copy2(config_path, output_path / target_name)
+        return True
+    except Exception:
+        return False
+
+
+def copy_fonts(output_dir: str) -> int:
+    """
+    Copy bundled fonts and license files to static directory.
+
+    Args:
+        output_dir: Output directory path (should be .streamlit directory)
+
+    Returns:
+        Number of files copied (fonts + licenses)
+    """
+    assets_dir = Path(__file__).parent
+    fonts_dir = assets_dir / "fonts"
+
+    # Look for font files and license files in the fonts subdirectory
+    font_files = []
+    license_files = []
+    if fonts_dir.exists():
+        font_files = (
+            list(fonts_dir.glob("*.ttf"))
+            + list(fonts_dir.glob("*.otf"))
+            + list(fonts_dir.glob("*.woff*"))
+        )
+        license_files = list(fonts_dir.glob("*.txt"))  # License files
+
+    if not font_files and not license_files:
+        return 0
+
+    # Create static directory structure
+    output_path = Path(output_dir)
+    if output_path.name == ".streamlit":
+        # Create static at parent level (alongside .streamlit)
+        static_dir = output_path.parent / "static"
+    else:
+        # Fallback: create static at output directory level
+        static_dir = output_path.parent / "static"
+    static_dir.mkdir(parents=True, exist_ok=True)
+
+    copied = 0
+
+    # Copy font files to static directory
+    for font_file in font_files:
+        try:
+            shutil.copy2(font_file, static_dir / font_file.name)
+            copied += 1
+        except Exception:
+            continue
+
+    # Copy license files to static directory
+    for license_file in license_files:
+        try:
+            shutil.copy2(license_file, static_dir / license_file.name)
+            copied += 1
+        except Exception:
+            continue
+
+    return copied
+
+
+def list_assets() -> list:
+    """
+    List all available bundled assets.
+
+    Returns:
+        List of asset file names
+    """
+    assets_dir = Path(__file__).parent
+    return [f.name for f in assets_dir.iterdir() if f.is_file() and f.name != "__init__.py"]

scholarimpact/assets/fonts/OFL-SpaceGrotesk.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

scholarimpact/assets/fonts/OFL-SpaceMono.txt

@@ -0,0 +1,93 @@
+Copyright 2016 The Space Mono Project Authors (https://github.com/googlefonts/spacemono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

scholarimpact/assets/streamlit/config.toml

@@ -0,0 +1,55 @@
+[server]
+enableStaticServing = true
+
+[[theme.fontFaces]]
+family = "SpaceGrotesk"
+url = "app/static/SpaceGrotesk-VariableFont_wght.ttf"
+
+[[theme.fontFaces]]
+family = "SpaceMono"
+url = "app/static/SpaceMono-Bold.ttf"
+style = "normal"
+weight = 700
+
+[[theme.fontFaces]]
+family = "SpaceMono"
+url = "app/static/SpaceMono-BoldItalic.ttf"
+style = "italic"
+weight = 700
+
+[[theme.fontFaces]]
+family = "SpaceMono"
+url = "app/static/SpaceMono-Italic.ttf"
+style = "italic"
+weight = 400
+
+[[theme.fontFaces]]
+family = "SpaceMono"
+url = "app/static/SpaceMono-Regular.ttf"
+style = "normal"
+weight = 400
+
+[theme]
+primaryColor = "#cb785c"
+backgroundColor = "#fdfdf8"
+secondaryBackgroundColor = "#ecebe3"
+textColor = "#3d3a2a"
+linkColor = "#3d3a2a"
+borderColor = "#d3d2ca"
+showWidgetBorder = true
+baseRadius = "0.75rem"
+buttonRadius = "full"
+font = "SpaceGrotesk"
+headingFontWeights = [600,500,500,500,500,500]
+headingFontSizes = ["3rem", "2rem"]
+codeFont = "SpaceMono"
+codeFontSize = ".75rem"
+codeBackgroundColor = "#ecebe4"
+showSidebarBorder = true
+chartCategoricalColors = ["#0ea5e9", "#059669", "#fbbf24"]
+
+[theme.sidebar]
+backgroundColor = "#f0f0ec"
+secondaryBackgroundColor = "#ecebe3"
+headingFontSizes = ["1.6rem", "1.4rem", "1.2rem"]
+dataframeHeaderBackgroundColor = "#e4e4e0"

scholarimpact/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI module for ScholarImpact."""
+
+from .main import cli
+
+__all__ = ["cli"]

scholarimpact/cli/commands/__init__.py

@@ -0,0 +1,5 @@
+"""CLI commands for ScholarImpact."""
+
+from . import crawl, dashboard, extract, generate
+
+__all__ = ["extract", "crawl", "dashboard", "generate"]

scholarimpact/cli/commands/crawl.py

@@ -0,0 +1,115 @@
+"""Crawl citations command for CLI."""
+
+import json
+from pathlib import Path
+
+import click
+
+from ...core.crawler import CitationCrawler
+
+
+@click.command(name="crawl-citations")
+@click.argument("author_json")
+@click.option("--openalex-email", help="OpenAlex email for enhanced data")
+@click.option("--max-citations", type=int, help="Maximum citations per paper")
+@click.option(
+    "--delay-min", default=5.0, type=float, help="Minimum delay between requests (default: 5.0)"
+)
+@click.option(
+    "--delay-max", default=10.0, type=float, help="Maximum delay between requests (default: 10.0)"
+)
+@click.option(
+    "--delay-between-articles-min",
+    default=16.0,
+    type=float,
+    help="Minimum delay between articles (default: 16.0)",
+)
+@click.option(
+    "--delay-between-articles-max",
+    default=22.0,
+    type=float,
+    help="Maximum delay between articles (default: 22.0)",
+)
+@click.option("--output-dir", help="Output directory (defaults to author.json directory)")
+def crawl_citations(
+    author_json,
+    openalex_email,
+    max_citations,
+    delay_min,
+    delay_max,
+    delay_between_articles_min,
+    delay_between_articles_max,
+    output_dir,
+):
+    """Crawl citations for publications in author.json file."""
+
+    click.echo(f"Loading author data from: {author_json}")
+
+    # Load author data
+    try:
+        with open(author_json, "r", encoding="utf-8") as f:
+            author_data = json.load(f)
+    except FileNotFoundError:
+        raise click.ClickException(f"Author file not found: {author_json}")
+    except json.JSONDecodeError:
+        raise click.ClickException(f"Invalid JSON in author file: {author_json}")
+
+    # Determine output directory
+    if not output_dir:
+        output_dir = str(Path(author_json).parent)
+
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+    # Get articles from author data
+    articles = author_data.get("articles", [])
+    if not articles:
+        click.echo("No articles found in author data")
+        return
+
+    click.echo(f"Found {len(articles)} articles to process")
+
+    # Initialize crawler
+    delay_range = (delay_min, delay_max)
+    crawler = CitationCrawler(delay_range=delay_range, openalex_email=openalex_email)
+
+    # Process each article
+    processed = 0
+    skipped = 0
+    errors = 0
+
+    with click.progressbar(articles, label="Crawling citations") as article_bar:
+        for article in article_bar:
+            cites_id = article.get("cites_id")
+            if not cites_id:
+                skipped += 1
+                continue
+
+            # Check if already processed
+            output_file = Path(output_dir) / f"cites-{cites_id.replace(',', '_')}.json"
+            if output_file.exists():
+                skipped += 1
+                continue
+
+            try:
+                # Crawl citations
+                citations = crawler.crawl_all_citations(
+                    cites_id, max_pages=None  # max_citations is handled differently
+                )
+
+                # Save citations to file
+                if citations:
+                    with open(output_file, "w", encoding="utf-8") as f:
+                        json.dump(citations, f, ensure_ascii=False, indent=2)
+
+                processed += 1
+
+            except Exception as e:
+                click.echo(f"\nError processing {article.get('title', 'Unknown')}: {e}")
+                errors += 1
+
+    # Summary
+    click.echo(f"\n Citation crawling complete!")
+    click.echo(f"   Processed: {processed}")
+    click.echo(f"   Skipped (no ID or exists): {skipped}")
+    if errors > 0:
+        click.echo(f"   Errors: {errors}")