Getting Started
A comprehensive guide to set up and use the ASL Methods Section Generator
This guide will help you set up and run the ASL Methods Section Generator project on your local machine. The project consists of three main components: a Python package, a FastAPI backend, and a Next.js frontend.
Required Software
- Docker & Docker Compose (Recommended for easy setup)
- Docker Desktop: Download here
- Docker Compose: Usually included with Docker Desktop
Alternative: Manual Setup
If you prefer to run components individually, you'll need:
- Python 3.11+ with pip
- Node.js 18+ with yarn
- Git for version control
Quick Start with Docker (Recommended)
The easiest way to get started is using Docker Compose, which will set up all components automatically.
2. Start the Application
docker-compose up --build --watch
This command will:
- Build the Docker images for both frontend and backend
- Start the containers
- Make the application available at:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
- Enable changes in the containers
3. Access the Application
Open your web browser and navigate to http://localhost:3000 to access the web interface.
Manual Setup (Advanced)
If you prefer to run components individually or contribute to development, follow these steps:
1. Python Package Setup
This step is only requried if you are going to do changes to the package code
# Navigate to the package directory
cd package
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
# Install the package in development mode
pip install -e .
2. Backend Setup
# Navigate to the backend directory
cd apps/backend
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Start the backend server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
3. Frontend Setup
# Navigate to the frontend directory
cd apps/frontend
# Install dependencies
yarn install
# Start the development server
yarn dev
š Project Structure Overview
ASL-Methods-Generator/
āāā package/ # Python package (pyaslreport)
ā āāā src/pyaslreport/ # Core package source code
ā āāā pyproject.toml # Package configuration
ā āāā requirements.txt # Package dependencies
āāā apps/
ā āāā frontend/ # Next.js web application
ā ā āāā src/ # Source code
ā ā āāā package.json # Frontend dependencies
ā ā āāā Dockerfile # Frontend container
ā āāā backend/ # FastAPI backend
ā āāā app/ # Backend source code
ā āāā requirements.txt # Backend dependencies
ā āāā Dockerfile # Backend container
āāā docs/ # Documentation
āāā docker-compose.yml # Container orchestration
1. Test the Backend API
# Test the API health endpoint
curl http://localhost:8000/
# Expected response:
{
"name": "ASL Methods Parameter Generator API Service",
"version": "0.0.1",
"description": "This service provides an API for generating ASL methods parameters based on user input.",
"organization": "The ISMRM Open Science Initiative for Perfusion Imaging",
"authors": [
{"Ibrahim Abdelazim": "ibrahim.abdelazim@fau.de"},
{"Hanliang Xu": "hxu110@jh.edu"}
],
"supervisors": [
"Jan Petr",
"David Thomas"
],
"Specs": {
"Programming Language": "Python",
"Framework": "FastAPI",
"Operating System": "OS Independent"
},
"license": "MIT"
}
2. Test the Frontend
- Open http://localhost:3000 in your browser
- You should see the main application interface
- Try uploading a sample file to test the functionality
3. Test the Python Package
# In a Python environment with the package installed
from pyaslreport import generate_report
# Test with sample data
data = {
"modality": "asl",
"files": ["path/to/sample.json"],
"nifti_file": "path/to/sample.nii"
}
# This will raise an error if files don't exist, but confirms the package is working
try:
result = generate_report(data)
print("Package is working correctly!")
except FileNotFoundError:
print("Package is working (files not found as expected)")
Download Sample Data
- Sample ASL BIDS Data: Download
Expected File Structure
sample_dataset/
āāā sub-01/
ā āāā ses-01/
ā ā āāā perf/
ā ā ā āāā sub-01_ses-01_asl.json
ā ā ā āāā sub-01_ses-01_asl.nii.gz
ā ā ā āāā sub-01_ses-01_m0scan.json
ā ā ā āāā sub-01_ses-01_m0scan.nii.gz
ā ā ā āāā sub-01_ses-01_asl.tsv
ā ā āāā anat/
ā ā āāā sub-01_ses-01_T1w.nii.gz
āāā dataset_description.json
1. Making Changes
# The application supports hot reloading
# Changes to frontend code will automatically refresh
# Changes to backend code will restart the server
# Changes to the Python package require restarting the backend
2. Running Tests
# Backend tests
cd apps/backend
python -m pytest
# Frontend tests
cd apps/frontend
yarn test
# Package tests
cd package
python -m pytest
3. Code Quality
# Frontend linting
cd apps/frontend
yarn lint
# Backend formatting
cd apps/backend
black .
isort .
Next Steps
Now that you have the application running, you can:
- Explore the Web Interface: Upload sample data and generate reports
- Read the Documentation: Check out the User Guide for detailed usage instructions
- Explore the API: Visit http://localhost:8000/docs for interactive API documentation
- Contribute: Check out the Contributing Guide for development guidelines
Getting Help
If you encounter issues:
- Check the Troubleshooting section above
- Review the logs: Use
docker-compose logsfor detailed error information - Search existing issues: Check the project's issue tracker
- Create a new issue: Provide detailed information about your setup and the problem
Need Help? If you're still having trouble, check out our Troubleshooting Guide or join our community discussions.