diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..0109de6 Binary files /dev/null and b/.DS_Store differ diff --git a/docs/.DS_Store b/docs/.DS_Store index 5008ddf..6e5a6bb 100644 Binary files a/docs/.DS_Store and b/docs/.DS_Store differ diff --git a/docs/AnalysisToolboxes.md b/docs/AnalysisToolboxes.md new file mode 100644 index 0000000..1424c72 --- /dev/null +++ b/docs/AnalysisToolboxes.md @@ -0,0 +1,83 @@ +# Analysis Toolboxes for Perfusion MRI + +This page provides an overview of software tools and packages designed for the analysis of contrast-agent based perfusion MRI data. + +## Overview + +Perfusion MRI analysis toolboxes provide implementations of various algorithms for quantifying perfusion parameters from DCE-MRI and DSC-MRI data. These tools facilitate the conversion of signal intensity time courses into quantitative perfusion metrics using pharmacokinetic models and other quantification approaches. + +## Available Analysis Toolboxes + +### QIN-PROQC (Quantitative Imaging Network - Perfusion Research Oncology Quality Control) + +**Developer**: Quantitative Imaging Network (QIN) +**Repository**: [GitHub Repository](https://github.com/DrSidG/QIN-PROQC) +**Description**: A MATLAB-based platform for quality control and standardization of DCE-MRI analysis in oncology. It includes implementations of several tracer kinetic models including Tofts, Extended Tofts, and Patlak. + +### ROCKETSHIP + +**Developer**: Stanford University +**Repository**: [GitHub Repository](https://github.com/petmri/ROCKETSHIP) +**Description**: A MATLAB-based toolkit for kinetic modeling of DCE-MRI data. It provides a comprehensive workflow from T1 mapping to parametric map generation. + +### PkModeling + +**Developer**: Quantitative Image Informatics for Cancer Research (QIICR) +**Repository**: [GitHub Repository](https://github.com/QIICR/PkModeling) +**Description**: A C++ library for pharmacokinetic analysis of DCE-MRI, integrated with 3D Slicer via the PkModeling extension. + +### DCE-MRI.jl + +**Developer**: Julia MRI community +**Repository**: [GitHub Repository](https://github.com/notZaki/DCE-MRI.jl) +**Description**: A Julia package for DCE-MRI analysis with implementations of various pharmacokinetic models and AIF estimation methods. + +### DCE-Tool + +**Developer**: Danish Research Centre for Magnetic Resonance +**Website**: [DCE-Tool Website](https://www.drcmr.dk/software) +**Description**: A MATLAB-based tool for DCE-MRI analysis with a graphical user interface, supporting multiple pharmacokinetic models. + +### DSCoMAN (DSC-MRI Analysis) + +**Developer**: Medical College of Wisconsin +**Website**: [DSCoMAN Website](https://mcw.edu/departments/biophysics/research/software) +**Description**: A software package for the analysis of DSC-MRI data, providing relative and absolute cerebral blood flow, blood volume, and mean transit time maps. + +### Perfusion BASIL + +**Developer**: FMRIB Centre, University of Oxford +**Website**: [BASIL Website](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/BASIL) +**Description**: Although primarily designed for arterial spin labeling, BASIL includes tools that can be adapted for contrast-based perfusion analysis. + +## Comparison of Key Features + +| Toolbox | Platform | Models Supported | GUI | AIF | Open Source | +|---------|----------|------------------|-----|-----|-------------| +| QIN-PROQC | MATLAB | Tofts, ETM, Patlak | Yes | Manual, Auto | Yes | +| ROCKETSHIP | MATLAB | Tofts, ETM, 2CXM | Yes | Manual, Auto | Yes | +| PkModeling | C++/3D Slicer | Tofts, ETM | Yes | Manual | Yes | +| DCE-MRI.jl | Julia | Tofts, ETM, 2CXM | No | Manual, Auto | Yes | +| DCE-Tool | MATLAB | Tofts, ETM, 2CXM | Yes | Manual | Yes | +| DSCoMAN | MATLAB | SVD, cSVD | Yes | Auto | Yes | +| BASIL | C++/FSL | Kinetic models | Yes | N/A | Yes | + +## How to Select an Analysis Toolbox + +Consider the following factors when selecting a toolbox for your perfusion MRI analysis: + +1. **Compatibility**: Ensure the toolbox works with your data format and operating system +2. **Models implemented**: Check if the toolbox includes the pharmacokinetic models you need +3. **Validation**: Look for toolboxes that have been validated in published literature +4. **Support and documentation**: Consider the availability of documentation and user support +5. **Customizability**: Determine if you need to modify or extend the existing analysis methods + +## Contributing + +If you have developed an analysis toolbox for contrast-agent based perfusion MRI that you would like to add to this list, please see our [contribution guidelines](contributionTutorial.md). + +## References + +1. Sourbron SP, Buckley DL. Tracer kinetic modelling in MRI: estimating perfusion and capillary permeability. Phys Med Biol. 2012;57(2):R1-33. +2. Heye AK, et al. Assessment of blood-brain barrier disruption using dynamic contrast-enhanced MRI. A systematic review. NeuroImage Clin. 2014;6:262-74. +3. Jahng GH, et al. Perfusion magnetic resonance imaging: a comprehensive update on principles and techniques. Korean J Radiol. 2014;15(5):554-77. \ No newline at end of file diff --git a/docs/SampleDatasets.md b/docs/SampleDatasets.md new file mode 100644 index 0000000..7828b94 --- /dev/null +++ b/docs/SampleDatasets.md @@ -0,0 +1,79 @@ +# Sample Datasets for Perfusion MRI + +This page provides links to publicly available contrast-agent based perfusion MRI datasets that can be used for research, development, and validation of analysis methods. + +## Overview + +Sample datasets are essential resources for: +- Developing and validating new analysis methods +- Benchmarking different software tools +- Reproducing published results +- Training and education +- Harmonizing acquisition and analysis protocols across sites + +## Available Datasets + +### QIN Breast DCE-MRI Dataset + +**Provider**: Cancer Imaging Archive (TCIA), Quantitative Imaging Network (QIN) +**Access**: [TCIA QIN Breast DCE-MRI](https://wiki.cancerimagingarchive.net/display/Public/QIN+Breast+DCE-MRI) +**Description**: Multisite, multivendor breast DCE-MRI data with associated clinical data. Includes pre-treatment and early-treatment images for monitoring response to neoadjuvant chemotherapy. + +### RIDER Neuro MRI Dataset + +**Provider**: Cancer Imaging Archive (TCIA) +**Access**: [TCIA RIDER Neuro MRI](https://wiki.cancerimagingarchive.net/display/Public/RIDER+Neuro+MRI) +**Description**: DCE-MRI and DSC-MRI scans of brain tumors with test-retest data for reproducibility assessment. + +### SPIE-AAPM-NCI PROSTATEx Challenge + +**Provider**: Cancer Imaging Archive (TCIA) +**Access**: [PROSTATEx](https://wiki.cancerimagingarchive.net/display/Public/SPIE-AAPM-NCI+PROSTATEx+Challenges) +**Description**: Multiparametric MRI of the prostate including DCE-MRI sequences. Includes expert annotations for lesion classification. + +### Perfusion Training Dataset + +**Provider**: OSIPI Task Force 4.1 +**Access**: [OSIPI Perfusion Training Dataset](https://github.com/OSIPI/OSIPI_StandardizedDatatsets) +**Description**: Standardized DCE-MRI and DSC-MRI datasets with known ground truth values, specifically curated for training and educational purposes. + +### DCE MRI Phantom Dataset + +**Provider**: National Institute of Standards and Technology (NIST) +**Access**: [NIST Quantitative MRI](https://www.nist.gov/programs-projects/quantitative-mri) +**Description**: Phantom data for testing and validating DCE-MRI quantification methods with controlled conditions and known T1 values. + +### KISSDB (Kantonsspital St. Gallen Brain Dataset) + +**Provider**: Kantonsspital St. Gallen, Switzerland +**Access**: [KISSDB Website](https://www.kispi.uzh.ch/en/research/downloads) +**Description**: DSC-MRI brain perfusion dataset with manual segmentation of stroke lesions and tissue types. + +## Dataset Specifications + +| Dataset | Modality | Anatomy | # of Subjects | Field Strength | Temporal Resolution | AIF Available | +|---------|----------|---------|---------------|----------------|---------------------|---------------| +| QIN Breast | DCE-MRI | Breast | 67 | 1.5T, 3T | Variable | Yes (some) | +| RIDER Neuro | DCE/DSC | Brain | 19 | 1.5T, 3T | 5-6s | Yes | +| PROSTATEx | DCE-MRI | Prostate | 204 | 3T | 3.5-5s | No | +| OSIPI Training | DCE/DSC | Various | 20 | 1.5T, 3T | Variable | Yes | +| NIST Phantom | DCE-MRI | Phantom | N/A | 1.5T, 3T | Variable | N/A | +| KISSDB | DSC-MRI | Brain | 151 | 1.5T | 1-2s | Yes | + +## How to Use These Datasets + +1. **Registration**: Most datasets require user registration and agreement to data use terms +2. **Download**: Follow the provider's instructions for downloading the data +3. **Format conversion**: You may need to convert data to formats compatible with your analysis tools +4. **Documentation**: Review the accompanying documentation for acquisition parameters and other metadata +5. **Citation**: Always cite the dataset in your publications according to the provider's guidelines + +## Contributing + +If you have a publicly available perfusion MRI dataset that you would like to add to this list, please see our [contribution guidelines](contributionTutorial.md). + +## References + +1. Kalpathy-Cramer J, et al. Quantitative Imaging Network: Data Sharing and Competitive Algorithm Validation Leveraging The Cancer Imaging Archive. Transl Oncol. 2014;7(1):147-52. +2. Shukla-Dave A, et al. Quantitative Imaging Biomarkers Alliance (QIBA) recommendations for improved precision of DWI and DCE-MRI derived biomarkers in multicenter oncology trials. J Magn Reson Imaging. 2019;49(7):e101-e121. +3. Huang W, et al. Variations of dynamic contrast-enhanced magnetic resonance imaging in evaluation of breast cancer therapy response: a multicenter data analysis challenge. Transl Oncol. 2014;7(1):153-66. \ No newline at end of file diff --git a/docs/improved-contribution-tutorial.md b/docs/improved-contribution-tutorial.md new file mode 100644 index 0000000..3f4d3fa --- /dev/null +++ b/docs/improved-contribution-tutorial.md @@ -0,0 +1,265 @@ +# Contributing to OSIPI CAPLEX + +If you follow this tutorial but find yourself stuck, please submit an issue in the github repository and include all steps you have taken and the full traceback to the error you've encountered so we may improve this page. + +This tutorial will guide you through contributing to the OSIPI CAPLEX website, even if you've never used GitHub, Git, or written code for a website before. + +## Quick Start Guide + +Choose one of these two approaches to get started: + +1. **Remote Development Environment** - Recommended for beginners (no installation required) +2. **Local Development Environment** - For those who prefer working on their own machine + +## 1. Remote Development Environment + +Using a development container through GitHub Codespaces is the quickest way to start contributing without installing anything on your computer. + +### Creating a GitHub Codespace + +1. Navigate to the [OSIPI CAPLEX repository](https://github.com/OSIPI/OSIPI_CAPLEX/tree/main-major-development) +2. Click the green `<> Code` button near the top of the page +3. Select the `Codespaces` tab +4. Click `Create codespace on main-major-development` +5. Wait for the environment to build (typically 1-2 minutes) + +![codespace gif](tutorialImgs/codespace gif.gif) + +### Working in the Codespace + +Once your codespace is ready: + +1. The repository files will appear in the file explorer on the left +2. Open the terminal at the bottom of the screen +3. Run `mkdocs serve` to build a local version of the website +4. Click on the URL that appears (typically http://127.0.0.1:8000) to view the site +5. Make your changes to any files using the editor +6. The website will automatically update as you save changes + +### Committing Your Changes + +1. Click the Source Control icon in the left sidebar (third icon from top) +2. Review your changes +3. Add a descriptive commit message +4. Click the checkmark to commit +5. Click the three dots (...) and select "Push" to send your changes to GitHub + +!!! warning "Important" + When you're done working, either stop or delete your codespace to avoid unnecessary usage. Click on the `<> Code` button, find the three dots next to your codespace, and select "Stop codespace" or "Delete codespace". + +## 2. Local Development Environment + +If you prefer working on your local machine, follow these steps to set up your environment. + +### Prerequisites + +You'll need to install: +1. A Git client +2. Python environment manager (we recommend Anaconda) +3. Visual Studio Code (or your preferred code editor) + +### Step 1: Install Anaconda + +[Download and install Anaconda](https://docs.anaconda.com/free/anaconda/install/index.html) to manage your Python environments. + +#### Windows Quick Setup (Alternative) + +Windows users can use `winget` to install everything with these commands: + +``` +winget install -e --id Git.Git +winget install -e --id Anaconda.Miniconda3 +winget install -e --id Microsoft.VisualStudioCode +``` + +### Step 2: Create a Python Environment + +1. Open Anaconda Prompt (Windows) or Terminal (MacOS/Linux) +2. Create a new environment: + ``` + conda create -n CAPLEX python + ``` +3. Activate the environment: + ``` + conda activate CAPLEX + ``` +4. Install MkDocs Material: + ``` + pip install mkdocs-material + ``` + +### Step 3: Set Up Git and GitHub + +1. [Create a GitHub account](https://github.com/signup) if you don't have one +2. Fork the [OSIPI CAPLEX repository](https://github.com/OSIPI/OSIPI_CAPLEX) +3. Clone your fork to your local machine: + ``` + git clone https://github.com/YOUR-USERNAME/OSIPI_CAPLEX.git + ``` +4. Configure Git with your identity: + ``` + git config --global user.name "Your Name" + git config --global user.email "your.email@example.com" + ``` + +### Step 4: Work on the Website Locally + +1. Navigate to your repository folder: + ``` + cd OSIPI_CAPLEX + ``` +2. Switch to the development branch: + ``` + git checkout main-major-development + ``` +3. Start the local server: + ``` + mkdocs serve + ``` +4. Open http://127.0.0.1:8000 in your browser +5. Make changes to the files using your code editor +6. Save the files to see the changes instantly in your browser + +### Step 5: Submit Your Changes + +1. Commit your changes: + ``` + git add . + git commit -m "Brief description of your changes" + ``` +2. Push to your fork: + ``` + git push origin main-major-development + ``` +3. Create a pull request: + - Go to your fork on GitHub + - Click "Compare & pull request" + - Review your changes and click "Create pull request" + +## Markdown and Website Editing Guide + +Now that you have your environment set up, let's look at how to edit content. + +### Understanding the Website Structure + +The OSIPI CAPLEX website is built using MkDocs with the Material theme. Here's what you need to know: + +- `mkdocs.yml` - Main configuration file that defines the website structure +- `docs/` - Directory containing all the website content as Markdown files +- `docs/stylesheets/` - Custom CSS for styling +- `docs/javascripts/` - Custom JavaScript functionality + +### Essential Markdown Syntax + +#### 1. Headers + +Create headers of different levels using `#` symbols: + +```markdown +# Main Heading (H1) +## Section Heading (H2) +### Subsection Heading (H3) +``` + +#### 2. Links and Anchors + +Create links to other pages or sections: + +```markdown +[Link text](destination.md) +[Link to section](#section-id) +[External link](https://example.com){target="_blank"} +``` + +Create anchor points for deep linking: +```markdown + +``` + +#### 3. Tables + +Create tables using the pipe syntax: + +```markdown +| Header 1 | Header 2 | Header 3 | +| -------- | -------- | -------- | +| Cell 1 | Cell 2 | Cell 3 | +| Cell 4 | Cell 5 | Cell 6 | +``` + +For multi-line cell content, use HTML line breaks (`
`). + +#### 4. Images + +Add images with optional width and alignment: + +```markdown +![Alt text](path/to/image.png) +![Alt text](path/to/image.png){ width="300" } +![Alt text](path/to/image.png){ align=right } +``` + +#### 5. Mathematics + +Use MathJax for mathematical equations: + +```markdown +Inline equation: $E = mc^2$ + +Block equation: +$$ +\frac{d}{dx}f(x) = \lim_{h \to 0}\frac{f(x+h) - f(x)}{h} +$$ +``` + +#### 6. Advanced Features + +Create notes, warnings, and expandable sections: + +```markdown +!!! note "Optional Title" + This is a note. + +!!! warning + This is a warning. + +??? question "Expandable section" + This content is hidden until clicked. +``` + +Create tabs for alternative content: + +```markdown +=== "Tab 1" + Content for tab 1 + +=== "Tab 2" + Content for tab 2 +``` + +### Common Tasks + +#### Adding a New Page + +1. Create a new `.md` file in the appropriate directory +2. Add it to the navigation section in `mkdocs.yml` + +#### Adding Interactive Buttons + +Use this HTML to add a hyperlink button: + +```html + +``` + +#### Adding Abbreviations + +Edit the `includes/abbreviations.md` file to add new abbreviations that will be automatically recognized throughout the site. + +## Getting Help + +If you need assistance: + +1. Check the [MkDocs Material Reference](https://squidfunk.github.io/mkdocs-material/reference/) +2. Submit a question in the [GitHub Issues](https://github.com/OSIPI/OSIPI_CAPLEX/issues) +3. For lexicon resources, contact [Ben Dickie](mailto:ben.dickie@manchester.ac.uk) diff --git a/docs/practical-examples.md b/docs/practical-examples.md new file mode 100644 index 0000000..b30c2d9 --- /dev/null +++ b/docs/practical-examples.md @@ -0,0 +1,188 @@ +# Practical Contribution Examples + +This guide provides step-by-step examples of common contribution scenarios to help you get started with OSIPI CAPLEX. + +## Example 1: Adding a New Lexicon Entry + +Let's walk through the process of adding a new quantity to the lexicon. + +### Step 1: Locate the Appropriate File + +Quantities are stored in `docs/quantities.md`. Open this file in your editor. + +### Step 2: Find the Correct Section + +Quantities are organized alphabetically by category. For example, if you're adding a new "Signal" quantity, find the "Signal" section in the file. + +### Step 3: Add Your Entry + +Copy an existing table row and modify it with your new information: + +```markdown +| Q.MS1.002.[j] | Normalized Signal | -- | *Snorm,j* | The MR signal in compartment *j* normalized to a reference value. | a.u. | -- | +``` + +### Step 4: Preview Your Changes + +With `mkdocs serve` running, check your browser to see how your new entry looks. + +### Step 5: Commit Your Change + +Follow the Git workflow to commit and push your change: + +``` +git add docs/quantities.md +git commit -m "Add normalized signal quantity to lexicon" +git push +``` + +## Example 2: Adding a New Reference + +References can enhance the value of lexicon entries. Here's how to add one: + +### Step 1: Find the Entry Needing a Reference + +Locate the lexicon entry that needs a reference. + +### Step 2: Add the Reference + +Update the reference column with a properly formatted link: + +```markdown +| Q.MS1.001.[j] | Signal | -- | *Sj* | The MR signal (magnitude, phase or complex depending on context) in compartment *j*. | a.u. | [Bernstein et al. (2004)](https://doi.org/10.1016/B978-0-12-092861-3.X5000-6) | +``` + +For DOI references, use the format: +``` +[Author et al. (Year)](https://doi.org/10.xxxx/xxxxx) +``` + +For PubMed references, use: +``` +[Author et al. (Year)](https://www.ncbi.nlm.nih.gov/pmc/articles/PMCxxxxxxx/) +``` + +## Example 3: Creating a New Section Page + +If you need to add a completely new section to the website: + +### Step 1: Create the Markdown File + +Create a new `.md` file in the `docs` directory: + +``` +touch docs/new-section.md +``` + +### Step 2: Add Basic Content Structure + +Start with a header and introduction: + +```markdown +# New Section Title + +This section covers [brief description of what this section is about]. + +## Overview + +[Provide a general overview of the topic] + +## Key Concepts + +[List and describe the most important concepts in this area] +``` + +### Step 3: Update Navigation + +Add your new page to the `mkdocs.yml` file in the `nav:` section: + +```yaml +nav: + - Home: index.md + - Quantities: quantities.md + - Your New Section: new-section.md +``` + +## Example 4: Adding Interactive Elements + +MkDocs Material offers various interactive elements to enhance your content: + +### Adding Expandable Content + +Use this pattern to create content that expands when clicked: + +```markdown +??? example "Click to expand" + This content is hidden by default. + + It can contain multiple paragraphs, code blocks, and even images. + + ```python + def example(): + return "This is a code example" + ``` +``` + +### Adding Tabbed Content + +Create tabbed sections like this: + +```markdown +=== "Basic Usage" + Here's the basic way to use this feature. + +=== "Advanced Options" + For more control, try these advanced settings. + +=== "Examples" + See these examples of the feature in action. +``` + +## Example 5: Styling and Formatting + +Here are some examples of styling options: + +### Text Formatting + +```markdown +**Bold text** for emphasis +*Italic text* for slight emphasis +`code` for inline code references +``` + +### Block Elements + +```markdown +> This is a blockquote. +> It can span multiple lines. + +```python +# This is a code block with syntax highlighting +def function(): + return "Hello World" +``` + +!!! tip + This is a tip callout box. +``` + +### Mathematical Equations + +For inline equations: +```markdown +The relationship is defined by $E = mc^2$ where $m$ is mass. +``` + +For display equations: +```markdown +$$ +R_1 = \frac{1}{T_1} +$$ +``` + +## Getting Help + +If you run into issues with any of these examples, please: + +1. Refer to the [MkDocs Material documentation](https://squidfunk.github.io/mkdocs-material/reference/) +2. Ask for help in the [GitHub Issues section](https://github.com/OSIPI/OSIPI_CAPLEX/issues) diff --git a/docs/quick-reference.md b/docs/quick-reference.md new file mode 100644 index 0000000..db6fecd --- /dev/null +++ b/docs/quick-reference.md @@ -0,0 +1,170 @@ +# OSIPI CAPLEX Quick Reference + +This quick reference provides common syntax and patterns used in OSIPI CAPLEX Markdown files. + +## Basic Markdown + +| Element | Syntax | +| ------- | ------ | +| Heading 1 | `# Heading` | +| Heading 2 | `## Heading` | +| Heading 3 | `### Heading` | +| Bold | `**bold text**` | +| Italic | `*italic text*` | +| Link | `[link text](URL)` | +| Image | `![alt text](image.jpg)` | +| Blockquote | `> quoted text` | +| Ordered List | `1. First item`
`2. Second item` | +| Unordered List | `- Item`
`- Another item` | +| Code | `` `code` `` | +| Code Block | ```````
```language
code
```
``````` | +| Horizontal Rule | `---` | + +## CAPLEX-Specific Elements + +### Anchors and Links + +Create an anchor: +``` + +``` + +Link to an anchor: +``` +[link text](#uniqueID) +``` + +Link to an anchor on another page: +``` +[link text](page.md#uniqueID){target="_blank"} +``` + +### Tables + +Basic table structure: +``` +| Header 1 | Header 2 | Header 3 | +| -------- | -------- | -------- | +| Cell 1 | Cell 2 | Cell 3 | +``` + +Multi-line cell content: +``` +| Header 1 | Header 2 | +| -------- | -------- | +| Cell 1 | Line 1
Line 2 | +``` + +### Hyperlink Button + +``` + +``` + +### Math Equations + +Inline math: +``` +$equation$ +``` + +Display math: +``` +$$ +equation +$$ +``` + +### Material MkDocs Extensions + +Note box: +``` +!!! note "Optional Title" + Note content +``` + +Warning box: +``` +!!! warning + Warning content +``` + +Expandable section: +``` +??? question "Title" + Hidden content +``` + +Tabbed content: +``` +=== "Tab 1" + Tab 1 content + +=== "Tab 2" + Tab 2 content +``` + +Annotations: +``` +Text to annotate (1) +{ .annotate } + +1. Annotation content +``` + +### Common Lexicon Patterns + +Quantity entry: +``` +| Q.XX1.001 | Name | Alt Names | *Symbol* | Description | Units | Reference | +``` + +Model entry: +``` +| M.XX1.001 | Name | Alt Names | Symbol | Description | Reference | +``` + +### Images with Options + +``` +![alt text](image.jpg){ width="300" } +![alt text](image.jpg){ align=right } +![alt text](image.jpg){ loading=lazy } +``` + +## Common Quantities Notation + +| Quantity | Notation | +| -------- | -------- | +| Signal | *S* | +| T1 | *T1* | +| T2 | *T2* | +| T2* | *T2** | +| R1 | *R1* | +| R2 | *R2* | +| R2* | *R2** | + +## HTML Elements for Layout + +Two-column layout: +```html +
+
+ +First column content (written in Markdown) + +
+
+ +Second column content (written in Markdown) + +
+
+``` + +Centered image: +```html +
+![alt text](image.jpg) +
+``` diff --git a/docs/simulationTools.md b/docs/simulationTools.md new file mode 100644 index 0000000..af84512 --- /dev/null +++ b/docs/simulationTools.md @@ -0,0 +1,56 @@ +# Data Simulation Tools for Perfusion MRI + +This page provides an overview of software tools for simulating contrast-agent based perfusion MRI data, which can be valuable for testing and validating perfusion quantification methods. + +## Overview + +Simulation tools allow researchers to generate synthetic perfusion MRI data with known ground truth parameters. These tools are essential for: + +- Validating quantification algorithms +- Testing the effects of noise, temporal resolution, and other acquisition parameters +- Developing and benchmarking new analysis methods +- Training and education + +## Available Simulation Tools + +### JSim + +**Developer**: University of Washington, Physiome Project +**Website**: [JSim Website](http://www.physiome.org/jsim/) +**Description**: JSim is a Java-based simulation system for building quantitative numerical models and analyzing them with respect to experimental reference data. It can be used to simulate tracer-kinetic models for DCE-MRI and DSC-MRI. + +### OSIPI DCE/DSC Simulator + +**Developer**: OSIPI Task Force 1.2 +**Repository**: [GitHub Repository](https://github.com/OSIPI/TF1.2_notebook) +**Description**: A collection of Jupyter notebooks developed by OSIPI for simulating DCE-MRI and DSC-MRI data with various perfusion models. These notebooks allow users to generate synthetic perfusion time-series with user-defined parameter values. + +### POSSUM (Physics-Oriented Simulated Scanner for Understanding MRI) + +**Developer**: FMRIB Centre, University of Oxford +**Website**: [POSSUM Website](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/POSSUM) +**Description**: Although primarily designed for fMRI, POSSUM can be adapted for simulating perfusion MRI with the addition of tracer-kinetic models. + +### JEMRIS (Jülich Extensible MRI Simulator) + +**Developer**: Forschungszentrum Jülich +**Website**: [JEMRIS Website](http://www.jemris.org/) +**Description**: JEMRIS is an open-source MRI simulator that includes capabilities for simulating various pulse sequences and can be extended to include contrast agent dynamics. + +## How to Use Simulation Tools in Perfusion Research + +1. **Define physiological parameters**: Set tissue-specific parameters (e.g., blood flow, vessel permeability, blood volume) based on literature or experimental values. +2. **Set up acquisition parameters**: Configure temporal resolution, noise level, and other MRI acquisition parameters. +3. **Run simulation**: Generate synthetic perfusion time-series data. +4. **Apply analysis methods**: Test different quantification methods on the simulated data. +5. **Compare results with ground truth**: Evaluate the accuracy of quantification methods. + +## Contributing New Simulation Tools + +If you have developed a simulation tool for contrast-agent based perfusion MRI that you would like to add to this list, please see our [contribution guidelines](contributionTutorial.md). + +## References + +1. Jelescu IO, et al. Challenges for biophysical modeling of microstructure. J Neurosci Methods. 2020;344:108861. +2. Sourbron SP, Buckley DL. Classic models for dynamic contrast-enhanced MRI. NMR Biomed. 2013;26(8):1004-27. +3. Koh TS, et al. Fundamentals of tracer kinetics for dynamic contrast-enhanced MRI. J Magn Reson Imaging. 2011;34(6):1262-76. \ No newline at end of file diff --git a/docs/style-guide.md b/docs/style-guide.md new file mode 100644 index 0000000..057e881 --- /dev/null +++ b/docs/style-guide.md @@ -0,0 +1,163 @@ +# OSIPI CAPLEX Style Guide + +This style guide provides guidelines to ensure consistency across all contributions to the OSIPI CAPLEX website. + +## General Principles + +- **Clarity**: Write content that is clear and accessible to both experts and newcomers +- **Precision**: Use technically accurate language and proper terminology +- **Consistency**: Follow established patterns for formatting and organization +- **Brevity**: Be concise while conveying necessary information + +## Document Structure + +### Page Headers + +- Use title case for main headers (e.g., "Signal Modeling Approaches") +- Use sentence case for subheaders (e.g., "Common signal models") +- Structure documents with a clear hierarchy (H1 → H2 → H3) + +### Sections + +Organize content in a logical flow: +1. Introduction/Overview +2. Key Concepts +3. Detailed Information +4. Examples (where applicable) +5. References + +## Lexicon Entries + +### Quantities + +Follow this format for quantity entries: + +``` +| Q.[Category].[Number].[j] | Full Name | Alternative Names | Notation | Description | Units | Reference | +``` + +Where: +- `[Category]` is the two-letter category code +- `[Number]` is a sequential three-digit number +- `[j]` indicates if the quantity applies to a specific compartment +- `UniqueID` is a short, memorable identifier + +### Models + +Follow this format for model entries: + +``` +| M.[Category].[Number] | Full Name | Alternative Names | Notation | Description | Reference | +``` + +### Descriptions + +- Begin with a capital letter and end with a period +- Be concise but complete (ideally 1-2 sentences) +- Include key parameters and their meanings +- Use proper mathematical notation +- Link to related quantities when first mentioned + +## Mathematical Notation + +### Symbols + +- Use consistent symbols across the lexicon +- Italicize variables (e.g., *S*, *T*, *R*) +- Use subscripts for specificity (e.g., *S0*) +- Use proper Greek letters where conventional (e.g., τ, θ) + +### Equations + +- Center standalone equations +- Number significant equations for reference +- Use consistent notation between text and equations +- Include units where appropriate + +Example: +``` +$$ +S = S_0 \cdot e^{-TE/T_2^*} +$$ +``` + +## References + +### Format + +Use consistent reference formatting: + +- DOI references: `[Author et al. (Year)](https://doi.org/10.xxxx/xxxxx)` +- PubMed references: `[Author et al. (Year)](https://www.ncbi.nlm.nih.gov/pmc/articles/PMCxxxxxxx/)` +- Books: `[Author (Year). Title. Publisher.](URL if available)` + +### Citation Style + +- For one author: `Smith (2020)` +- For two authors: `Smith and Jones (2020)` +- For three or more authors: `Smith et al. (2020)` + +## Language Guidelines + +### Terminology + +- Use established terminology from the field +- Provide alternative names where multiple terms exist +- Define abbreviations on first use +- Add common abbreviations to the abbreviations.md file + +### Writing Style + +- Use active voice where possible +- Avoid unnecessary jargon +- Define technical terms for newcomers +- Be consistent with spelling (use American English) +- Write in third person (avoid "you" and "we") + +## Images and Figures + +- Provide descriptive alt text for all images +- Use vector formats (SVG) when possible +- Include captions explaining key elements +- Maintain consistent styling across related figures +- Optimize image sizes for web viewing + +## Examples and Code + +- Include practical examples where helpful +- Use syntax highlighting for code blocks +- Comment code examples thoroughly +- Ensure code examples are functional + +## Website-Specific Elements + +### Interactive Elements + +- Use expandable sections for supplementary information +- Use tabs for alternative approaches or implementations +- Include tooltips for technical terms + +### Navigation + +- Ensure logical placement in site hierarchy +- Use descriptive link text +- Avoid deep nesting of pages +- Consider the user's journey through the site + +## Review Process + +Before submitting contributions: + +1. Check for technical accuracy +2. Verify that formatting is consistent with this style guide +3. Ensure all links work correctly +4. Preview the content in a local build +5. Review for grammar and spelling + +## Accessibility + +- Use sufficient color contrast +- Provide text alternatives for non-text content +- Create descriptive link text +- Use proper heading hierarchy +- Avoid relying solely on color to convey information diff --git a/mkdocs.yml b/mkdocs.yml index b433993..9aef3c6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,7 +29,7 @@ theme: features: - search.suggest icon: - admonition: + admonition: note: fontawesome/solid/note-sticky question: fontawesome/solid/circle-question warning: fontawesome/solid/triangle-exclamation @@ -39,7 +39,7 @@ theme: docs_dir: docs nav: - - Overview: + - Overview: - About Caplex: index.md - CAPLEX structure: structure.md - How to use the website: qualityOfLife.md @@ -50,14 +50,20 @@ nav: - P - Perfusion processes: perfusionProcesses.md - G - General purpose processes: generalPurposeProcesses.md - D - Derived processes: derivedProcesses.md - - - DCE/DSC resources: - - DCE literature library: dceliterature.md + - Implementation Resources: + - DCE/DSC resources: + - DCE literature library: dceliterature.md + - Software tools: + - Software overview: softwareOverview.md + - Data simulation tools: simulationTools.md + - Analysis toolboxes: analysisToolboxes.md + - Sample datasets: sampleDatasets.md + plugins: - search: lang: en separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;' - + markdown_extensions: - toc: permalink: True @@ -89,11 +95,9 @@ markdown_extensions: - md_in_html - abbr - - extra: og: - type: website + type: website title: Contrast-agent based perfusion MRI lexicon (CAPLEX) description: CAPLEX image: Social Card.png @@ -124,13 +128,13 @@ extra: - icon: material/emoticon-sad-outline name: This page could be improved data: 0 - note: >- + note: >- Thanks for your feedback! Help us improve this page by using our feedback form. consent: title: Cookie consent - description: >- + description: >- We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our lexicon and whether users find what they're searching for. With your consent, you're helping us to - make our lexicon better. \ No newline at end of file + make our lexicon better.