crossref-local 0.3.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

crossref_local/_cache/viz.py

@@ -0,0 +1,296 @@
+"""Visualization tools for cache analysis.
+
+Provides plotting and network visualization for cached paper collections.
+
+Usage:
+    >>> from crossref_local import cache
+    >>> from crossref_local.cache_viz import plot_year_citations, plot_citation_network
+    >>> # Scatter plot: year vs citations
+    >>> plot_year_citations("epilepsy", output="epilepsy_scatter.png")
+    >>> # Citation network
+    >>> plot_citation_network("epilepsy", output="epilepsy_network.html")
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from . import cache
+
+
+def plot_year_citations(
+    cache_name: str,
+    output: Optional[str] = None,
+    top_n: int = 10,
+    highlight_threshold: Optional[int] = None,
+    figsize: Tuple[int, int] = (10, 6),
+) -> Dict[str, Any]:
+    """Plot year vs citation count scatter plot.
+
+    Helps identify highly cited papers across publication years.
+
+    Args:
+        cache_name: Name of cache to analyze
+        output: Output file path (png/pdf/svg). None for interactive display.
+        top_n: Number of top-cited papers to label
+        highlight_threshold: Citation threshold to highlight (draws horizontal line)
+        figsize: Figure size in inches
+
+    Returns:
+        Dict with plot path and top papers list
+
+    Example:
+        >>> plot_year_citations("epilepsy", output="scatter.png", top_n=5)
+    """
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError:
+        raise ImportError("matplotlib required. Install with: pip install matplotlib")
+
+    papers = cache.load(cache_name)
+
+    # Extract year and citations
+    data = []
+    for p in papers:
+        year = p.get("year")
+        citations = p.get("citation_count", 0)
+        if year and citations is not None:
+            data.append(
+                {
+                    "doi": p.get("doi"),
+                    "title": p.get("title", "")[:50],
+                    "year": year,
+                    "citations": citations,
+                    "journal": p.get("journal", ""),
+                }
+            )
+
+    if not data:
+        return {"error": "No papers with year and citation data"}
+
+    # Sort by citations for top-N
+    data_sorted = sorted(data, key=lambda x: -x["citations"])
+    top_papers = data_sorted[:top_n]
+
+    # Create scatter plot
+    fig, ax = plt.subplots(figsize=figsize)
+
+    years = [d["year"] for d in data]
+    citations = [d["citations"] for d in data]
+
+    ax.scatter(years, citations, alpha=0.5, s=20)
+
+    # Highlight top papers
+    for p in top_papers:
+        ax.annotate(
+            p["title"][:30] + "...",
+            (p["year"], p["citations"]),
+            fontsize=7,
+            alpha=0.8,
+            xytext=(5, 5),
+            textcoords="offset points",
+        )
+
+    # Threshold line
+    if highlight_threshold:
+        ax.axhline(y=highlight_threshold, color="r", linestyle="--", alpha=0.5)
+
+    ax.set_xlabel("Publication Year")
+    ax.set_ylabel("Citation Count")
+    ax.set_title(f"Year vs Citations: {cache_name}")
+    ax.grid(True, alpha=0.3)
+
+    plt.tight_layout()
+
+    if output:
+        plt.savefig(output, dpi=150)
+        plt.close()
+        result_path = output
+    else:
+        plt.show()
+        result_path = None
+
+    return {
+        "output": result_path,
+        "total_papers": len(data),
+        "top_papers": [
+            {
+                "doi": p["doi"],
+                "title": p["title"],
+                "year": p["year"],
+                "citations": p["citations"],
+            }
+            for p in top_papers
+        ],
+    }
+
+
+def plot_citation_network(
+    cache_name: str,
+    output: Optional[str] = None,
+    max_nodes: int = 100,
+    include_external: bool = False,
+) -> Dict[str, Any]:
+    """Generate citation network visualization.
+
+    Creates an interactive HTML network graph showing citation relationships
+    between papers in the cache.
+
+    Args:
+        cache_name: Name of cache to analyze
+        output: Output HTML file path. None returns network data.
+        max_nodes: Maximum papers to include (sorted by citations)
+        include_external: Include referenced papers not in cache
+
+    Returns:
+        Dict with network stats and output path
+
+    Example:
+        >>> plot_citation_network("epilepsy", output="network.html", max_nodes=50)
+    """
+    try:
+        from pyvis.network import Network
+    except ImportError:
+        raise ImportError("pyvis required. Install with: pip install pyvis")
+
+    papers = cache.load(cache_name)
+
+    # Build DOI lookup
+    doi_to_paper = {p["doi"]: p for p in papers if p.get("doi")}
+
+    # Sort by citations and take top N
+    papers_sorted = sorted(papers, key=lambda x: -(x.get("citation_count") or 0))
+    selected = papers_sorted[:max_nodes]
+    selected_dois = {p["doi"] for p in selected if p.get("doi")}
+
+    # Create network
+    net = Network(height="750px", width="100%", bgcolor="#ffffff", font_color="black")
+    net.barnes_hut()
+
+    # Add nodes
+    for p in selected:
+        doi = p.get("doi")
+        if not doi:
+            continue
+
+        title = p.get("title", "No title")[:40]
+        citations = p.get("citation_count", 0)
+        year = p.get("year", "?")
+
+        # Size by citations (log scale)
+        size = 10 + min(citations, 500) ** 0.5 * 2
+
+        net.add_node(
+            doi,
+            label=f"{title}...\n({year})",
+            title=f"{p.get('title', 'No title')}\n{doi}\nCitations: {citations}",
+            size=size,
+            color="#3498db" if citations > 50 else "#95a5a6",
+        )
+
+    # Add edges from references
+    edge_count = 0
+    for p in selected:
+        doi = p.get("doi")
+        refs = p.get("references", [])
+        if not doi or not refs:
+            continue
+
+        for ref in refs:
+            if ref in selected_dois:
+                # Both papers in cache
+                net.add_edge(doi, ref)
+                edge_count += 1
+            elif include_external and ref not in selected_dois:
+                # External reference
+                if ref not in [n["id"] for n in net.nodes]:
+                    net.add_node(
+                        ref,
+                        label=ref[:20],
+                        title=f"External: {ref}",
+                        size=5,
+                        color="#e74c3c",
+                    )
+                net.add_edge(doi, ref)
+                edge_count += 1
+
+    result = {
+        "nodes": len(net.nodes),
+        "edges": edge_count,
+        "cache_papers": len(papers),
+        "selected_papers": len(selected),
+    }
+
+    if output:
+        net.save_graph(output)
+        result["output"] = output
+    else:
+        result["network_data"] = {
+            "nodes": [{"id": n["id"], "label": n["label"]} for n in net.nodes],
+            "edges": edge_count,
+        }
+
+    return result
+
+
+def get_top_cited(
+    cache_name: str,
+    n: int = 20,
+    year_min: Optional[int] = None,
+    year_max: Optional[int] = None,
+) -> List[Dict[str, Any]]:
+    """Get top cited papers from cache.
+
+    Args:
+        cache_name: Name of cache
+        n: Number of papers to return
+        year_min: Filter by minimum year
+        year_max: Filter by maximum year
+
+    Returns:
+        List of paper dicts sorted by citation count
+    """
+    papers = cache.query(
+        cache_name,
+        include_citations=True,
+        year_min=year_min,
+        year_max=year_max,
+    )
+
+    # Sort by citations
+    papers_sorted = sorted(papers, key=lambda x: -(x.get("citation_count") or 0))
+    return papers_sorted[:n]
+
+
+def get_citation_summary(cache_name: str) -> Dict[str, Any]:
+    """Get citation statistics summary.
+
+    Args:
+        cache_name: Name of cache
+
+    Returns:
+        Dict with citation statistics
+    """
+    papers = cache.load(cache_name)
+
+    citations = [
+        p.get("citation_count", 0)
+        for p in papers
+        if p.get("citation_count") is not None
+    ]
+
+    if not citations:
+        return {"error": "No citation data available"}
+
+    import statistics
+
+    return {
+        "total_papers": len(papers),
+        "papers_with_citations": len(citations),
+        "total_citations": sum(citations),
+        "mean": round(statistics.mean(citations), 2),
+        "median": statistics.median(citations),
+        "stdev": round(statistics.stdev(citations), 2) if len(citations) > 1 else 0,
+        "max": max(citations),
+        "min": min(citations),
+        "highly_cited_50": sum(1 for c in citations if c >= 50),
+        "highly_cited_100": sum(1 for c in citations if c >= 100),
+    }

crossref_local/_cli/__init__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""Internal CLI modules."""
+
+from .cli import cli, main
+from .mcp import mcp, run_mcp_server
+
+__all__ = ["cli", "main", "mcp", "run_mcp_server"]
+
+# EOF

crossref_local/_cli/cache.py

@@ -0,0 +1,179 @@
+"""CLI commands for cache management.
+
+This module provides cache-related CLI commands that are registered
+with the main CLI application.
+"""
+
+import json
+import click
+
+
+def register_cache_commands(cli_group):
+    """Register cache commands with the CLI group."""
+
+    @cli_group.group()
+    def cache():
+        """Manage paper caches for efficient querying."""
+        pass
+
+    @cache.command("create")
+    @click.argument("name")
+    @click.option("-q", "--query", required=True, help="FTS search query")
+    @click.option("-l", "--limit", default=1000, help="Max papers to cache")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+    def cache_create(name, query, limit, as_json):
+        """Create a cache from search query.
+
+        Example:
+            crossref-local cache create epilepsy -q "epilepsy seizure" -l 500
+        """
+        from . import cache as cache_module
+
+        info = cache_module.create(name, query=query, limit=limit)
+        if as_json:
+            click.echo(json.dumps(info.to_dict(), indent=2))
+        else:
+            click.echo(f"Created cache: {info.name}")
+            click.echo(f"  Papers: {info.paper_count}")
+            click.echo(f"  Size: {info.size_bytes / 1024 / 1024:.2f} MB")
+            click.echo(f"  Path: {info.path}")
+
+    @cache.command("list")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+    def cache_list(as_json):
+        """List all available caches."""
+        from . import cache as cache_module
+
+        caches = cache_module.list_caches()
+        if as_json:
+            click.echo(json.dumps([c.to_dict() for c in caches], indent=2))
+        else:
+            if not caches:
+                click.echo("No caches found.")
+                return
+            for c in caches:
+                click.echo(
+                    f"{c.name}: {c.paper_count} papers, {c.size_bytes / 1024 / 1024:.2f} MB"
+                )
+
+    @cache.command("query")
+    @click.argument("name")
+    @click.option("-f", "--fields", help="Comma-separated field list")
+    @click.option("--abstract", is_flag=True, help="Include abstracts")
+    @click.option("--refs", is_flag=True, help="Include references")
+    @click.option("--citations", is_flag=True, help="Include citation counts")
+    @click.option("--year-min", type=int, help="Minimum year filter")
+    @click.option("--year-max", type=int, help="Maximum year filter")
+    @click.option("--journal", help="Journal name filter")
+    @click.option("-l", "--limit", type=int, help="Max results")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+    def cache_query(
+        name,
+        fields,
+        abstract,
+        refs,
+        citations,
+        year_min,
+        year_max,
+        journal,
+        limit,
+        as_json,
+    ):
+        """Query cache with field filtering.
+
+        Examples:
+            crossref-local cache query epilepsy -f doi,title,year
+            crossref-local cache query epilepsy --year-min 2020 --citations
+        """
+        from . import cache as cache_module
+
+        field_list = fields.split(",") if fields else None
+        papers = cache_module.query(
+            name,
+            fields=field_list,
+            include_abstract=abstract,
+            include_references=refs,
+            include_citations=citations,
+            year_min=year_min,
+            year_max=year_max,
+            journal=journal,
+            limit=limit,
+        )
+
+        if as_json:
+            click.echo(json.dumps(papers, indent=2))
+        else:
+            click.echo(f"Found {len(papers)} papers")
+            for p in papers[:10]:
+                title = p.get("title", "No title")[:60]
+                year = p.get("year", "?")
+                click.echo(f"  [{year}] {title}...")
+            if len(papers) > 10:
+                click.echo(f"  ... and {len(papers) - 10} more")
+
+    @cache.command("stats")
+    @click.argument("name")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+    def cache_stats(name, as_json):
+        """Show cache statistics."""
+        from . import cache as cache_module
+
+        stats = cache_module.stats(name)
+        if as_json:
+            click.echo(json.dumps(stats, indent=2))
+        else:
+            click.echo(f"Papers: {stats['paper_count']}")
+            yr = stats.get("year_range", {})
+            click.echo(f"Years: {yr.get('min', '?')} - {yr.get('max', '?')}")
+            click.echo(f"Abstracts: {stats['abstract_coverage']}%")
+            click.echo("\nTop journals:")
+            for j in stats.get("top_journals", [])[:5]:
+                click.echo(f"  {j['journal']}: {j['count']}")
+
+    @cache.command("export")
+    @click.argument("name")
+    @click.argument("output")
+    @click.option(
+        "--format", "fmt", default="json", help="Format: json, csv, bibtex, dois"
+    )
+    @click.option("-f", "--fields", help="Comma-separated field list")
+    def cache_export(name, output, fmt, fields):
+        """Export cache to file.
+
+        Examples:
+            crossref-local cache export epilepsy papers.csv --format csv
+            crossref-local cache export epilepsy refs.bib --format bibtex
+        """
+        from . import cache as cache_module
+
+        field_list = fields.split(",") if fields else None
+        path = cache_module.export(name, output, format=fmt, fields=field_list)
+        click.echo(f"Exported to: {path}")
+
+    @cache.command("delete")
+    @click.argument("name")
+    @click.option("--yes", is_flag=True, help="Skip confirmation")
+    def cache_delete(name, yes):
+        """Delete a cache."""
+        from . import cache as cache_module
+
+        if not yes:
+            if not click.confirm(f"Delete cache '{name}'?"):
+                return
+
+        if cache_module.delete(name):
+            click.echo(f"Deleted: {name}")
+        else:
+            click.echo(f"Cache not found: {name}")
+
+    @cache.command("dois")
+    @click.argument("name")
+    def cache_dois(name):
+        """Output DOIs from cache (one per line)."""
+        from . import cache as cache_module
+
+        dois = cache_module.query_dois(name)
+        for doi in dois:
+            click.echo(doi)
+
+    return cache