Skip to content

Gimmick12-DYY/ADRD-KG

Repository files navigation

ADRD Knowledge Graph

A comprehensive information sharing website for Alzheimer's Disease and Related Dementia (ADRD) research datasets and publications.

Overview

The ADRD Knowledge Graph is a modern web application built with Flask (backend) and React (frontend) that serves as a centralized platform for exploring and accessing ADRD research data. It provides researchers with tools to discover datasets, browse publications, and understand relationships within the ADRD research ecosystem.

Features

Dataset Discovery

  • Browse comprehensive collection of ADRD research datasets
  • Advanced filtering by disease type, data modality, sample size, and accessibility
  • Detailed metadata including sample sizes, data types, and access requirements
  • Visual analytics and distribution charts

Publication Database

  • Searchable database of research publications linked to datasets
  • PubMed and DOI integration for direct access to papers
  • Filter by dataset, publication year, and research topics
  • Author and journal information

Knowledge Graph (Coming Soon)

  • Interactive visualization of relationships between datasets, publications, and researchers
  • Network analysis of research collaborations
  • Temporal analysis of research trends
  • Entity relationship discovery

Documentation & API

  • Comprehensive API documentation
  • Data access procedures and guidelines
  • Privacy and security information
  • Technical support resources

Technology Stack

Backend (Flask)

  • Flask 2.3.3 - Web framework
  • Flask-SQLAlchemy - Database ORM
  • Flask-CORS - Cross-origin resource sharing
  • Pandas - Data processing
  • SQLite - Database (easily upgradeable to PostgreSQL)

Frontend (React)

  • React 18 with TypeScript
  • Material-UI (MUI) - Modern UI components
  • React Router - Client-side routing
  • Recharts - Data visualization
  • Axios - HTTP client

Project Structure

ADRD-KG/
├── backend/
│   ├── app.py                 # Flask application
│   └── requirements.txt       # Python dependencies
├── frontend/
│   ├── public/
│   ├── src/
│   │   ├── components/        # Reusable UI components
│   │   ├── pages/            # Page components
│   │   ├── services/         # API service layer
│   │   ├── App.tsx           # Main application
│   │   └── index.tsx         # Application entry point
│   └── package.json          # Node.js dependencies
├── ADRD_Metadata_Sample.xlsx  # Sample dataset metadata
├── pubmed_refs_fetched.csv    # Sample publication data
└── README.md

Installation Guide

Step 1: Clone the Repository

# Clone the repository
git clone https://github.com/your-username/ADRD-KG.git
cd ADRD-KG

Step 2: Backend Setup

2.1 Navigate to Backend Directory

cd backend

2.2 Create Virtual Environment

On Windows:

python -m venv venv
venv\Scripts\activate

On macOS/Linux:

python3 -m venv venv
source venv/bin/activate

Note: If you have multiple Python versions, use python3 instead of python

2.3 Upgrade pip and Install Dependencies

# Upgrade pip to latest version
python -m pip install --upgrade pip setuptools wheel

# Install Python dependencies
pip install -r requirements.txt

2.4 Verify Backend Installation

# Test the Flask application
python app.py

You should see output similar to:

 * Running on http://127.0.0.1:5000
 * Debug mode: on

Test the API: Open a new terminal and run:

curl http://localhost:5000/api/health

Expected response:

{"status": "healthy", "message": "ADRD Knowledge Graph API is running"}

Step 3: Frontend Setup

3.1 Navigate to Frontend Directory

# From the project root
cd frontend

3.2 Install Node.js Dependencies

# Install all required packages
npm install

3.3 Start the Development Server

# Start the React development server
npm run dev

The application will be available at http://localhost:5173

Step 4: Verify Complete Setup

  1. Backend API: Visit http://localhost:5000/api/health
  2. Frontend Application: Visit http://localhost:5173
  3. Full Application: The frontend should connect to the backend automatically

Quick Start Script

For convenience, you can use the provided startup script:

# Make the script executable (macOS/Linux)
chmod +x start.sh

# Run both backend and frontend
./start.sh

Windows users: Run the commands manually in separate terminals:

# Terminal 1 - Backend
cd backend
venv\Scripts\activate
python app.py

# Terminal 2 - Frontend
cd frontend
npm run dev

Detailed Setup Instructions

Backend Configuration

Environment Variables (Optional)

Create a .env file in the backend directory:

FLASK_ENV=development
FLASK_DEBUG=True
DATABASE_URL=sqlite:///adrd_knowledge_graph.db

Database Initialization

The SQLite database is automatically created on first run. To reset the database:

cd backend
rm instance/adrd_knowledge_graph.db
python app.py

Custom Port Configuration

To run on a different port:

export FLASK_RUN_PORT=8000  # macOS/Linux
set FLASK_RUN_PORT=8000     # Windows
python app.py

Frontend Configuration

Vite Configuration

The frontend uses Vite for development. Configuration is in frontend/vite.config.ts:

  • Proxy: API calls to /api/* are automatically proxied to http://localhost:5000
  • Port: Default development port is 5173

Custom Port Configuration

To run on a different port:

npm run dev -- --port 3000

Build for Production

npm run build

The built files will be in the dist/ directory.

Troubleshooting

Common Issues and Solutions

Python Installation Issues

Issue: python: command not found

# macOS (using Homebrew)
brew install python@3.11

# Ubuntu/Debian
sudo apt update
sudo apt install python3.11 python3.11-venv

# Windows
# Download from https://python.org/downloads/

Issue: pip: command not found

# Install pip
python -m ensurepip --upgrade
# or
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py

Python 3.13 Compatibility Issues

Error: AttributeError: module 'pkgutil' has no attribute 'ImpImporter'

Solution 1: Use Python 3.11 or 3.12 (Recommended)

# Install Python 3.12
# macOS
brew install python@3.12
python3.12 -m venv venv

# Ubuntu
sudo apt install python3.12 python3.12-venv
python3.12 -m venv venv

Solution 2: Force Installation

pip install --no-build-isolation -r requirements.txt

Solution 3: Install Packages Individually

pip install Flask==2.3.3
pip install Flask-CORS==4.0.0
pip install Flask-SQLAlchemy==3.0.5
pip install pandas==2.0.3
pip install openpyxl==3.1.2

Node.js Installation Issues

Issue: npm: command not found

macOS:

# Using Homebrew
brew install node

# Using Node Version Manager (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Ubuntu/Debian:

# Install Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows:

  • Download from https://nodejs.org/
  • Choose the LTS version
  • Ensure "Add to PATH" is checked during installation

Backend Connection Issues

Issue: Frontend can't connect to backend

  1. Check if backend is running:

    curl http://localhost:5000/api/health
  2. Check firewall settings:

    • Windows: Allow Python through Windows Firewall
    • macOS: System Preferences > Security & Privacy > Firewall
    • Linux: sudo ufw allow 5000
  3. Check port conflicts:

    # Check if port 5000 is in use
    netstat -an | grep 5000  # macOS/Linux
    netstat -an | findstr 5000  # Windows

Frontend Build Issues

Issue: npm install fails

  1. Clear npm cache:

    npm cache clean --force
  2. Delete node_modules and reinstall:

    rm -rf node_modules package-lock.json
    npm install
  3. Use different package manager:

    # Try with yarn
    npm install -g yarn
    yarn install

Issue: Vite development server issues

  1. Check if port 5173 is available:

    npm run dev -- --port 3000
  2. Clear Vite cache:

    rm -rf node_modules/.vite
    npm run dev

Platform-Specific Notes

Windows

  • Use PowerShell or Command Prompt as Administrator for installation
  • Ensure Python and Node.js are added to PATH
  • Use venv\Scripts\activate for virtual environment activation
  • Consider using Windows Subsystem for Linux (WSL) for better compatibility

macOS

  • Install Xcode Command Line Tools: xcode-select --install
  • Use Homebrew for package management: brew install python@3.11 node
  • May need to allow Python through System Preferences > Security & Privacy

Linux (Ubuntu/Debian)

  • Update package lists: sudo apt update
  • Install build essentials: sudo apt install build-essential
  • May need to install additional dependencies for some Python packages

Development Workflow

Making Changes

  1. Backend Changes:

    • Edit files in backend/
    • Flask auto-reloads on file changes
    • Test API endpoints with curl or Postman
  2. Frontend Changes:

    • Edit files in frontend/src/
    • Vite hot-reloads on file changes
    • Browser automatically refreshes

Adding New Features

  1. Backend API:

    # Add new route in backend/app.py
    @app.route('/api/new-endpoint', methods=['GET'])
    def new_endpoint():
        return jsonify({"message": "New feature"})
  2. Frontend Component:

    // Create new component in frontend/src/components/
    import React from 'react';
    
    const NewComponent: React.FC = () => {
      return <div>New Component</div>;
    };
    
    export default NewComponent;

Database Management

View Database:

# Install SQLite browser
# macOS: brew install --cask db-browser-for-sqlite
# Windows: Download from https://sqlitebrowser.org/
# Linux: sudo apt install sqlitebrowser

# Open database
sqlite3 backend/instance/adrd_knowledge_graph.db

Reset Database:

cd backend
rm instance/adrd_knowledge_graph.db
python app.py

Production Deployment

Backend Deployment

  1. Set Environment Variables:

    export FLASK_ENV=production
    export FLASK_DEBUG=False
  2. Use Production WSGI Server:

    pip install gunicorn
    gunicorn -w 4 -b 0.0.0.0:5000 app:app

Frontend Deployment

  1. Build for Production:

    npm run build
  2. Serve Static Files:

    # Using serve
    npm install -g serve
    serve -s dist -l 3000
    
    # Or deploy to static hosting (Netlify, Vercel, etc.)

Docker Deployment (Optional)

Backend Dockerfile:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["python", "app.py"]

Frontend Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "preview"]

Support and Contributing

Getting Help

  1. Check the troubleshooting section above
  2. Review existing issues on GitHub
  3. Create a new issue with:
    • Operating system and version
    • Python and Node.js versions
    • Complete error messages
    • Steps to reproduce the issue

Contributing

  1. Fork the repository
  2. Create a feature branch:
    git checkout -b feature/new-feature
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

Code Style

  • Python: Follow PEP 8 guidelines
  • TypeScript/React: Use ESLint and Prettier configurations
  • Commits: Use conventional commit messages

API Endpoints

Core Endpoints

  • GET /api/health - Health check
  • GET /api/datasets - Retrieve datasets with filtering
  • GET /api/datasets/{id} - Get specific dataset
  • GET /api/publications - Retrieve publications with filtering
  • GET /api/stats - Get summary statistics
  • GET /api/filters - Get available filter options

Query Parameters

Datasets:

  • disease_type - Filter by disease type
  • modality - Filter by data modality
  • search - Search dataset names
  • page - Page number
  • per_page - Results per page

Publications:

  • dataset_name - Filter by associated dataset
  • title_search - Search publication titles
  • year - Filter by publication year

Data Sources

The application currently supports:

  • Excel metadata files for dataset information
  • CSV files for publication data
  • Extensible architecture for additional data sources

Development

Adding New Features

  1. Backend: Add new routes in backend/app.py
  2. Frontend: Create components in frontend/src/components/ or pages in frontend/src/pages/
  3. API Integration: Update frontend/src/services/apiService.ts

Database Schema

The application uses SQLAlchemy models:

  • Dataset - Dataset metadata and information
  • Publication - Research publication details

Styling

The frontend uses Material-UI with a custom theme:

  • Primary color: #004c97 (Deep blue)
  • Secondary color: #8E7DBE (Dusty lavender)
  • Consistent spacing and typography

Known Issues & Solutions

Python 3.13 Compatibility

Some Python packages haven't fully updated for Python 3.13 compatibility, causing pkgutil.ImpImporter errors.

Solutions:

  1. Use Python 3.11 or 3.12 (Most reliable)
  2. Try the no-build-isolation flag: pip install --no-build-isolation -r requirements.txt
  3. Install packages individually as shown in the troubleshooting section above

Windows-Specific Issues

  • Ensure you're using the correct virtual environment activation command: venv\Scripts\activate
  • If you encounter permission errors, run PowerShell as Administrator
  • Consider using Windows Subsystem for Linux (WSL) for a more Unix-like environment

Node.js/npm Issues

  • If npm is not recognized, ensure Node.js is properly installed and added to PATH
  • Try using npx instead of npm for package execution
  • Clear npm cache if installation fails: npm cache clean --force

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

For questions, support, or collaboration opportunities:

Acknowledgments

  • ADNI (Alzheimer's Disease Neuroimaging Initiative)
  • AMP-AD (Accelerating Medicines Partnership - Alzheimer's Disease)
  • NACC (National Alzheimer's Coordinating Center)
  • All contributing research institutions and datasets

About

Home Repository for ADRD-KG, Data-Literature Linkage Project for Alzheimer's Disease

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published