crossref-local 0.3.0__py3-none-any.whl

crossref_local/citations.py

@@ -0,0 +1,413 @@
+"""Citation network analysis and visualization.
+
+Build citation graphs like Connected Papers from the local database.
+
+Usage:
+    from crossref_local.citations import get_citing, get_cited, CitationNetwork
+
+    # Get papers citing a DOI
+    citing_dois = get_citing("10.1038/nature12373")
+
+    # Get papers a DOI cites
+    cited_dois = get_cited("10.1038/nature12373")
+
+    # Build and visualize network
+    network = CitationNetwork("10.1038/nature12373", depth=2)
+    network.save_html("citation_network.html")
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional, Set, Tuple
+from pathlib import Path
+
+from .db import get_db, Database
+from .models import Work
+
+
+def get_citing(doi: str, limit: int = 100, db: Optional[Database] = None) -> List[str]:
+    """
+    Get DOIs of papers that cite the given DOI.
+
+    Args:
+        doi: The DOI to find citations for
+        limit: Maximum number of citing papers to return
+        db: Database connection (uses singleton if not provided)
+
+    Returns:
+        List of DOIs that cite this paper
+    """
+    if db is None:
+        db = get_db()
+
+    rows = db.fetchall(
+        """
+        SELECT citing_doi
+        FROM citations
+        WHERE cited_doi = ?
+        LIMIT ?
+        """,
+        (doi, limit)
+    )
+    return [row["citing_doi"] for row in rows]
+
+
+def get_cited(doi: str, limit: int = 100, db: Optional[Database] = None) -> List[str]:
+    """
+    Get DOIs of papers that the given DOI cites (references).
+
+    Args:
+        doi: The DOI to find references for
+        limit: Maximum number of referenced papers to return
+        db: Database connection (uses singleton if not provided)
+
+    Returns:
+        List of DOIs that this paper cites
+    """
+    if db is None:
+        db = get_db()
+
+    rows = db.fetchall(
+        """
+        SELECT cited_doi
+        FROM citations
+        WHERE citing_doi = ?
+        LIMIT ?
+        """,
+        (doi, limit)
+    )
+    return [row["cited_doi"] for row in rows]
+
+
+def get_citation_count(doi: str, db: Optional[Database] = None) -> int:
+    """
+    Get the number of citations for a DOI.
+
+    Args:
+        doi: The DOI to count citations for
+        db: Database connection
+
+    Returns:
+        Number of papers citing this DOI
+    """
+    if db is None:
+        db = get_db()
+
+    row = db.fetchone(
+        "SELECT COUNT(*) as count FROM citations WHERE cited_doi = ?",
+        (doi,)
+    )
+    return row["count"] if row else 0
+
+
+@dataclass
+class CitationNode:
+    """A node in the citation network."""
+    doi: str
+    title: str = ""
+    authors: List[str] = field(default_factory=list)
+    year: Optional[int] = None
+    journal: str = ""
+    citation_count: int = 0
+    depth: int = 0  # Distance from center node
+
+    def to_dict(self) -> dict:
+        return {
+            "doi": self.doi,
+            "title": self.title,
+            "authors": self.authors,
+            "year": self.year,
+            "journal": self.journal,
+            "citation_count": self.citation_count,
+            "depth": self.depth,
+        }
+
+
+@dataclass
+class CitationEdge:
+    """An edge in the citation network (citing -> cited)."""
+    citing_doi: str
+    cited_doi: str
+    year: Optional[int] = None
+
+
+class CitationNetwork:
+    """
+    Citation network builder and visualizer.
+
+    Builds a graph of papers connected by citations, similar to Connected Papers.
+
+    Example:
+        >>> network = CitationNetwork("10.1038/nature12373", depth=2)
+        >>> print(f"Nodes: {len(network.nodes)}, Edges: {len(network.edges)}")
+        >>> network.save_html("network.html")
+    """
+
+    def __init__(
+        self,
+        center_doi: str,
+        depth: int = 1,
+        max_citing: int = 50,
+        max_cited: int = 50,
+        db: Optional[Database] = None,
+    ):
+        """
+        Build a citation network around a central paper.
+
+        Args:
+            center_doi: The DOI to build the network around
+            depth: How many levels of citations to include (1 = direct only)
+            max_citing: Max papers citing each node to include
+            max_cited: Max papers each node cites to include
+            db: Database connection
+        """
+        self.center_doi = center_doi
+        self.depth = depth
+        self.max_citing = max_citing
+        self.max_cited = max_cited
+        self.db = db or get_db()
+
+        self.nodes: Dict[str, CitationNode] = {}
+        self.edges: List[CitationEdge] = []
+
+        self._build_network()
+
+    def _build_network(self):
+        """Build the citation network by traversing citations."""
+        # Start with center node
+        to_process: List[Tuple[str, int]] = [(self.center_doi, 0)]
+        processed: Set[str] = set()
+
+        while to_process:
+            doi, current_depth = to_process.pop(0)
+
+            if doi in processed:
+                continue
+            processed.add(doi)
+
+            # Add node
+            self._add_node(doi, current_depth)
+
+            # Stop expanding at max depth
+            if current_depth >= self.depth:
+                continue
+
+            # Get citing papers (papers that cite this one)
+            citing = get_citing(doi, limit=self.max_citing, db=self.db)
+            for citing_doi in citing:
+                self.edges.append(CitationEdge(citing_doi=citing_doi, cited_doi=doi))
+                if citing_doi not in processed:
+                    to_process.append((citing_doi, current_depth + 1))
+
+            # Get cited papers (papers this one cites)
+            cited = get_cited(doi, limit=self.max_cited, db=self.db)
+            for cited_doi in cited:
+                self.edges.append(CitationEdge(citing_doi=doi, cited_doi=cited_doi))
+                if cited_doi not in processed:
+                    to_process.append((cited_doi, current_depth + 1))
+
+    def _add_node(self, doi: str, depth: int):
+        """Add a node with metadata from the database."""
+        if doi in self.nodes:
+            return
+
+        # Get metadata
+        metadata = self.db.get_metadata(doi)
+        citation_count = get_citation_count(doi, db=self.db)
+
+        if metadata:
+            work = Work.from_metadata(doi, metadata)
+            self.nodes[doi] = CitationNode(
+                doi=doi,
+                title=work.title or "",
+                authors=work.authors,
+                year=work.year,
+                journal=work.journal or "",
+                citation_count=citation_count,
+                depth=depth,
+            )
+        else:
+            # DOI not in our database, create minimal node
+            self.nodes[doi] = CitationNode(
+                doi=doi,
+                citation_count=citation_count,
+                depth=depth,
+            )
+
+    def to_networkx(self):
+        """
+        Convert to a NetworkX DiGraph.
+
+        Returns:
+            networkx.DiGraph with nodes and edges
+
+        Raises:
+            ImportError: If networkx is not installed
+        """
+        try:
+            import networkx as nx
+        except ImportError:
+            raise ImportError("networkx required: pip install networkx")
+
+        G = nx.DiGraph()
+
+        # Add nodes with attributes
+        for doi, node in self.nodes.items():
+            G.add_node(doi, **node.to_dict())
+
+        # Add edges
+        for edge in self.edges:
+            if edge.citing_doi in self.nodes and edge.cited_doi in self.nodes:
+                G.add_edge(edge.citing_doi, edge.cited_doi)
+
+        return G
+
+    def save_html(self, path: str = "citation_network.html", **kwargs):
+        """
+        Save interactive HTML visualization using pyvis.
+
+        Args:
+            path: Output file path
+            **kwargs: Additional options for pyvis Network
+
+        Raises:
+            ImportError: If pyvis is not installed
+        """
+        try:
+            from pyvis.network import Network
+        except ImportError:
+            raise ImportError("pyvis required: pip install pyvis")
+
+        # Create pyvis network
+        net = Network(
+            height="800px",
+            width="100%",
+            directed=True,
+            bgcolor="#ffffff",
+            font_color="#333333",
+            **kwargs
+        )
+
+        # Configure physics
+        net.barnes_hut(
+            gravity=-3000,
+            central_gravity=0.3,
+            spring_length=200,
+            spring_strength=0.05,
+        )
+
+        # Add nodes with styling based on depth and citation count
+        for doi, node in self.nodes.items():
+            # Size based on citation count (log scale)
+            import math
+            size = 10 + min(30, math.log1p(node.citation_count) * 5)
+
+            # Color based on depth
+            colors = ["#e74c3c", "#3498db", "#2ecc71", "#9b59b6", "#f39c12"]
+            color = colors[min(node.depth, len(colors) - 1)]
+
+            # Label
+            title_short = (node.title[:50] + "...") if len(node.title) > 50 else node.title
+            label = f"{title_short}\n({node.year or 'N/A'})"
+
+            # Tooltip
+            authors_str = ", ".join(node.authors[:3])
+            if len(node.authors) > 3:
+                authors_str += " et al."
+            tooltip = f"""
+            <b>{node.title}</b><br>
+            {authors_str}<br>
+            {node.journal} ({node.year or 'N/A'})<br>
+            Citations: {node.citation_count}<br>
+            DOI: {doi}
+            """
+
+            net.add_node(
+                doi,
+                label=label,
+                title=tooltip,
+                size=size,
+                color=color,
+                borderWidth=2 if doi == self.center_doi else 1,
+                borderWidthSelected=4,
+            )
+
+        # Add edges
+        for edge in self.edges:
+            if edge.citing_doi in self.nodes and edge.cited_doi in self.nodes:
+                net.add_edge(edge.citing_doi, edge.cited_doi, arrows="to")
+
+        # Save
+        net.save_graph(path)
+        return path
+
+    def save_png(self, path: str = "citation_network.png", figsize: Tuple[int, int] = (12, 10)):
+        """
+        Save static PNG visualization using matplotlib.
+
+        Args:
+            path: Output file path
+            figsize: Figure size (width, height)
+
+        Raises:
+            ImportError: If matplotlib is not installed
+        """
+        try:
+            import matplotlib.pyplot as plt
+            import networkx as nx
+        except ImportError:
+            raise ImportError("matplotlib and networkx required")
+
+        G = self.to_networkx()
+
+        fig, ax = plt.subplots(figsize=figsize)
+
+        # Layout
+        pos = nx.spring_layout(G, k=2, iterations=50)
+
+        # Node sizes based on citation count
+        import math
+        sizes = [100 + min(500, math.log1p(self.nodes[n].citation_count) * 50) for n in G.nodes()]
+
+        # Node colors based on depth
+        colors = [self.nodes[n].depth for n in G.nodes()]
+
+        # Draw
+        nx.draw_networkx_nodes(G, pos, node_size=sizes, node_color=colors,
+                               cmap=plt.cm.RdYlBu_r, alpha=0.8, ax=ax)
+        nx.draw_networkx_edges(G, pos, alpha=0.3, arrows=True,
+                               arrowsize=10, ax=ax)
+
+        # Labels for important nodes (high citation count)
+        labels = {}
+        for doi in G.nodes():
+            node = self.nodes[doi]
+            if node.citation_count > 10 or doi == self.center_doi:
+                short_title = (node.title[:30] + "...") if len(node.title) > 30 else node.title
+                labels[doi] = f"{short_title}\n({node.year or 'N/A'})"
+
+        nx.draw_networkx_labels(G, pos, labels, font_size=8, ax=ax)
+
+        ax.set_title(f"Citation Network: {self.center_doi}")
+        ax.axis("off")
+
+        plt.tight_layout()
+        plt.savefig(path, dpi=150, bbox_inches="tight")
+        plt.close()
+
+        return path
+
+    def to_dict(self) -> dict:
+        """Export network as dictionary."""
+        return {
+            "center_doi": self.center_doi,
+            "depth": self.depth,
+            "nodes": [n.to_dict() for n in self.nodes.values()],
+            "edges": [{"citing": e.citing_doi, "cited": e.cited_doi} for e in self.edges],
+            "stats": {
+                "total_nodes": len(self.nodes),
+                "total_edges": len(self.edges),
+            }
+        }
+
+    def __repr__(self):
+        return f"CitationNetwork(center={self.center_doi}, nodes={len(self.nodes)}, edges={len(self.edges)})"

crossref_local/cli.py

@@ -0,0 +1,257 @@
+"""Command-line interface for crossref_local."""
+
+import click
+import json
+import re
+import sys
+from typing import Optional
+
+from . import search, get, count, info, __version__
+
+
+from .impact_factor import ImpactFactorCalculator
+
+
+def _strip_xml_tags(text: str) -> str:
+    """Strip XML/JATS tags from abstract text."""
+    if not text:
+        return text
+    # Remove XML tags
+    text = re.sub(r"<[^>]+>", " ", text)
+    # Collapse multiple spaces
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+class AliasedGroup(click.Group):
+    """Click group that supports command aliases."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._aliases = {}
+
+    def command(self, *args, aliases=None, **kwargs):
+        """Decorator that registers aliases for commands."""
+        def decorator(f):
+            cmd = super(AliasedGroup, self).command(*args, **kwargs)(f)
+            if aliases:
+                for alias in aliases:
+                    self._aliases[alias] = cmd.name
+            return cmd
+        return decorator
+
+    def get_command(self, ctx, cmd_name):
+        """Resolve aliases to actual commands."""
+        cmd_name = self._aliases.get(cmd_name, cmd_name)
+        return super().get_command(ctx, cmd_name)
+
+    def format_commands(self, ctx, formatter):
+        """Format commands with aliases shown inline."""
+        commands = []
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None or cmd.hidden:
+                continue
+
+            # Find aliases for this command
+            aliases = [a for a, c in self._aliases.items() if c == subcommand]
+            if aliases:
+                name = f"{subcommand} ({', '.join(aliases)})"
+            else:
+                name = subcommand
+
+            help_text = cmd.get_short_help_str(limit=50)
+            commands.append((name, help_text))
+
+        if commands:
+            with formatter.section("Commands"):
+                formatter.write_dl(commands)
+
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(cls=AliasedGroup, context_settings=CONTEXT_SETTINGS)
+@click.version_option(version=__version__, prog_name="crossref-local")
+def cli():
+    """Local CrossRef database with 167M+ works and full-text search."""
+    pass
+
+
+@cli.command(aliases=["s"], context_settings=CONTEXT_SETTINGS)
+@click.argument("query")
+@click.option("-n", "--limit", default=10, help="Number of results")
+@click.option("-o", "--offset", default=0, help="Skip first N results")
+@click.option("-a", "--with-abstracts", is_flag=True, help="Show abstracts")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def search_cmd(query: str, limit: int, offset: int, with_abstracts: bool, as_json: bool):
+    """Search for works by title, abstract, or authors."""
+    results = search(query, limit=limit, offset=offset)
+
+    if as_json:
+        output = {
+            "query": results.query,
+            "total": results.total,
+            "elapsed_ms": results.elapsed_ms,
+            "works": [w.to_dict() for w in results.works],
+        }
+        click.echo(json.dumps(output, indent=2))
+    else:
+        click.echo(f"Found {results.total:,} matches in {results.elapsed_ms:.1f}ms\n")
+        for i, work in enumerate(results.works, start=offset + 1):
+            title = _strip_xml_tags(work.title) if work.title else "Untitled"
+            year = f"({work.year})" if work.year else ""
+            click.echo(f"{i}. {title} {year}")
+            click.echo(f"   DOI: {work.doi}")
+            if work.journal:
+                click.echo(f"   Journal: {work.journal}")
+            if with_abstracts and work.abstract:
+                # Strip XML tags and truncate
+                abstract = _strip_xml_tags(work.abstract)
+                if len(abstract) > 500:
+                    abstract = abstract[:500] + "..."
+                click.echo(f"   Abstract: {abstract}")
+            click.echo()
+
+
+@cli.command("get", aliases=["g"], context_settings=CONTEXT_SETTINGS)
+@click.argument("doi")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option("--citation", is_flag=True, help="Output as citation")
+def get_cmd(doi: str, as_json: bool, citation: bool):
+    """Get a work by DOI."""
+    work = get(doi)
+
+    if work is None:
+        click.echo(f"DOI not found: {doi}", err=True)
+        sys.exit(1)
+
+    if as_json:
+        click.echo(json.dumps(work.to_dict(), indent=2))
+    elif citation:
+        click.echo(work.citation())
+    else:
+        click.echo(f"Title: {work.title}")
+        click.echo(f"Authors: {', '.join(work.authors)}")
+        click.echo(f"Year: {work.year}")
+        click.echo(f"Journal: {work.journal}")
+        click.echo(f"DOI: {work.doi}")
+        if work.citation_count:
+            click.echo(f"Citations: {work.citation_count}")
+
+
+@cli.command(aliases=["c"], context_settings=CONTEXT_SETTINGS)
+@click.argument("query")
+def count_cmd(query: str):
+    """Count matching works."""
+    n = count(query)
+    click.echo(f"{n:,}")
+
+
+@cli.command(aliases=["i"], context_settings=CONTEXT_SETTINGS)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def info_cmd(as_json: bool):
+    """Show database information."""
+    db_info = info()
+
+    if as_json:
+        click.echo(json.dumps(db_info, indent=2))
+    else:
+        click.echo("CrossRef Local Database")
+        click.echo("-" * 40)
+        click.echo(f"Database: {db_info['db_path']}")
+        click.echo(f"Works: {db_info['works']:,}")
+        click.echo(f"FTS indexed: {db_info['fts_indexed']:,}")
+        click.echo(f"Citations: {db_info['citations']:,}")
+
+
+@cli.command("impact-factor", aliases=["if"], context_settings=CONTEXT_SETTINGS)
+@click.argument("journal")
+@click.option("-y", "--year", default=2023, help="Target year")
+@click.option("-w", "--window", default=2, help="Citation window years")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def impact_factor_cmd(journal: str, year: int, window: int, as_json: bool):
+    """Calculate impact factor for a journal."""
+    with ImpactFactorCalculator() as calc:
+        result = calc.calculate_impact_factor(
+            journal_identifier=journal,
+            target_year=year,
+            window_years=window,
+        )
+
+    if as_json:
+        click.echo(json.dumps(result, indent=2))
+    else:
+        click.echo(f"Journal: {result['journal']}")
+        click.echo(f"Year: {result['target_year']}")
+        click.echo(f"Window: {result['window_range']}")
+        click.echo(f"Articles: {result['total_articles']:,}")
+        click.echo(f"Citations: {result['total_citations']:,}")
+        click.echo(f"Impact Factor: {result['impact_factor']:.3f}")
+
+
+@cli.command(context_settings=CONTEXT_SETTINGS)
+def setup():
+    """Check setup status and configuration."""
+    from .config import Config, DEFAULT_DB_PATHS
+    import os
+
+    click.echo("CrossRef Local - Setup Status")
+    click.echo("=" * 50)
+    click.echo()
+
+    # Check environment variable
+    env_db = os.environ.get("CROSSREF_LOCAL_DB")
+    if env_db:
+        click.echo(f"CROSSREF_LOCAL_DB: {env_db}")
+        if os.path.exists(env_db):
+            click.echo("  Status: OK")
+        else:
+            click.echo("  Status: NOT FOUND")
+    else:
+        click.echo("CROSSREF_LOCAL_DB: (not set)")
+
+    click.echo()
+
+    # Check default paths
+    click.echo("Checking default database locations:")
+    db_found = None
+    for path in DEFAULT_DB_PATHS:
+        if path.exists():
+            click.echo(f"  [OK] {path}")
+            if db_found is None:
+                db_found = path
+        else:
+            click.echo(f"  [ ] {path}")
+
+    click.echo()
+
+    if db_found:
+        click.echo(f"Database found: {db_found}")
+        click.echo()
+
+        try:
+            db_info = info()
+            click.echo(f"  Works: {db_info['works']:,}")
+            click.echo(f"  FTS indexed: {db_info['fts_indexed']:,}")
+            click.echo(f"  Citations: {db_info['citations']:,}")
+            click.echo()
+            click.echo("Setup complete! Try:")
+            click.echo('  crossref-local search "machine learning"')
+        except Exception as e:
+            click.echo(f"  Error reading database: {e}", err=True)
+    else:
+        click.echo("No database found!")
+        click.echo()
+        click.echo("To set up:")
+        click.echo("  export CROSSREF_LOCAL_DB=/path/to/crossref.db")
+        click.echo("  See: make db-build-info")
+
+
+def main():
+    """Entry point for CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()