Skip to content

LITERATURE_REVIEW.md

Latest commit

 

History

History
1725 lines (1271 loc) · 42.8 KB

LITERATURE_REVIEW.md

File metadata and controls

1725 lines (1271 loc) · 42.8 KB
Raw

Literature Review Feature - ASReview Integration

Quick Start

Literature Review - Quick Deployment Guide

This guide provides quick setup instructions for deploying the Literature Review feature with ASReview integration.

Quick Setup (5 Minutes)

Step 1: Deploy ASReview Service

Option A: Docker (Easiest)

# On GPU-enabled server
docker run -d \
  --name asreview \
  --gpus all \
  -p 5275:5275 \
  -v asreview-data:/data \
  --restart unless-stopped \
  asreview/asreview:latest \
  asreview lab --host 0.0.0.0 --port 5275

Option B: Python (Alternative)

# On GPU-enabled server
pip install asreview[all]
asreview lab --host 0.0.0.0 --port 5275 &

Step 2: Configure HARVEST

Edit config.py:

# Enable Literature Review feature
ENABLE_LITERATURE_REVIEW = True

# Configure ASReview service URL
ASREVIEW_SERVICE_URL = "http://your-gpu-server:5275"

Replace your-gpu-server with:

  • IP address: http://192.168.1.100:5275
  • Hostname: http://gpu-server.local:5275
  • Same host: http://localhost:5275

Step 3: Restart HARVEST

# Kill existing processes
pkill -f harvest_be.py
pkill -f harvest_fe.py

# Start HARVEST
python3 launch_harvest.py

Step 4: Verify

# Check ASReview connectivity
curl http://localhost:5001/api/literature-review/health

Expected output:

{
  "ok": true,
  "available": true,
  "configured": true,
  "version": "1.x.x"
}

Usage (2 Minutes)

1. Search for Papers

  1. Login to HARVEST admin panel
  2. Go to Literature Search tab
  3. Search for papers: e.g., "CRISPR gene editing"
  4. Review results

2. Start Literature Review

  1. Click "Start Literature Review" button
  2. Enter project name: "CRISPR Review 2024"
  3. Select ML model: "Naive Bayes" (default)
  4. Click "Create Project"

3. Screen Papers

  1. Review paper presented (title, abstract, authors)
  2. Mark as:
    • ✅ Relevant: Meets your criteria
    • ❌ Irrelevant: Doesn't meet criteria
  3. Repeat for next paper (shown in order of predicted relevance)
  4. Stop when satisfied or all papers screened

4. Export Results

  1. Click "Export Results"
  2. Select export format:
    • Create new HARVEST project
    • Download CSV
    • Copy DOIs to clipboard
  3. Use relevant papers for annotation

Troubleshooting

"Service not configured" Error

Problem: ASREVIEW_SERVICE_URL not set

Solution:

# Edit config.py
nano config.py

# Add/update line:
ASREVIEW_SERVICE_URL = "http://gpu-server:5275"

# Restart HARVEST
python3 launch_harvest.py

"Connection refused" Error

Problem: Cannot reach ASReview service

Solutions:

  1. Check ASReview is running:

    curl http://gpu-server:5275/api/health

  2. Check firewall allows port 5275:

    sudo ufw allow 5275/tcp

  3. Verify network connectivity:

    ping gpu-server
telnet gpu-server 5275

"Service unavailable" Error

Problem: ASReview service not responding

Solutions:

  1. Restart ASReview:

    docker restart asreview
# or
pkill -f asreview
asreview lab --host 0.0.0.0 --port 5275 &

  2. Check ASReview logs:

    docker logs asreview

  3. Increase timeout in config.py:

    ASREVIEW_REQUEST_TIMEOUT = 600  # 10 minutes

Nginx Configuration

You have two main options for deploying ASReview with HARVEST. Choose based on your needs.

⚙️ How to Switch Between Options

IMPORTANT: There is no on/off switch! You just configure which URL to use in config.py:

# Option 1: Nginx Direct Proxy (faster)
ASREVIEW_SERVICE_URL = "https://yourdomain.com/harvest/asreview"

# Option 2: HARVEST Proxy (simpler)  
ASREVIEW_SERVICE_URL = "http://asreview-host:5123"

That's it! The URL format determines which method is used:

  • Full URL with path (e.g., https://domain.com/harvest/asreview) → Nginx proxies ASReview
  • Direct host:port (e.g., http://host:5123) → HARVEST proxies ASReview

No code changes needed to switch - just update config.py and restart HARVEST!

🤔 Which Option Should I Choose?

Quick Decision:

Your Situation Recommended Option
Production with nginx ✅ Option 1 (Nginx Proxy)
Development/Testing ✅ Option 2 (HARVEST Proxy)
No nginx access ✅ Option 2 (HARVEST Proxy)
High traffic (10+ users) ✅ Option 1 (Nginx Proxy)
Single user testing ✅ Option 2 (HARVEST Proxy)
Want best performance ✅ Option 1 (Nginx Proxy)
Want simplest setup ✅ Option 2 (HARVEST Proxy)
Need to debug issues ✅ Option 2 (HARVEST Proxy)

Not sure? Start with Option 2 (HARVEST Proxy) - it's easier to set up and you can always switch to Option 1 later for better performance.

Option 1: Nginx Proxies ASReview Directly (Recommended for Production)

Best for: Production deployments, better performance, standard practice

This approach has nginx proxy ASReview directly, which is more efficient and offloads work from HARVEST.

# Proxy HARVEST application
location /harvest/ {
    proxy_pass http://localhost:8050/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# Proxy ASReview service with React SPA support
location /harvest/asreview/ {
    # Remove /harvest/asreview prefix before passing to ASReview
    rewrite ^/harvest/asreview/(.*) /$1 break;
    
    # Proxy to ASReview service
    # Replace with your ASReview host and port
    proxy_pass http://asreview-host:5123;
    
    # Standard proxy headers
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # WebSocket support
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    
    # Timeouts
    proxy_connect_timeout 10s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
    
    # CRITICAL: Fix React SPA paths using sub_filter
    # This injects a <base> tag to tell the browser where to resolve relative URLs
    sub_filter_once off;
    sub_filter_types text/html text/css application/javascript;
    sub_filter '<head>' '<head><base href="/harvest/asreview/">';
    
    # Also rewrite absolute paths in HTML/JS
    sub_filter 'href="/' 'href="/harvest/asreview/';
    sub_filter 'src="/' 'src="/harvest/asreview/';
    
    # Disable redirect rewriting
    proxy_redirect off;
    
    # CORS headers (if needed)
    add_header Access-Control-Allow-Origin "*" always;
}

Then configure HARVEST to use the nginx-proxied ASReview:

# In config.py
ASREVIEW_SERVICE_URL = "https://yourdomain.com/harvest/asreview"

Advantages:

  • ✅ Better performance (one less hop)
  • ✅ Offloads proxying to nginx (designed for this)
  • ✅ Standard production practice
  • ✅ Works with your existing nginx setup

Requirements:

  • nginx sub_filter module (usually included by default)
  • nginx configured with proper base path rewriting

Test nginx config before reloading:

sudo nginx -t
sudo systemctl reload nginx

Option 2: HARVEST Proxies to ASReview (Simpler Setup)

Best for: Development, testing, simpler deployments without nginx

Let HARVEST handle all ASReview proxying (nginx just proxies HARVEST):

# In your nginx configuration, just proxy to HARVEST
location /harvest/ {
    proxy_pass http://localhost:8050/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Then configure HARVEST to connect directly to ASReview:

# In config.py
# Replace with your ASReview host and port
ASREVIEW_SERVICE_URL = "http://asreview-host:5123"  # Direct connection

How it works:

  1. Browser requests /harvest/proxy/asreview/...
  2. Nginx forwards to HARVEST frontend
  3. HARVEST's /proxy/asreview/ route forwards to ASReview service
  4. HARVEST handles MIME type correction and base path injection automatically
  5. Browser receives correctly formatted responses

Advantages:

  • ✅ HARVEST handles React SPA routing automatically (code already in place)
  • ✅ No nginx sub_filter configuration needed
  • ✅ Centralized proxy logic in HARVEST code (easier to debug)
  • ✅ Works with ASReview on internal/private networks

Disadvantages:

  • ❌ Extra hop adds latency (Browser → nginx → HARVEST → ASReview)
  • ❌ Uses HARVEST server resources for proxying

Which Option Should You Use?

Use Option 1 (nginx direct proxy) if:

  • You're deploying to production
  • You want best performance
  • You're comfortable with nginx configuration
  • You want to follow standard web server practices
  • You have nginx with sub_filter module available

Use Option 2 (HARVEST proxy) if:

  • You're in development/testing
  • You want simpler configuration
  • You don't have access to nginx config
  • ASReview is on an internal/private network only accessible from HARVEST server
  • You prefer centralized proxy logic

Detailed Comparison

Performance

Metric Nginx Proxy HARVEST Proxy
Latency per request ~5-10ms ~15-30ms
Server resource usage Minimal Medium
Concurrent users Excellent (1000+) Good (10-50)
Large file transfers Very efficient Good

Verdict: Nginx proxy is 2-3x faster and more resource-efficient.

Complexity

Aspect Nginx Proxy HARVEST Proxy
Setup time ~10 minutes ~2 minutes
Configuration changes 2 files (nginx + HARVEST) 1 file (HARVEST only)
Requires nginx knowledge Yes No
Requires nginx access Yes No

Verdict: HARVEST proxy is much simpler to set up.

Debugging & Maintenance

Aspect Nginx Proxy HARVEST Proxy
Log location Nginx logs + HARVEST logs HARVEST logs only
Error debugging Need to check nginx Python stack traces
Code inspection nginx config file Python code
Flexibility Limited to nginx features Full Python flexibility

Verdict: HARVEST proxy is easier to debug and modify.

Production Readiness

Aspect Nginx Proxy HARVEST Proxy
Industry standard Yes ✅ No (custom)
Scalability Excellent Good
Load balancing Native support Requires code
Monitoring Standard nginx tools Custom implementation

Verdict: Nginx proxy follows best practices for production.

Migration Between Options

Switching is easy - just configuration changes:

From HARVEST Proxy → Nginx Proxy:

  1. Update nginx config (add sub_filter directives)
  2. Test: sudo nginx -t
  3. Reload: sudo systemctl reload nginx
  4. Update HARVEST config.py: ASREVIEW_SERVICE_URL = "https://yourdomain.com/harvest/asreview"
  5. Restart HARVEST

From Nginx Proxy → HARVEST Proxy:

  1. Update HARVEST config.py: ASREVIEW_SERVICE_URL = "http://asreview-host:5123"
  2. Restart HARVEST
  3. (Optional) Remove sub_filter directives from nginx

No code changes needed - both options use the same Python proxy code as a fallback.

Troubleshooting Nginx Setup

If ASReview doesn't load properly through nginx (Option 1):

  1. Verify sub_filter module is available:

    nginx -V 2>&1 | grep -o with-http_sub_module
# Should output: with-http_sub_module

  2. Check nginx logs for errors:

    tail -f /var/log/nginx/error.log

  3. Test the base tag injection by viewing page source:

    curl https://yourdomain.com/harvest/asreview/ | grep -i "<base"
# Should show: <base href="/harvest/asreview/">

  4. Check Content-Type headers for static files:

    curl -I https://yourdomain.com/harvest/asreview/static/js/main.xxx.js
# Should return: Content-Type: application/javascript

  5. If sub_filter doesn't work, fall back to Option 2 (HARVEST proxy)

Converting from Option 2 to Option 1

If you're currently using Option 2 and want to switch:

  1. Update nginx config with the Option 1 configuration
  2. Test nginx config: sudo nginx -t
  3. Update HARVEST config.py to point to nginx URL
  4. Reload nginx: sudo systemctl reload nginx
  5. Restart HARVEST: python3 launch_harvest.py

No code changes needed - HARVEST's proxy at /proxy/asreview/ will still work but won't be used.

Performance Tips

GPU Acceleration

Ensure ASReview uses GPU:

# Check GPU available
nvidia-smi

# Run ASReview with GPU
docker run --gpus all ...

Model Selection

  • Naive Bayes: Fastest, good for <1000 papers
  • Logistic Regression: Balanced, good for most cases
  • Random Forest: Most accurate, slower
  • SVM: Best for complex criteria, needs more training

Batch Size

For large reviews:

  • Upload papers in batches of 500
  • Screen in sessions of 50-100
  • Export results regularly

Next Steps

Support

Deployment Checklist

Literature Review Feature - Deployment Checklist

This checklist helps deploy the Literature Review feature to production.

Pre-Deployment Checklist

☐ 1. ASReview Service Setup

Choose deployment method:

  • Docker (recommended for production)
  • Python virtual environment
  • Systemd service

GPU Host Requirements:

  • NVIDIA GPU available (check with nvidia-smi)
  • Docker installed (if using Docker)
  • Python 3.8+ (if using Python install)
  • Network connectivity to HARVEST

Deploy ASReview:

# Option A: Docker
docker run -d \
  --name asreview \
  --gpus all \
  -p 5275:5275 \
  -v asreview-data:/data \
  --restart unless-stopped \
  asreview/asreview:latest \
  asreview lab --host 0.0.0.0 --port 5275

# Option B: Python
pip install asreview[all]
asreview lab --host 0.0.0.0 --port 5275 &

Verify service:

curl http://gpu-server:5275/api/health
# Should return: {"version": "...", "status": "ok"}

☐ 2. Network Configuration

Firewall rules:

  • Allow port 5275 on GPU server
  • Allow HARVEST → ASReview connectivity
# On GPU server
sudo ufw allow 5275/tcp
sudo ufw status

Test connectivity:

# From HARVEST server
telnet gpu-server 5275
curl http://gpu-server:5275/api/health

☐ 3. HARVEST Configuration

Edit config.py:

# Enable feature
ENABLE_LITERATURE_REVIEW = True

# Configure service URL
ASREVIEW_SERVICE_URL = "http://gpu-server:5275"

# Optional: API key
ASREVIEW_API_KEY = ""

# Timeouts
ASREVIEW_REQUEST_TIMEOUT = 300
ASREVIEW_CONNECTION_TIMEOUT = 10

Or use environment variables:

export ASREVIEW_SERVICE_URL="http://gpu-server:5275"
export ASREVIEW_API_KEY=""

☐ 4. Nginx Configuration (if using nginx mode)

Add to nginx.conf:

# ASReview service proxy
location /asreview/ {
    proxy_pass http://gpu-server:5275/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
    proxy_connect_timeout 10s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
}

Test nginx config:

sudo nginx -t
sudo systemctl reload nginx

Update HARVEST config:

ASREVIEW_SERVICE_URL = "https://yourdomain.com/asreview"

☐ 5. Testing

Test ASReview health:

curl http://localhost:5001/api/literature-review/health

Expected response:

{
  "ok": true,
  "available": true,
  "configured": true,
  "service_url": "http://gpu-server:5275",
  "version": "1.x.x",
  "status": "ok"
}

Run integration tests (optional):

# Start mock service
python3 asreview_mock_service.py &

# Run tests
python3 test_literature_review_integration.py

☐ 6. Restart HARVEST

# Kill existing processes
pkill -f harvest_be.py
pkill -f harvest_fe.py

# Start HARVEST
python3 launch_harvest.py

# Or if using systemd
sudo systemctl restart harvest

☐ 7. Verify Deployment

Check logs:

# HARVEST logs
tail -f harvest.log

# ASReview logs (Docker)
docker logs -f asreview

# ASReview logs (systemd)
sudo journalctl -u asreview -f

Test workflow:

  1. Login to HARVEST as admin
  2. Go to Literature Search tab
  3. Search for papers
  4. Click "Start Literature Review" (if frontend implemented)
  5. Or use API directly:
# Test API endpoint
curl -X GET \
  http://localhost:5001/api/literature-review/health \
  -H 'Cookie: session=...'

Post-Deployment Checklist

☐ 8. Monitoring

Setup monitoring:

  • ASReview service uptime
  • GPU utilization
  • API response times
  • Error rates

Monitor ASReview:

# Check service status
curl http://gpu-server:5275/api/health

# Check GPU usage
nvidia-smi

# Check Docker stats
docker stats asreview

☐ 9. Documentation

Update internal docs:

  • Document ASReview service URL
  • Document admin procedures
  • Create runbook for common issues
  • Train users on new feature

☐ 10. Backup and Recovery

Backup procedures:

  • ASReview data directory (/data in Docker)
  • HARVEST database (includes project metadata)
  • Configuration files
# Backup ASReview data
docker cp asreview:/data /backup/asreview-data-$(date +%Y%m%d)

# Backup HARVEST config
cp config.py /backup/config.py.$(date +%Y%m%d)

Troubleshooting Guide

Issue: "Service not configured"

Symptoms:

  • Error in UI: "ASReview service not configured"
  • Health check returns: "configured": false

Solutions:

  1. Check ASREVIEW_SERVICE_URL in config.py
  2. Restart HARVEST to load new config
  3. Verify environment variables not overriding config

Issue: "Connection refused"

Symptoms:

  • Error: "Cannot connect to ASReview service"
  • Timeout on health check

Solutions:

  1. Verify ASReview service is running:

    curl http://gpu-server:5275/api/health

  2. Check firewall rules:

    sudo ufw status
telnet gpu-server 5275

  3. Check service logs:

    docker logs asreview

Issue: "Service unavailable"

Symptoms:

  • Service responds but returns errors
  • Slow response times

Solutions:

  1. Check GPU availability:

    nvidia-smi

  2. Check resource usage:

    docker stats asreview

  3. Restart ASReview:

    docker restart asreview

  4. Check disk space:

    df -h

Issue: "Authentication failed"

Symptoms:

  • "Unauthorized" errors
  • Admin check fails

Solutions:

  1. Verify admin user in HARVEST:

    python3 create_admin.py

  2. Check session cookies are set

  3. Verify admin email in config

Rollback Procedure

If deployment fails:

1. Disable Feature

# In config.py
ENABLE_LITERATURE_REVIEW = False

2. Restart HARVEST

pkill -f harvest_be.py
pkill -f harvest_fe.py
python3 launch_harvest.py

3. Stop ASReview Service

docker stop asreview
# or
pkill -f asreview

4. Restore Config

cp /backup/config.py.YYYYMMDD config.py

Upgrade Procedure

When upgrading ASReview version:

1. Backup Data

docker cp asreview:/data /backup/asreview-data-upgrade

2. Stop Service

docker stop asreview
docker rm asreview

3. Pull New Image

docker pull asreview/asreview:latest

4. Start New Version

docker run -d \
  --name asreview \
  --gpus all \
  -p 5275:5275 \
  -v asreview-data:/data \
  --restart unless-stopped \
  asreview/asreview:latest \
  asreview lab --host 0.0.0.0 --port 5275

5. Verify

curl http://gpu-server:5275/api/health

Security Checklist

☐ Network Security

  • ASReview service not exposed to public internet
  • Firewall rules restrict access to HARVEST only
  • Use VPN for remote ASReview service
  • HTTPS enabled for production (nginx)

☐ Authentication

  • Admin authentication required
  • Session management working correctly
  • API key configured (if needed)

☐ Data Privacy

  • ASReview service organization-controlled
  • Data retention policy configured
  • Backup encryption enabled
  • Access logs enabled

Performance Optimization

☐ GPU Configuration

# Check GPU memory
nvidia-smi --query-gpu=memory.used,memory.free --format=csv

# Limit GPU memory (if needed)
docker run ... -e TF_FORCE_GPU_ALLOW_GROWTH=true ...

☐ Resource Limits

# Docker resource limits
docker run ... \
  --memory=8g \
  --cpus=4 \
  ...

☐ Monitoring

  • Setup Prometheus/Grafana for metrics
  • Monitor GPU utilization
  • Track API response times
  • Alert on errors

Completion

  • All pre-deployment steps completed
  • Service deployed and verified
  • Monitoring configured
  • Documentation updated
  • Team trained
  • Backup procedures in place
  • Rollback procedure tested

Deployment Date: _______________

Deployed By: _______________

Service URL: _______________

Notes:

______________________________________________________________
______________________________________________________________
______________________________________________________________

Support Contacts

Overview

The Literature Review feature integrates ASReview, an AI-powered systematic review tool, into HARVEST. This feature helps researchers efficiently screen and shortlist literature by using active learning to predict paper relevance and prioritize review efforts.

What is ASReview?

ASReview is an open-source active learning tool for systematic literature reviews. It uses machine learning to:

  1. Learn from your decisions: The AI model trains on papers you mark as relevant or irrelevant
  2. Predict relevance: Estimates which unscreened papers are most likely to be relevant
  3. Prioritize screening: Shows you the most relevant papers first
  4. Reduce workload: Can reduce manual screening effort by 95% or more

Key Benefits

  • Efficient screening: Focus on likely-relevant papers first
  • AI-assisted decisions: ML model learns your criteria over time
  • Systematic approach: Structured review process with progress tracking
  • Export results: Get list of relevant papers for further analysis

Architecture

The Literature Review feature uses a remote service architecture for optimal performance:

┌─────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│                 │         │                  │         │                  │
│  HARVEST        │  HTTP   │  HARVEST         │  HTTP   │  ASReview        │
│  Frontend       │────────▶│  Backend         │────────▶│  Service         │
│  (Browser)      │         │  (Flask)         │         │  (GPU Server)    │
│                 │         │                  │         │                  │
└─────────────────┘         └──────────────────┘         └──────────────────┘

Why Remote Service?

ASReview requires:

  • GPU acceleration: For fast ML model training and inference
  • ML dependencies: TensorFlow/PyTorch and other heavy libraries
  • Computational resources: CPU/RAM for large datasets

By deploying ASReview on a separate GPU-enabled host, HARVEST remains lightweight while leveraging powerful ML capabilities when needed.

Setup Instructions

Step 1: Deploy ASReview Service

ASReview can be deployed in several ways:

Option A: Using Docker (Recommended)

# Pull official ASReview Docker image
docker pull asreview/asreview:latest

# Run ASReview service on GPU-enabled host
docker run -d \
  --name asreview-service \
  --gpus all \
  -p 5275:5275 \
  -v asreview-data:/data \
  --restart unless-stopped \
  asreview/asreview:latest \
  asreview lab --host 0.0.0.0 --port 5275

Option B: Using Python Virtual Environment

# On GPU-enabled server
ssh gpu-server

# Create virtual environment
python3 -m venv asreview-env
source asreview-env/bin/activate

# Install ASReview with GPU support
pip install asreview[all]
pip install tensorflow-gpu  # or pytorch with GPU support

# Start ASReview service
asreview lab --host 0.0.0.0 --port 5275

Option C: Using systemd Service

Create /etc/systemd/system/asreview.service:

[Unit]
Description=ASReview Service for HARVEST
After=network.target

[Service]
Type=simple
User=asreview
WorkingDirectory=/opt/asreview
ExecStart=/opt/asreview/venv/bin/asreview lab --host 0.0.0.0 --port 5275
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Then enable and start:

sudo systemctl daemon-reload
sudo systemctl enable asreview
sudo systemctl start asreview

Step 2: Configure HARVEST

Edit /home/runner/work/HARVEST/HARVEST/config.py:

# Literature Review Configuration (ASReview Integration)
ENABLE_LITERATURE_REVIEW = True  # Enable the feature

# ASReview Service URL - Update this with your ASReview server URL
ASREVIEW_SERVICE_URL = "http://asreview-gpu-host:5275"

# Optional: API key if your ASReview service requires authentication
ASREVIEW_API_KEY = ""

# Timeout settings
ASREVIEW_REQUEST_TIMEOUT = 300  # 5 minutes for long operations
ASREVIEW_CONNECTION_TIMEOUT = 10  # 10 seconds to establish connection

Configuration Options

Direct Connection:

ASREVIEW_SERVICE_URL = "http://192.168.1.100:5275"

Via Nginx Proxy:

ASREVIEW_SERVICE_URL = "https://yourdomain.com/asreview"

Same Host (for testing):

ASREVIEW_SERVICE_URL = "http://localhost:5275"

Step 3: Configure Nginx (Optional)

If using nginx proxy for ASReview service:

Add to your nginx configuration:

# ASReview service proxy
location /asreview/ {
    proxy_pass http://asreview-gpu-host:5275/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
    
    # Timeouts for long-running operations
    proxy_connect_timeout 10s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
}

Step 4: Verify Setup

Restart HARVEST and check the Literature Review feature:

# Restart HARVEST
python3 launch_harvest.py

# Check ASReview connectivity
curl http://localhost:5001/api/literature-review/health

Expected response:

{
  "ok": true,
  "available": true,
  "configured": true,
  "service_url": "http://asreview-gpu-host:5275",
  "version": "1.x.x",
  "status": "ok"
}

Usage Guide

1. Start from Literature Search

The Literature Review feature integrates with the existing Literature Search:

  1. Navigate to Literature Search tab
  2. Search for papers using semantic search
  3. Review and select papers of interest
  4. Click "Start Literature Review" button

2. Create Review Project

When starting a literature review:

  1. Project Name: Enter a descriptive name (e.g., "CRISPR Gene Editing Review 2024")

  2. Description: Optional notes about review criteria

  3. ML Model: Choose algorithm (Naive Bayes is default, recommended)

    • Naive Bayes (nb): Fast, works well with small training sets
    • SVM (svm): Powerful, requires more training data
    • Random Forest (rf): Robust, good for complex criteria
    • Logistic Regression (logistic): Interpretable, balanced performance

  4. Prior Knowledge (optional):

    • Mark papers you already know are relevant
    • Mark papers you know are irrelevant
    • Helps bootstrap the ML model

  5. Click "Create Project" to upload papers to ASReview

3. Screen Papers

ASReview presents papers in order of predicted relevance:

  1. Review paper details:

    • Title
    • Authors
    • Abstract
    • Relevance score (0-100%)

  2. Make decision:

    • ✅ Relevant: Paper meets your criteria
    • ❌ Irrelevant: Paper doesn't meet criteria
    • 📝 Note (optional): Document reason for decision

  3. Model learns: After each decision, the ML model updates and re-ranks remaining papers

  4. Progress tracking: See how many papers reviewed, estimated remaining

4. Complete Review

Stop screening when:

  • All papers reviewed: Systematic completion
  • Diminishing returns: Several consecutive irrelevant papers
  • Confidence threshold: Remaining papers below relevance threshold

5. Export Results

Export relevant papers to:

  • HARVEST Project: Create new annotation project
  • Download CSV: Export for external tools
  • Copy DOIs: Paste into other systems

Review Criteria Examples

ASReview learns your criteria from examples. For HARVEST use cases:

Example 1: Validation Studies

Relevant papers have:

  • Experimental validation (in vivo/in vitro)
  • Statistical analysis
  • Replication studies
  • Peer-reviewed

Irrelevant papers:

  • Pure computational predictions
  • Review articles
  • Opinion pieces
  • Preliminary conference abstracts

Example 2: Entity Relationships

Relevant papers describe:

  • Gene-phenotype relationships
  • Protein-protein interactions
  • Drug-target associations
  • Pathway mechanisms

Irrelevant papers:

  • General overviews
  • Taxonomy papers
  • Tool descriptions
  • Unrelated organisms/systems

Example 3: Stress Response Studies

Relevant papers:

  • Environmental stress experiments
  • Molecular stress responses
  • Survival/reproduction measurements
  • Stress biomarkers

Irrelevant papers:

  • Clinical/medical stress (wrong domain)
  • Psychological stress
  • Engineering stress analysis

API Reference

Health Check

GET /api/literature-review/health

Returns ASReview service status.

Create Project

POST /api/literature-review/projects
Content-Type: application/json

{
  "project_name": "My Review",
  "description": "Optional description",
  "model_type": "nb"
}

Upload Papers

POST /api/literature-review/projects/{project_id}/upload
Content-Type: application/json

{
  "papers": [
    {
      "title": "Paper Title",
      "abstract": "Abstract text",
      "authors": ["Author 1", "Author 2"],
      "doi": "10.1234/example",
      "year": 2024
    }
  ]
}

Start Review

POST /api/literature-review/projects/{project_id}/start
Content-Type: application/json

{
  "prior_relevant": ["10.1234/relevant"],
  "prior_irrelevant": ["10.5678/irrelevant"]
}

Get Next Paper

GET /api/literature-review/projects/{project_id}/next

Returns next paper to screen.

Record Decision

POST /api/literature-review/projects/{project_id}/record
Content-Type: application/json

{
  "paper_id": "10.1234/example",
  "relevant": true,
  "note": "Has experimental validation"
}

Get Progress

GET /api/literature-review/projects/{project_id}/progress

Returns review statistics.

Export Results

GET /api/literature-review/projects/{project_id}/export

Returns list of relevant papers.

Troubleshooting

Service Not Available

Symptom: "ASReview service not configured" error

Solutions:

  1. Check ASREVIEW_SERVICE_URL in config.py
  2. Verify ASReview service is running
  3. Test connectivity: curl http://asreview-host:5275/api/health
  4. Check firewall rules allow connections

Connection Timeout

Symptom: Request timeout errors

Solutions:

  1. Increase ASREVIEW_REQUEST_TIMEOUT in config.py
  2. Check network latency between HARVEST and ASReview
  3. Verify ASReview service has adequate resources
  4. Check nginx proxy timeout settings

Slow Performance

Symptom: Slow paper screening, long waits

Solutions:

  1. Ensure ASReview service has GPU access
  2. Check GPU utilization: nvidia-smi
  3. Reduce concurrent reviews
  4. Upgrade to faster GPU
  5. Consider lighter ML model (nb instead of rf/svm)

Model Not Learning

Symptom: Poor relevance predictions, random ordering

Solutions:

  1. Provide more prior knowledge examples (5-10 relevant, 5-10 irrelevant)
  2. Be consistent in decision criteria
  3. Try different ML model type
  4. Ensure sufficient training data (>20 decisions)

MIME Type Errors / Static Files Not Loading

Symptom: Browser console errors like:

Error: Could not establish connection. Receiving end does not exist.
GET https://domain.com/static/js/main.xxx.js NS_ERROR_CORRUPTED_CONTENT
The resource was blocked due to MIME type ("text/html") mismatch (X-Content-Type-Options: nosniff)

Cause: ASReview is a React Single Page Application (SPA) that serves static assets (JavaScript, CSS) from /static/ paths. When proxied through HARVEST, these assets may:

  1. Be served with incorrect MIME types (e.g., text/html instead of application/javascript)
  2. Have incorrect base paths, causing the browser to request them from the wrong location

Solution: This issue has been fixed in the HARVEST proxy implementation. The proxy now:

  1. Detects correct MIME types from file extensions (.js, .css, .json, etc.)
  2. Injects <base> tag into HTML responses to fix relative URL resolution
  3. Overrides incorrect Content-Type headers for static assets

If you're still experiencing this issue after updating HARVEST:

  1. Verify you have the latest version with the proxy fix:

    cd /home/runner/work/HARVEST/HARVEST
git pull

  2. Clear browser cache to remove cached responses:

    • Open browser DevTools (F12)
    • Right-click reload button → "Empty Cache and Hard Reload"
    • Or use Incognito/Private mode

  3. Check proxy configuration:

    • Ensure ASREVIEW_SERVICE_URL is correct in config.py
    • If using nginx, verify the proxy configuration passes all requests correctly

  4. Verify ASReview service is returning correct responses:

    # Test direct access to ASReview (should return HTML)
curl -i http://asreview-host:5275/

# Test static file directly (should return JavaScript)
curl -i http://asreview-host:5275/static/js/main.xxx.js

  5. Check HARVEST logs for proxy errors:

    tail -f harvest.log | grep -i "asreview\|proxy"

Technical Details:

  • HARVEST's /proxy/asreview/ route now handles React SPA routing properly
  • HTML responses receive a <base href="/proxy/asreview/"> tag injection
  • Static assets (.js, .css, .json, fonts, images) have their Content-Type corrected
  • This allows ASReview to load correctly within HARVEST's iframe

Security Considerations

Authentication

  • Literature Review requires admin authentication
  • All API endpoints check admin status
  • Session-based authentication via cookies

Network Security

  • ASReview service should be on trusted network
  • Use HTTPS for production deployments
  • Configure firewall to restrict ASReview access
  • Consider VPN for remote ASReview service

Data Privacy

  • Papers uploaded to ASReview service
  • Service may store metadata temporarily
  • Configure ASReview data retention policies
  • Use organization-controlled ASReview instance

Best Practices

Project Organization

  1. One review per topic: Keep reviews focused
  2. Meaningful names: Use descriptive project names
  3. Document criteria: Note inclusion/exclusion criteria in description
  4. Export regularly: Save results incrementally

Screening Strategy

  1. Start with 10-20 decisions: Train model with diverse examples
  2. Be consistent: Apply same criteria throughout
  3. Add notes: Document decision rationale
  4. Review in sessions: Avoid decision fatigue
  5. Trust the model: Papers are prioritized intelligently

Quality Control

  1. Double-check borderline papers: Review low-confidence decisions
  2. Sample irrelevant papers: Periodically verify excluded papers
  3. Track agreement: Monitor consistency over time
  4. Export for validation: Have second reviewer check results

Performance Tuning

GPU Configuration

For optimal ASReview performance:

# Check GPU availability
nvidia-smi

# Set GPU memory growth (TensorFlow)
export TF_FORCE_GPU_ALLOW_GROWTH=true

# Limit GPU memory (if shared)
export CUDA_VISIBLE_DEVICES=0

Model Selection Guide

Model Type Speed Accuracy Data Needed Best For
Naive Bayes ⚡⚡⚡ ⭐⭐ Low Quick reviews, small datasets
Logistic ⚡⚡ ⭐⭐⭐ Medium Balanced performance
SVM ⚡ ⭐⭐⭐ High Complex criteria, large datasets
Random Forest ⚡⚡ ⭐⭐⭐⭐ High Best accuracy, slower

Batch Operations

For large reviews (>1000 papers):

  1. Upload in batches of 500 papers
  2. Screen in sessions of 50-100 decisions
  3. Export results periodically
  4. Monitor memory usage on ASReview host

Integration with HARVEST Workflow

Complete Workflow

  1. Search → Literature Search tab

    • Query multiple sources
    • Gather initial candidate papers

  2. Review → Literature Review feature

    • Upload papers to ASReview
    • AI-assisted screening
    • Shortlist relevant papers

  3. Annotate → Annotate tab

    • Extract entity relationships
    • Add triples for relevant papers
    • Build knowledge base

  4. Analyze → Browse tab

    • Query annotations
    • Visualize relationships
    • Export data

Project Management

Link Literature Review with HARVEST Projects:

  1. Create HARVEST project from Literature Search
  2. Start Literature Review for same papers
  3. Export relevant papers from review
  4. Focus annotation efforts on reviewed papers

Advanced Features

Custom Model Configuration

For advanced users, ASReview can be configured with:

  • Custom feature extraction
  • Ensemble models
  • Transfer learning from previous reviews
  • Domain-specific embeddings

See ASReview documentation for details.

Programmatic Access

Use ASReview client directly in Python:

from asreview_client import get_asreview_client

client = get_asreview_client()

# Create project
result = client.create_project("My Review")
project_id = result['project_id']

# Upload papers
papers = [...]  # From literature search
client.upload_papers(project_id, papers)

# Start review
client.start_review(project_id)

# Screen papers
while True:
    result = client.get_next_paper(project_id)
    if result['paper'] is None:
        break
    
    paper = result['paper']
    # Make decision (relevant = True/False)
    relevant = decide_relevance(paper)
    client.record_decision(project_id, paper['doi'], relevant)

# Export results
results = client.export_results(project_id)
relevant_papers = results['relevant_papers']

Deployment Architectures

Single Server Setup

For small teams or testing:

┌─────────────────────────────────┐
│  Same Host                      │
│                                 │
│  ┌──────────┐  ┌────────────┐  │
│  │ HARVEST  │  │ ASReview   │  │
│  │ :8050    │  │ :5275      │  │
│  └──────────┘  └────────────┘  │
│                                 │
└─────────────────────────────────┘

Multi-Server Setup

For production with GPU:

┌──────────────┐         ┌──────────────────┐
│ HARVEST      │         │ GPU Server       │
│ Server       │  HTTP   │                  │
│              │────────▶│ ASReview Service │
│ Web + API    │         │ :5275            │
└──────────────┘         └──────────────────┘

Nginx Proxy Setup

For enterprise deployments:

                ┌─────────────────┐
                │  Nginx Proxy    │
                │  :443 (HTTPS)   │
                └────────┬────────┘
                         │
         ┌───────────────┴───────────────┐
         ▼                               ▼
┌─────────────────┐            ┌─────────────────┐
│ HARVEST         │            │ ASReview        │
│ /harvest/*      │            │ /asreview/*     │
│ :8050           │            │ :5275           │
└─────────────────┘            └─────────────────┘

Future Enhancements

Planned features:

  • Collaborative reviews: Multiple reviewers with conflict resolution
  • Review templates: Pre-configured criteria for common review types
  • Citation network: Visualize paper relationships
  • Automated exports: Schedule exports to HARVEST projects
  • Progress dashboards: Visualize review progress over time
  • Quality metrics: Inter-rater reliability, decision confidence

Support and Resources

Documentation

Getting Help

  1. Check this documentation
  2. Review ASReview tutorials: https://asreview.ai/tutorials
  3. Open GitHub issue for HARVEST integration problems
  4. Contact ASReview community for ASReview-specific questions

Citation

If you use this feature in research, please cite:

HARVEST: (Add HARVEST citation here)

ASReview:

van de Schoot, R., de Bruin, J., Schram, R., Zahedi, P., de Boer, J., Weijdema, F., ...
& Oberski, D. L. (2021). ASReview: Open Source Software for Efficient and Transparent
Active Learning for Systematic Reviews. Nature Machine Intelligence, 3(2), 125–133.
https://doi.org/10.1038/s42256-020-00287-7

License

ASReview is licensed under Apache License 2.0. See ASReview project for details.