Quick Start Guide¶

Get running with your first citation analysis in under 10 minutes!

Before You Start¶

Choose your path:

🎭 Demo Mode First! (recommended for all users): - ✅ Installation - Install with pip install -e ".[all]" - ✅ No database required - Use demo datasets to explore features - ✅ Learn features - Get familiar before full setup

🏢 Production Setup (after mastering demo mode): - ✅ Installation - Install with pip install -e ".[all]" - ✅ Configuration - .env file configured with Neo4j credentials - ✅ Environment Setup - Database connection validated - ✅ Demo Experience - Understanding gained from hands-on exploration

Your First Citation Analysis¶

Step 1: Launch the Platform¶

Choose your preferred interface:

# Launch Streamlit interface
streamlit run app.py

# Start Jupyter
jupyter notebook notebooks/

Step 2: Choose Your Data Source¶

Once the platform is running, choose how you want to explore citation networks:

In the Interactive Dashboard:¶

1. Navigate to the Home page - Overview of your citation network
2. Check Network Analysis - View basic statistics about your data:
3. Number of papers and citations
4. Network density and connectivity
5. Top-cited papers and influential authors

In Jupyter Notebooks:¶

Run the first few cells of 01_comprehensive_exploration.ipynb to see:

# Quick network overview
from src.services.analytics_service import get_analytics_service

analytics = get_analytics_service()
overview = analytics.get_network_overview()

print(f"📊 Network Overview:")
print(f"Papers: {overview.num_papers:,}")
print(f"Citations: {overview.num_citations:,}")
print(f"Authors: {overview.num_authors:,}")
print(f"Average citations per paper: {overview.avg_citations:.2f}")

Step 3: Make Your First Citation Prediction¶

New! Citation predictions now work in demo mode with no setup required!

# Works in both demo and production modes
from src.services.ml_service import get_ml_service

ml_service = get_ml_service()

# Demo mode: Use papers from loaded demo dataset
# Production: Use papers from your database
paper_id = "649def34f8be52c8b66281af98ae884c09aef38f9"  # Attention paper in demo
predictions = ml_service.predict_citations(paper_id, top_k=10)

print(f"🤖 Predictions for paper: {paper_id}")
for pred in predictions:
    print(f"📄 Target: {pred['target_id']}")
    print(f"   Confidence: {pred['confidence']:.3f}")
    print(f"   Field relationship: {pred.get('field_similarity', 'N/A')}")
    print()

Step 4: Analyze Citation Communities¶

Discover research communities in your network:

# Detect research communities
communities = analytics.detect_communities(
    method='louvain',
    resolution=1.0
)

print(f"🏘️ Found {len(communities.communities)} research communities")

# Show largest communities
for i, community in enumerate(communities.communities[:5]):
    print(f"\nCommunity {i+1}: {len(community.papers)} papers")
    print(f"Top papers: {community.top_papers[:3]}")

Step 5: Generate Your First Report¶

Export your analysis results:

from src.analytics.export_engine import ExportEngine

exporter = ExportEngine()

# Generate comprehensive report
report = exporter.generate_report(
    title="My First Citation Analysis",
    include_predictions=True,
    include_communities=True,
    format="latex"
)

print(f"📊 Report generated: {report.file_path}")

Sample Workflows¶

Try these common analysis patterns:

🔍 Research Discovery Workflow¶

1. Find a paper of interest in your network
2. Generate citation predictions to find related work
3. Explore the embedding space to visualize paper relationships
4. Export reading list with confidence scores

🕸️ Network Analysis Workflow¶

1. Compute network statistics (centrality, clustering)
2. Detect research communities using graph algorithms
3. Analyze temporal trends in citation patterns
4. Generate LaTeX report for publication

🤖 ML Pipeline Workflow¶

1. Train custom TransE model on your data
2. Evaluate model performance with standard metrics
3. Generate predictions for paper recommendation
4. Validate results against known citations

Next Steps¶

Now that you've completed your first analysis:

📚 Learn More¶

New User Path: - Demo Mode Guide - Master demo features and educational workflows - Demo Datasets - Explore all available demo datasets - File Upload Guide - Import your research collections easily

Advanced Features: - Interactive Features - Clickable nodes, real-time progress, enhanced UI - Data Import - Comprehensive import pipeline with streaming features
- User Guide - Complete feature walkthrough - Notebook Pipeline - Complete analysis workflows - ML Predictions - Advanced prediction techniques

🔧 Customize Your Setup¶

• Model Training Notebook - Train models for your domain
• API Reference - Scale for large datasets
• Developer Guide - Connect with other tools

🤝 Get Help¶

• GitHub Issues - Common issues and solutions
• API Reference - Complete API documentation
• GitHub Issues - Report bugs or request features

Quick Reference¶

Essential Commands¶

# Start interactive dashboard
streamlit run app.py

# Run complete analysis pipeline
jupyter notebook notebooks/01_comprehensive_exploration.ipynb

# Test your setup
python -m pytest tests/test_integration.py -v

# Validate configuration
python scripts/validate_environment.py

# Generate API documentation
mkdocs serve --watch-theme

Key File Locations¶

• Configuration: .env
• Models: models/
• Outputs: outputs/
• Notebooks: notebooks/
• Documentation: docs/

Important URLs¶

• Interactive Dashboard: http://localhost:8501
• Jupyter Notebooks: http://localhost:8888
• Documentation: http://localhost:8000 (if running mkdocs serve)