Anisotropic Phantoms

[curtcorum]

Phantom functions accept length 2 (or length 3 for brain_phantom3D) vectors for the subsampling and upsampling parameters. Scalers still accepted and should be backwards compatible. Some validity checking.

"""
    obj = brain_phantom2D(; axis="axial", ss=4, us=1)

Creates a two-dimensional brain Phantom struct.
Default ss=4 sample spacing is 2 mm. Original file (ss=1) sample spacing is .5 mm.

# References
- B. Aubert-Broche, D.L. Collins, A.C. Evans: "A new improved version of the realistic
    digital brain phantom" NeuroImage, in review - 2006
- B. Aubert-Broche, M. Griffin, G.B. Pike, A.C. Evans and D.L. Collins: "20 new digital
    brain phantoms for creation of validation image data bases" IEEE TMI, in review - 2006
- https://brainweb.bic.mni.mcgill.ca/brainweb

# Keywords
- `axis`: (`::String`, `="axial"`, opts=[`"axial"`, `"coronal"`, `"sagittal"`]) orientation of the phantom
- `ss`: (`::Integer or ::Vector{Integer}`, `=4`) subsampling parameter for all axes if scaler, per axis if 2 element vector [ssx, ssy]
- `us`: (`::Integer or ::Vector{Integer}`, `=1`)  upsampling parameter for all axes if scaler, per axis if 2 element vector [usx, usy], if used ss is set to ss=1


# Returns
- `obj`: (`::Phantom`) Phantom struct

# Examples
```julia-repl
julia> obj = brain_phantom2D(; axis="sagittal", ss=1)

julia> obj = brain_phantom2D(; axis="axial", us=[1, 2])

julia> plot_phantom_map(obj, :ρ)

"""

[curtcorum]

See #311 (reply in thread) for an example.

[codecov]

Codecov Report

Attention: Patch coverage is 86.25000% with 11 lines in your changes are missing coverage. Please review.

Project coverage is 92.04%. Comparing base (3d7e92d) to head (ce12a24).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #342      +/-   ##
==========================================
- Coverage   92.41%   92.04%   -0.38%     
==========================================
  Files          33       33              
  Lines        2215     2250      +35     
==========================================
+ Hits         2047     2071      +24     
- Misses        168      179      +11     

Flag	Coverage Δ
base	90.24% <86.25%> (-1.02%)	⬇️
core	90.30% <ø> (ø)
files	93.79% <ø> (ø)
komamri	93.95% <ø> (ø)
plots	93.50% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
KomaMRIBase/src/datatypes/Phantom.jl	88.18% <86.25%> (-7.47%)	⬇️

[cncastillo]

Thanks @curtcorum!

Sorry for all the commits, I couldn´t find a way to do them simultaneously on GitHub.

There is a part where tabs are used instead of spaces, and I also included a suggestion to wrap some checks in a function.

[curtcorum]

help?> KomaMRIBase.check_phantom_arguments
  ssx, ssy, ssz, usx, usy, usz = check_phantom_arguments(nd, ss, us)

  Utility function to check the arguments of phantom generating functions.

  Arguments
  ≡≡≡≡≡≡≡≡≡≡≡

    •  nd : (::Integer) dimensionality of the phantom

    •  ss : (::Integer or ::Vector{Integer}) subsampling parameter for all axes if scaler, per axis if a 2 or 3 element vector

    •  us : (::Integer or ::Vector{Integer}) upsampling parameter for all axes if scaler, per axis if a 2 or 3 element vector

  Returns
  ≡≡≡≡≡≡≡≡≡

    •  ssx, ssy, ssz: (::Vector{Integer}) valid subsampling parameter per axis

    •  usx, usy, usz: (::Vector{Integer}) valid upsampling parameter per axis

  Examples
  ≡≡≡≡≡≡≡≡≡≡

  julia> ssx, ssy, ssz, usx, usy, usz = check_phantom_arguments(2, 1, 1)
  
  julia> ssx, ssy, ssz, usx, usy, usz = check_phantom_arguments(3, 4, [2, 2, 2])

julia> KomaMRIBase.check_phantom_arguments(2, 1, [1, 1])
[ Info: setting ss=1 since us=[1, 1] defined
(1, 1, -9999, 1, 1, -9999)

julia> KomaMRIBase.check_phantom_arguments(2, 1, [1, 1, 1])
[ Info: setting ss=1 since us=[1, 1, 1] defined
ERROR: AssertionError: us=[1, 1, 1] invalid, us can have up to two components [usx, usy] for a 2D phantom
Stacktrace:
 [1] check_phantom_arguments(nd::Int64, ss::Int64, us::Vector{Int64})
   @ KomaMRIBase ~/src/KomaMRI/KomaMRIBase/src/datatypes/Phantom.jl:549
 [2] top-level scope
   @ REPL[2]:1

julia> KomaMRIBase.check_phantom_arguments(3, 1, [1, 1, 1])
[ Info: setting ss=1 since us=[1, 1, 1] defined
(1, 1, 1, 1, 1, 1)

[cncastillo]

I completely forgot to merge this. I will run tests including some recent changes, and then merge.

[aTrotier]

Thanks 🙏

hen an official release of Koma will be tagged, I'll share my example from pypulseq to qMRI for the MP2RAGE.
It will be a good example to show how to label the AcquisitionData to get 2 TI images in the reconstruction.

And I will also try to label directly the profiles in the RawAcquisitioDdata in order to get a standard cartesian acquisition data rather than using the nufft reconstruction :)

[cncastillo]

Ok, all the tests are running. I will be merging this.

@beorostica can you release a new set of patch package versions? (after checking everything looks good with the docs, plots, etc...)

@aTrotier Tell us if you need any help.

[curtcorum]

@cncastillo Still need to merge?

[cncastillo]

Oh god, thanks for noticing! merged!