A comprehensive information sharing website for Alzheimer's Disease and Related Dementia (ADRD) research datasets and publications.
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.
- 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
- 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
- Interactive visualization of relationships between datasets, publications, and researchers
- Network analysis of research collaborations
- Temporal analysis of research trends
- Entity relationship discovery
- Comprehensive API documentation
- Data access procedures and guidelines
- Privacy and security information
- Technical support resources
- 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)
- React 18 with TypeScript
- Material-UI (MUI) - Modern UI components
- React Router - Client-side routing
- Recharts - Data visualization
- Axios - HTTP client
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
# Clone the repository
git clone https://github.com/your-username/ADRD-KG.git
cd ADRD-KG
cd backend
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 ofpython
# Upgrade pip to latest version
python -m pip install --upgrade pip setuptools wheel
# Install Python dependencies
pip install -r requirements.txt
# 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"}
# From the project root
cd frontend
# Install all required packages
npm install
# Start the React development server
npm run dev
The application will be available at http://localhost:5173
- Backend API: Visit
http://localhost:5000/api/health
- Frontend Application: Visit
http://localhost:5173
- Full Application: The frontend should connect to the backend automatically
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
Create a .env
file in the backend directory:
FLASK_ENV=development
FLASK_DEBUG=True
DATABASE_URL=sqlite:///adrd_knowledge_graph.db
The SQLite database is automatically created on first run. To reset the database:
cd backend
rm instance/adrd_knowledge_graph.db
python app.py
To run on a different port:
export FLASK_RUN_PORT=8000 # macOS/Linux
set FLASK_RUN_PORT=8000 # Windows
python app.py
The frontend uses Vite for development. Configuration is in frontend/vite.config.ts
:
- Proxy: API calls to
/api/*
are automatically proxied tohttp://localhost:5000
- Port: Default development port is 5173
To run on a different port:
npm run dev -- --port 3000
npm run build
The built files will be in the dist/
directory.
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
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
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
Issue: Frontend can't connect to backend
-
Check if backend is running:
curl http://localhost:5000/api/health
-
Check firewall settings:
- Windows: Allow Python through Windows Firewall
- macOS: System Preferences > Security & Privacy > Firewall
- Linux:
sudo ufw allow 5000
-
Check port conflicts:
# Check if port 5000 is in use netstat -an | grep 5000 # macOS/Linux netstat -an | findstr 5000 # Windows
Issue: npm install
fails
-
Clear npm cache:
npm cache clean --force
-
Delete node_modules and reinstall:
rm -rf node_modules package-lock.json npm install
-
Use different package manager:
# Try with yarn npm install -g yarn yarn install
Issue: Vite development server issues
-
Check if port 5173 is available:
npm run dev -- --port 3000
-
Clear Vite cache:
rm -rf node_modules/.vite npm run dev
- 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
- 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
- Update package lists:
sudo apt update
- Install build essentials:
sudo apt install build-essential
- May need to install additional dependencies for some Python packages
-
Backend Changes:
- Edit files in
backend/
- Flask auto-reloads on file changes
- Test API endpoints with curl or Postman
- Edit files in
-
Frontend Changes:
- Edit files in
frontend/src/
- Vite hot-reloads on file changes
- Browser automatically refreshes
- Edit files in
-
Backend API:
# Add new route in backend/app.py @app.route('/api/new-endpoint', methods=['GET']) def new_endpoint(): return jsonify({"message": "New feature"})
-
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;
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
-
Set Environment Variables:
export FLASK_ENV=production export FLASK_DEBUG=False
-
Use Production WSGI Server:
pip install gunicorn gunicorn -w 4 -b 0.0.0.0:5000 app:app
-
Build for Production:
npm run build
-
Serve Static Files:
# Using serve npm install -g serve serve -s dist -l 3000 # Or deploy to static hosting (Netlify, Vercel, etc.)
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"]
- Check the troubleshooting section above
- Review existing issues on GitHub
- Create a new issue with:
- Operating system and version
- Python and Node.js versions
- Complete error messages
- Steps to reproduce the issue
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature
- Make your changes
- Test thoroughly
- Submit a pull request
- Python: Follow PEP 8 guidelines
- TypeScript/React: Use ESLint and Prettier configurations
- Commits: Use conventional commit messages
GET /api/health
- Health checkGET /api/datasets
- Retrieve datasets with filteringGET /api/datasets/{id}
- Get specific datasetGET /api/publications
- Retrieve publications with filteringGET /api/stats
- Get summary statisticsGET /api/filters
- Get available filter options
Datasets:
disease_type
- Filter by disease typemodality
- Filter by data modalitysearch
- Search dataset namespage
- Page numberper_page
- Results per page
Publications:
dataset_name
- Filter by associated datasettitle_search
- Search publication titlesyear
- Filter by publication year
The application currently supports:
- Excel metadata files for dataset information
- CSV files for publication data
- Extensible architecture for additional data sources
- Backend: Add new routes in
backend/app.py
- Frontend: Create components in
frontend/src/components/
or pages infrontend/src/pages/
- API Integration: Update
frontend/src/services/apiService.ts
The application uses SQLAlchemy models:
Dataset
- Dataset metadata and informationPublication
- Research publication details
The frontend uses Material-UI with a custom theme:
- Primary color:
#004c97
(Deep blue) - Secondary color:
#8E7DBE
(Dusty lavender) - Consistent spacing and typography
Some Python packages haven't fully updated for Python 3.13 compatibility, causing pkgutil.ImpImporter
errors.
Solutions:
- Use Python 3.11 or 3.12 (Most reliable)
- Try the no-build-isolation flag:
pip install --no-build-isolation -r requirements.txt
- Install packages individually as shown in the troubleshooting section above
- 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
- If npm is not recognized, ensure Node.js is properly installed and added to PATH
- Try using
npx
instead ofnpm
for package execution - Clear npm cache if installation fails:
npm cache clean --force
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
For questions, support, or collaboration opportunities:
- Technical Support: support@adrd-kg.org
- Research Collaboration: research@adrd-kg.org
- 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