Skip to content

Commit

Permalink
Merge pull request #4 from BRAIN-TO/joss_review_response
Browse files Browse the repository at this point in the history
Joss review response
  • Loading branch information
alexjaffray authored Jan 30, 2024
2 parents 9f5b4b9 + 7075253 commit 53c54d3
Show file tree
Hide file tree
Showing 62 changed files with 30,045 additions and 3,475 deletions.
40 changes: 40 additions & 0 deletions .github/workflows/CI.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
name: CI
on:
push:
branches:
- main
- joss_review_response
tags: ['*']
pull_request:
concurrency:
# Skip intermediate builds: always.
# Cancel intermediate builds: only if it is a pull request build.
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
jobs:
test:
name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
version:
- '1.9'
- '1.10'
os:
- ubuntu-latest
arch:
- x64
steps:
- uses: actions/checkout@v2
- uses: julia-actions/setup-julia@v1
with:
version: ${{ matrix.version }}
arch: ${{ matrix.arch }}
- uses: julia-actions/cache@v1
- uses: julia-actions/julia-buildpkg@v1
- uses: julia-actions/julia-runtest@v1
- uses: julia-actions/julia-processcoverage@v1
- uses: codecov/codecov-action@v2
with:
files: lcov.info
45 changes: 45 additions & 0 deletions .github/workflows/CompatHelper.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
name: CompatHelper
on:
schedule:
- cron: 0 0 * * *
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
CompatHelper:
runs-on: ubuntu-latest
steps:
- name: Check if Julia is already available in the PATH
id: julia_in_path
run: which julia
continue-on-error: true
- name: Install Julia, but only if it is not already available in the PATH
uses: julia-actions/setup-julia@v1
with:
version: '1'
arch: ${{ runner.arch }}
if: steps.julia_in_path.outcome != 'success'
- name: "Add the General registry via Git"
run: |
import Pkg
ENV["JULIA_PKG_SERVER"] = ""
Pkg.Registry.add("General")
shell: julia --color=yes {0}
- name: "Install CompatHelper"
run: |
import Pkg
name = "CompatHelper"
uuid = "aa819f21-2bde-4658-8897-bab36330d9b7"
version = "3"
Pkg.add(; name, uuid, version)
shell: julia --color=yes {0}
- name: "Run CompatHelper"
run: |
import CompatHelper
CompatHelper.main()
shell: julia --color=yes {0}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
# COMPATHELPER_PRIV: ${{ secrets.COMPATHELPER_PRIV }}
2 changes: 1 addition & 1 deletion .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ jobs:
with:
version: '1.9'
- name: Install dependencies
run: julia --project=docs -e 'using Pkg; Pkg.add("MRIGradients"); Pkg.develop(PackageSpec(path=pwd())); Pkg.add("Documenter"); Pkg.add("Literate"); Pkg.instantiate()'
run: julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
- name: Build Documents through Documenter.jl
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ LocalPreferences.toml
GIRFReco.code-workspace
docs/build/
docs/src/generated/
.vscode/
49 changes: 49 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Contributing to GIRFReco.jl
We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Proposing new features

## We Develop with Github
We use github to host code, to track issues and feature requests, as well as accept pull requests.

We actively welcome your pull requests:

1. Fork or clone the repo and create your branch from `main`.
2. If you've added code that should be tested, add tests.
3. Add docstrings to facilitate our generated documentation.
4. Ensure your (and our) tests pass
5. Post the PR or file an issue and we will work with you

## Any contributions you make will be under the BSD 3-Clause Software License
In short, when you submit code changes, your submissions are understood to be under the same [BSD 3-Clause License
](https://choosealicense.com/licenses/bsd-3-clause/) that covers the project. Feel free to contact the maintainers if that's a concern.

## Report bugs using Github's [issues](https://github.com/BRAIN-TO/GIRFReco.jl/issues)
We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/BRAIN-TO/GIRFReco.jl/issues/new/choose); it's that easy!

## Write bug reports with detail, background, and sample code

**Great Bug Reports** tend to have:

- A quick summary and/or background
- Steps to reproduce
- Be specific!
- Give sample code if you can, a minimum working example (MWE) is best but we understand MRI involves complicated and large data
- What you expected would happen
- What actually happens
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)

People *love* thorough bug reports. I'm not even kidding.

## Use a Consistent Coding Style
* We (mostly) use Julia [Blue](https://github.com/invenia/BlueStyle)
* It would be great if you did as well

## License
By contributing, you agree that your contributions will be licensed under its BSD 3-Clause License.

## References
This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)
41 changes: 1 addition & 40 deletions Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -8,46 +8,27 @@ AxisArrays = "39de3d68-74b9-583c-8d2d-e117c070f3a9"
DSP = "717857b8-e6f2-59f4-9121-6e50c889abd2"
DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
Dierckx = "39dd38d3-220a-591b-8e3c-4c3a8c710a94"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
FourierTools = "b18b359b-aebc-45ac-a139-9c0ccbb2871e"
HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
ImageBinarization = "cbc4b850-ae4b-5111-9e64-df94c024a13d"
ImageEdgeDetection = "2b14c160-480b-11ea-1b58-656063328ff7"
ImageMorphology = "787d08f9-d448-5407-9aad-5290dd7ab264"
ImageUtils = "8ad4436d-4835-5a14-8bce-3ae014d2950b"
Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
LinearOperators = "5c8ed15e-5a4c-59e4-a42b-c7e8811fb125"
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
MAT = "23992714-dd62-5051-b70f-ba57cb901cac"
MRIBase = "f7771a9a-6e57-4e71-863b-6e4b6a2f17df"
MRICoilSensitivities = "c57eb701-aafc-44a2-a53c-128049758959"
MRIFieldmaps = "5af58b90-8a55-4daf-adb4-2008a66a38cf"
MRIFiles = "5a6f062f-bf45-497d-b654-ad17aae2a530"
MRIGradients = "6ea382ba-d04a-44a2-b811-544bd2aee867"
MRIOperators = "fb1137e3-90a6-46ce-a672-6e1e53d120f2"
MRIReco = "bdf86e05-2d2b-5731-a332-f3fe1f9e047f"
Measures = "442fdcdd-2543-5da2-b0f3-8c86c306513e"
MosaicViews = "e94cdb99-869f-56ef-bcf0-1ae2bcbe0389"
NFFT = "efe261a4-0d2b-5849-be55-fc731d526b0d"
NFFTTools = "7424e34d-94f7-41d6-98a0-85abaf1b6c91"
NIfTI = "a3a9e032-41b5-5fc4-967a-a6b7a19844d3"
PlotlyJS = "f0f68f2c-4968-5e81-91da-67840de0976a"
Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
PolygonInbounds = "e4521ec6-8c1d-418e-9da2-b3bc4ae105d6"
Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
ROMEO = "1ea8258b-a15d-4adb-ad20-01632f467a84"
RegularizedLeastSquares = "1e9c538a-f78c-5de5-8ffb-0b6dbe892d23"
Scratch = "6c6a2e73-6563-6170-7368-637461726353"
SparsityOperators = "a5ff1dd3-4e0a-50db-9022-6d011c1d5846"
Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
Waveforms = "cb13b1c6-351e-5134-b3ad-d6a530956a82"


[extras]
CPUSummary = "2a0fbf3d-bb9c-48f3-b0a9-814d99fd7ab9"
Expand All @@ -59,41 +40,21 @@ AxisArrays = "0.4.6"
DSP = "0.7.8"
DelimitedFiles = "1.9.1"
Dierckx = "0.5.3"
Documenter = "0.27.24"
FFTW = "1.7.1"
FileIO = "1.16.1"
Flux = "0.13.17"
FourierTools = "0.4.2"
HDF5 = "0.16.15"
HTTP = "1.9.8"
ImageBinarization = "0.2.9"
ImageEdgeDetection = "0.1.7"
ImageMorphology = "0.3.2"
ImageUtils = "0.2.9"
Images = "0.25.3"
LinearOperators = "2.5.2"
Literate = "2.14.0"
MAT = "0.10.5"
MRIBase = "0.3.3"
MRICoilSensitivities = "0.1.1"
MRIFieldmaps = "0.0.3"
MRIFiles = "0.1.6"
MRIGradients = "0.1.2"
MRIOperators = "0.1.2"
MRIReco = "0.7.1"
Measures = "0.3.2"
MosaicViews = "0.3.4"
NFFT = "0.13.3"
NFFTTools = "0.2.6"
NIfTI = "0.5.9"
PlotlyJS = "0.18.10"
Plots = "1.38.16"
PolygonInbounds = "0.2.0"
ROMEO = "1.0.1"
RegularizedLeastSquares = "0.9.1"
Scratch = "1.2.0"
SparsityOperators = "0.4.7"
StatsBase = "0.33.21"
Unitful = "1.14.0"
Waveforms = "0.1.1"
Statistics = "1.9.0"
36 changes: 21 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,49 +1,55 @@
[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://brain-to.github.io/GIRFReco)

[![codecov](https://codecov.io/gh/BRAIN-TO/GIRFReco.jl/graph/badge.svg?token=7E3WK1GKR3)](https://codecov.io/gh/BRAIN-TO/GIRFReco.jl)
# GIRFReco.jl: An open-source pipeline for spiral MRI Reconstruction in Julia

## Introduction

This package provides an image reconstruction pipeline for real-world non-Cartesian MRI, especially on spiral diffusion imaging. It is completely implemented in Julia using original code and external packages, e.g., [MRIReco.jl](https://magneticresonanceimaging.github.io/MRIReco.jl/latest/) for the off-resonance (B<sub>0</sub>) corrections & core iterative reconstruction tasks, and [MRIGradients.jl](https://github.com/BRAIN-TO/MRIGradients.jl) for the corrections of gradient waveform due to system imperfections via the Gradient Impulse Response Function (GIRF).
This package provides an image reconstruction pipeline for real-world non-Cartesian MRI, especially on spiral diffusion imaging. It is completely implemented in Julia using original code and external packages, e.g., [MRIReco.jl](https://magneticresonanceimaging.github.io/MRIReco.jl/latest/) for the off-resonance (B<sub>0</sub>) corrections & core iterative reconstruction tasks, and [MRIGradients.jl](https://github.com/BRAIN-TO/MRIGradients.jl) for the correction of gradient waveforms due to system imperfections via the Gradient Impulse Response Function (GIRF).

This repository includes working [examples](./docs/lit/examples/) for spiral reconstruction with GIRF correction of trajectory (kx-ky-kz, or k<sub>1</sub> as the first order GIRF) and B0 eddy currents (k<sub>0</sub> as zeroth order GIRF), iterative reconstruction (cg-SENSE) and a Cartesian reconstruction example for coil sensitivity and off-resonance map calculation.
This repository includes working [examples](./docs/lit/examples/) for spiral reconstruction with GIRF correction of trajectory (kx-ky-kz, or k<sub>1</sub> as the first order GIRF) and B<sub>0</sub> eddy currents (k<sub>0</sub> as zeroth order GIRF), iterative reconstruction (cg-SENSE) and a Cartesian reconstruction example for coil sensitivity and off-resonance map calculation.

The data for the phantom reconstruction [`joss_demo.jl`](./docs/lit/examples/joss_demo.jl) is publicly available [here](https://www.doi.org/10.5281/zenodo.7779045). The path of the data, `paramsGeneral[:pathProject]`, needs to be modified accordingly in the [config file](./docs/lit/examples/ReconConfig_joss_demo.jl).
The data for the phantom reconstruction [`joss_demo.jl`](./docs/lit/examples/joss_demo.jl) is publicly available [here](https://www.doi.org/10.5281/zenodo.7779045). The path of the data, `params_general[:project_path]`, needs to be modified accordingly in the [config file](./docs/lit/examples/recon_config_joss_demo.jl).

For a full introduction, please refer to our [manuscript](./paper.md) for a full description of this package, including background, purpose, implementation, and the information of dependent packages.
For a full introduction, please refer to our [manuscript](./paper/paper.md) for a full description of this package, including background, purpose, implementation, and the information of dependent packages.

## Quick Installation
To install the package, use the following command:
To install the package, **type** the following command:
```
julia>]add GIRFReco
```

It is also possible to install the package with the following code:
```
using Pkg
Pkg.add("GIRFReco")
```

## Development Installation

1. To get started, make sure you have Julia installed (>=1.9).
2. Clone the GIRFReco.jl project from Github to a local directory by `git clone git@github:BRAIN-TO/GIRFReco.jl` or to copy it to the dev directory using the Quick Installation and the following command:
```
julia> ]dev GIRFReco
```
3. Download the demonstrating data from Zenodo (https://doi.org/10.5281/zenodo.6510020) and extract to your local folder. **Make sure you have both reading and writing privileges on the data folder.**
* Note: The data downloading might take a few minutes. You can continue with step 5-10 in the meantime.
4. Open a Julia REPL under the path of your local `GIRFReco.jl` folder. We recommend using Visual Studio Code with the Julia extension as development environment.
5. In the Julia REPL, type `]` to enter the package manager.
6. In Julia package manager, Type `activate .` to activate a the Julia environment defined in `Project.toml` file in the `GIRFReco.jl` repo.
7. Add the `MRIGradients.jl` package by `add MRIGradients`.
8. Install all additional dependent packages:
3. Open a Julia REPL under the path of your local `GIRFReco.jl` folder. Our own development configuration is Visual Studio Code with the Julia extension. Other environments for Julia should work in a similar way with possible extra configurations.
4. In the Julia REPL, type `]` to enter the package manager.
5. In Julia package manager, Type `activate .` to activate a the Julia environment defined in `Project.toml` file in the `GIRFReco.jl` repo.
6. Add the `MRIGradients.jl` package by `add MRIGradients`.
7. Install all additional dependent packages:
* `add MRIReco`
* `add MRIFiles`
* `add MRIBase`
* `add ImageUtils`
* `add MRICoilSensitivities`
* `add FileIO`
9. Use command `instantiate` in Julia package manager to install all of the dependencies. This may be all you need to do (i.e you might be able to skip steps 7,8).
8. Use command `instantiate` in Julia package manager to install all of the dependencies. This may be all you need to do (i.e you might be able to skip steps 7,8).
9. Download the demonstrating data from Zenodo (https://doi.org/10.5281/zenodo.6510020) and extract to your local folder. **Make sure you have both reading and writing privileges on the data folder.**
* Note: The data downloading might take a few minutes.
10. Open the demo script `joss_demo.jl` under the folder `docs/lit/examples/`, make sure to set `rootProjPath` as the folder that stores demo data, then run it in Julia REPL.

## Example Results

1. **Phantom Images.** (*Presented at [ISMRM 2022, p.2435](https://archive.ismrm.org/2022/2435.html)*): using a dataset with 4 spiral interleaves for images with 1.1mm in-plane resolution. The code and dataset are both described in the [previous section](#quick-start).
1. **Phantom Images.** (*Presented at [ISMRM 2022, p.2435](https://archive.ismrm.org/2022/2435.html)*): using a dataset with 4 spiral interleaves for images with 1.1mm in-plane resolution. The code and dataset are both described in the [previous section](#quick-installation).

```bash
cd docs/lit/examples
Expand Down
22 changes: 22 additions & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
GIRFReco = "cf1bd817-9e2d-403d-b1e7-15ef5a867bae"
HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
ImageTransformations = "02fcd773-0e25-5acc-982a-7f6622650795"
ImageUtils = "8ad4436d-4835-5a14-8bce-3ae014d2950b"
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
MRIBase = "f7771a9a-6e57-4e71-863b-6e4b6a2f17df"
MRICoilSensitivities = "c57eb701-aafc-44a2-a53c-128049758959"
MRIFiles = "5a6f062f-bf45-497d-b654-ad17aae2a530"
MRIGradients = "6ea382ba-d04a-44a2-b811-544bd2aee867"
MRIReco = "bdf86e05-2d2b-5731-a332-f3fe1f9e047f"
MRISimulation = "8988da37-ea20-4fa6-9af7-8a6f6f9a8970"
PlotlyJS = "f0f68f2c-4968-5e81-91da-67840de0976a"
Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
RegularizedLeastSquares = "1e9c538a-f78c-5de5-8ffb-0b6dbe892d23"

[compat]
MRIReco = "0.7.1"
Loading

0 comments on commit 53c54d3

Please sign in to comment.