ROMEO

CITATIONS

Reference text for the methods in the toolbox, keyed by method. ROMEO seeds this with its own; other packages add theirs through register_citation!.

LABELS

Human-readable method name for each key, used as the heading above its reference in the citations file. A reader should be able to tell which step of the run each reference is for without recognising the paper.

NOTICES

Non-citation facts a method carries, keyed like CITATIONS. Written into the citations file when that method ran, because that file is what someone reads before publishing or before shipping a product.

calculateweights(wrapped; weights=:romeo, kwargs...)

Calculates weights for all edges. size(weights) == [3, size(wrapped)...]

Optional keyword arguments:

• weights: Options are [:romeo] | :romeo2 | :romeo3 | :bestpath.
• mag: Additional mag weights are used.
• mask: Unwrapping is only performed inside the mask.
• phase2: A second reference phase image (possibly with different echo time). It is used for calculating the phasecoherence weight.
• TEs: The echo times of the phase and the phase2 images as a tuple (eg. (5, 10) or [5, 10]).

package_version(m::Module)

The version of the package m, as a string, for a provenance record.

pkgversion reads a package's Project.toml through path metadata that the module carries at runtime, and it returns nothing rather than throwing when that metadata is not there, which is how a settings file ends up recording the literal word "nothing". A sysimage built with --strip-metadata is one case; a module defined outside a package is another. Packages in this family therefore also record their own version in a PKG_VERSION constant, which is evaluated while the package is precompiled and is part of the image after that, so it survives both.

parse_array(str)

Parse the array syntax the command line tools accept: an array literal ("[1.5,3.0]", brackets optional, comma or space separated), a range ("1:3", "3.5:3.5:14"), a bare ":", or a single number.

Returns Colon() for ":", the number itself for a single value, and a Vector{Int} or Vector{Float64} otherwise - never a Matrix and never a lazy range, so the result reads the same in a provenance record as it behaves in the code. Throws an ArgumentError naming the offending text if it is not one of those forms.

parse_weight_flags(str)

Parse ROMEO's --weights bit string ("1010", up to six flags) into a BitVector of length 6. Returns nothing when str is not a bit string, which is how the caller tells a set of flags from a named weighting like "romeo3".

register_citation!(key, text; notice=nothing, label=nothing)

Register the reference for a method, to be written by write_provenance when that method is used. Call this from a package's __init__ for the methods that package implements, so the text lives with the code rather than in whichever tool happens to print it.

label is the method name shown as a heading above the reference, so a reader can see which step of the run it belongs to. Two keys may share a label, in which case their references appear together under one heading - which is how a method with more than one reference is expressed. Defaults to the key.

Re-registering the same key with identical text is a no-op; changing the text of an existing key warns, because two packages disagreeing about a reference is a bug worth hearing about.

unwrap(wrapped::AbstractArray; keyargs...)

ROMEO unwrapping for 3D and 4D data.

Optional keyword arguments:

• TEs: Required for 4D data. The echo times for multi-echo data. In the case of single-echo application with phase and the phase2 as a tuple (eg. (5, 10) or [5, 10]).
• weights: Options are [:romeo] | :romeo2 | :romeo3 | :bestpath.
• mag: The magnitude is used to improve the unwrapping-path.
• mask: Unwrapping is only performed inside the mask.
• phase2: A second reference phase image (possibly with different echo time). It is used for calculating the phasecoherence weight. This is automatically done for 4D multi-echo input and therefore not required.
• correctglobal=false: If true corrects global n2π offsets.
• individual=false: If true perform individual unwrapping of echos. Type ?unwrap_individual for more information
• template=1: echo that is spatially unwrapped (if individual is false)
• maxseeds=1: higher values allow more seperate regions
• merge_regions=false: spatially merge neighboring regions after unwrapping
• correct_regions=false: bring each regions median closest to 0 by adding n2π
• wrap_addition=0: [0;π], allows 'linear unwrapping', neighbors can have more (π+wrap_addition) phase difference
• temporal_uncertain_unwrapping=0.5: Useful for veins. It uses spatial unwrapping on voxels that have high uncertainty values after temporal unwrapping. A higher quality threshold re-unwraps more voxels spatially.

Examples

julia> using MriResearchTools
julia> phase = readphase("phase_3echo.nii")
julia> unwrapped = unwrap(phase; TEs=[1,2,3])
julia> savenii(unwrapped, "unwrapped.nii"; header=header(phase))

unwrap(wrapped::AbstractArray; keyargs...)

ROMEO unwrapping for 3D and 4D data.

Optional keyword arguments:

• TEs: Required for 4D data. The echo times for multi-echo data. In the case of single-echo application with phase and the phase2 as a tuple (eg. (5, 10) or [5, 10]).
• weights: Options are [:romeo] | :romeo2 | :romeo3 | :bestpath.
• mag: The magnitude is used to improve the unwrapping-path.
• mask: Unwrapping is only performed inside the mask.
• phase2: A second reference phase image (possibly with different echo time). It is used for calculating the phasecoherence weight. This is automatically done for 4D multi-echo input and therefore not required.
• correctglobal=false: If true corrects global n2π offsets.
• individual=false: If true perform individual unwrapping of echos. Type ?unwrap_individual for more information
• template=1: echo that is spatially unwrapped (if individual is false)
• maxseeds=1: higher values allow more seperate regions
• merge_regions=false: spatially merge neighboring regions after unwrapping
• correct_regions=false: bring each regions median closest to 0 by adding n2π
• wrap_addition=0: [0;π], allows 'linear unwrapping', neighbors can have more (π+wrap_addition) phase difference
• temporal_uncertain_unwrapping=0.5: Useful for veins. It uses spatial unwrapping on voxels that have high uncertainty values after temporal unwrapping. A higher quality threshold re-unwraps more voxels spatially.

Examples

julia> using MriResearchTools
julia> phase = readphase("phase_3echo.nii")
julia> unwrapped = unwrap(phase; TEs=[1,2,3])
julia> savenii(unwrapped, "unwrapped.nii"; header=header(phase))

unwrap_individual(wrapped::AbstractArray{T,4}; TEs, keyargs...) where T

Performs individual unwrapping of the echoes instead of temporal unwrapping. Still uses multi-echo information to improve the quality map. This function is identical to unwrap with the flag individual=true. The syntax is identical to unwrap, but doesn't support the temporal_uncertain_unwrapping and template options:

unwrap_individual(wrapped::AbstractArray{T,4}; TEs, keyargs...) where T

Performs individual unwrapping of the echoes instead of temporal unwrapping. Still uses multi-echo information to improve the quality map. This function is identical to unwrap with the flag individual=true. The syntax is identical to unwrap, but doesn't support the temporal_uncertain_unwrapping and template options:

voxelquality(phase::AbstractArray; keyargs...)

Calculates a quality for each voxel. The voxel quality can be used to create a mask. The quality range is [0;1]

Examples

julia> qmap = voxelquality(phase_3echo; TEs=[1,2,3]);
julia> mask = robustmask(qmap);

Takes the same inputs as romeo/unwrap:

See also unwrap

write_citations(dir, tool; cite, optional=Symbol[])

Write citations_<tool>.txt into dir, covering only the methods named in cite. Keys are looked up in the citation registry, which each package fills in for the methods it implements (see register_citation!); a key with no registered citation is warned about rather than silently omitted, because a missing reference is the failure this is meant to prevent. Any notice attached to a used method is written below the references, and optional keys that are registered but were not used are listed separately.

The registry itself is ROMEO.CITATIONS, ROMEO.NOTICES and ROMEO.LABELS. None are exported: the names are too generic to put in every user's namespace, and register_citation! plus this function are the intended interface.

write_provenance(dir, tool; version, args, settings, cite, optional=Symbol[],
                 inputs=(), packages=(), describe=abspath)

Write settings_<tool>.txt and citations_<tool>.txt into dir, recording what was run and what has to be cited for it.

• version the application version string.
• args the raw command line arguments.
• settings any key-value collection of resolved settings. Written sorted, and array values are written out rather than skipped, so the echo times actually used are recoverable from the record.
• cite the methods that were actually used, as keys of CITATIONS. Pass only what ran: a citation for a method the user did not use is as wrong as a missing one. Any NOTICES entry for those methods is included too.
• optional further methods to list under "Optional citations".
• inputs name => path pairs for the input files.
• packages modules whose versions did the work, recorded alongside the Julia version so a result can be traced to the code that produced it.
• describe how to render an input path. Defaults to the absolute path; callers that can read the file cheaply pass something that adds the dimensions.

Examples

julia> write_provenance("out", "romeo"; version="4.7.1", args=ARGS, settings,
                        cite=[:romeo, :aspire], inputs=["phase" => fn_phase],
                        packages=[ROMEO])