Merge branch 'master' of https://github.com/MagneticParticleImaging/M…

…PIFiles.jl

docs/make.jl

@@ -11,9 +11,9 @@ makedocs(
         "Low Level Interface" => "lowlevel.md",
         "Conversion" => "conversion.md",
         "Measurements" => "measurements.md",
-        "System Matrix" => "systemmatrix.md",
+        "System Matrices" => "systemmatrix.md",
         "Frequency Filter" => "frequencyFilter.md",
-        "Reconstructions" => "images.md"
+        "Reconstruction Results" => "reconstruction.md"
       #  "Positions" => "positions.md"
     ],
     html_prettyurls = false, #!("local" in ARGS),

docs/src/conversion.md

@@ -8,15 +8,15 @@ saveasMDF(filenameOut, filenameIn)
 ```
 The second argument can alternatively also be an `MPIFile` handle.
 
-There is also a more low level interface which gives the user the control to
+Alternatively, there is also a more low level interface which gives the user the control to
 change parameters before storing. This look like this
 ```julia
 params = loadDataset(f)
 # do something with params
 saveasMDF(filenameOut, params)
 ```
 Here, `f` is an `MPIFile` handle and the command `loadDataset` loads the entire
-dataset including all parameters into a Julia `Dict` that can be modified by the
+dataset including all parameters into a Julia `Dict`, which can be modified by the
 user. After modification one can store the data by passing the `Dict` as the
 second argument to the `saveasMDF` function.
 

docs/src/gettingStarted.md

@@ -1,27 +1,35 @@
 # Getting Started
 
+In order to get started with MPIFiles we first need some example datasets.
+These can be obtained by calling
+```julia
+download("https://media.tuhh.de/ibi/mdfv2/measurement_V2.mdf", "measurements.mdf")
+download("https://media.tuhh.de/ibi/mdfv2/systemMatrix_V2.mdf", "systemMatrix.mdf")
+```
+which will download an MPI system matrix and an MPI measurement dataset into
+the current directory.
+
 An MPI data file consists of a collection of parameters that can be
-divided into metadata and measurement data. Let us now consider that
-the string `filename` contains the path to an MPI file (e.g. an MDF file).
-Then be can open the file by calling
+divided into metadata and measurement data. We can open the downloaded MPI
+measurement data by calling
 ```julia
-julia> f = MPIFile(filename)
+f = MPIFile("measurements.mdf")
 ```
 `f` can be considered to be a handle to the file. The file will be automatically
-be closed when `f` is garbage collected. The philosophy of MPIFiles.jl is that
+ closed when `f` is garbage collected. The philosophy of MPIFiles.jl is that
 the content of the file is only loaded on demand. Hence, opening an MPI file
-is a cheap operations. This design allows it, to handle system matrices, which
+is a cheap operation. This design allows it, to handle system matrices, which
 are larger than the main memory of the computer.
 
-Using the file handle it is possible now to read out different metadata. For instance
+Using the file handle it is possible now to read out different metadata. For instance,
 we can determine the number of frames measured:
 ```julia
-julia> acqNumFrames(f)
+println( acqNumFrames(f) )
 500
 ```
 Or we can access the drive field strength
 ```julia
-julia> dfStrength(f)
+println( dfStrength(f) )
 1×3×1 Array{Float64,3}:
 [:, :, 1] =
  0.014  0.014  0.0

docs/src/index.md

@@ -34,14 +34,15 @@ This will install the packages `MPIFiles.jl` and all its dependencies.
 The source code of this project is licensed under the MIT license. This implies that
 you are free to use, share, and adapt it. However, please give appropriate credit by citing the project.
 
-## Contact
+## Community Guidelines
 
-If you have problems using the software, find mistakes, or have general questions please use
-the [issue tracker](https://github.com/MagneticParticleImaging/MPIFiles.jl/issues) to contact us.
+If you have problems using the software, find bugs, or have feature requests please use the [issue tracker](https://github.com/MagneticParticleImaging/MPIFiles.jl/issues) to contact us. For general questions we prefer that you contact the current maintainer directly by email.
+
+We welcome community contributions to `MPIFiles.jl`. Simply create a [pull request](https://github.com/MagneticParticleImaging/MPIFiles.jl/pulls) with your proposed changes.
 
 ## Contributors
 
-* [Tobias Knopp](https://www.tuhh.de/ibi/people/tobias-knopp-head-of-institute.html)
+* [Tobias Knopp](https://www.tuhh.de/ibi/people/tobias-knopp-head-of-institute.html) (maintainer)
 * [Martin Möddel](https://www.tuhh.de/ibi/people/martin-moeddel.html)
 * [Patryk Szwargulski](https://www.tuhh.de/ibi/people/patryk-szwargulski.html)
 * [Florian Griese](https://www.tuhh.de/ibi/people/florian-griese.html)

docs/src/measurements.md

@@ -41,7 +41,7 @@ function getMeasurementsFD(f::MPIFile, neglectBGFrames=true;
                   tfCorrection=measIsTFCorrected(f),
                   kargs...)
 ```
-The function has basically the same parameters as `getMeasurements` but additionally
+The function has basically the same parameters as `getMeasurements` but, additionally,
 it is possible to load the data in real form (useful when using a solver that cannot
 handle complex numbers), it is possible to specify the frequencies (specified by
 the indices) that should be loaded, and it is possible to transpose the data

docs/src/images.md → docs/src/reconstruction.md

@@ -10,7 +10,7 @@ function recoSize(f::MPIFile)
 function recoOrder(f::MPIFile)
 function recoPositions(f::MPIFile)
 ```
-Instead one can also combine these data into an `ImageMetadata` object from the
+Instead, one can also combine these data into an `ImageMetadata` object from the
 [Images.jl](https://github.com/JuliaImages/Images.jl) package by calling the
 functions
 ```julia

docs/src/systemmatrix.md

@@ -2,9 +2,9 @@
 
 For loading the system matrix, one could in principle again call `measData` but there
 is again a high level function for this job. Since system functions can be very large
-it is crutial to load only the subset of frequencies that are used during reconstruction
+it is crucial to load only the subset of frequencies that are used during reconstruction
 The high level system matrix loading function is called `getSystemMatrix` and has
-the following interface
+the following interface:
 ```julia
 function getSystemMatrix(f::MPIFile,
                          frequencies=1:rxNumFrequencies(f)*rxNumChannels(f);
@@ -13,6 +13,10 @@ function getSystemMatrix(f::MPIFile,
                          kargs...)
 ```
 `loadasreal` can again be used when using a solver requiring real numbers.
-The most important parameter is frequencies, which defaults to all possible
-frequencies over all receive channels. In practice one will determine the
-frequencies using the the [Frequency Filter](@ref) functionality.
+The most important parameter is `frequencies`, which defaults to all possible
+frequencies over all receive channels. In practice, one will determine the
+frequencies using the the [Frequency Filter](@ref) functionality. The parameter
+`bgCorrection` controls if a  background correction is applied while loading the
+system matrix. The return value of `getSystemMatrix` is a matrix of type `ComplexF32`
+or `Float32` with the rows encoding the spatial dimension and the columns encoding
+the dimensions frequency, receive channels, and patches.

paper/paper.bib

@@ -1,6 +1,6 @@
 @Book{knopp2012magnetic,
   Title                    = {Magnetic Particle Imaging: An Introduction to Imaging Principles and Scanner Instrumentation},
-  Author                   = {Tobias Knopp and {Thorsten M. Buzug}},
+  Author                   = {Tobias Knopp and {T. M.} Buzug},
   Publisher                = {Springer},
   Year                     = {2012},
   Address                  = {Berlin/Heidelberg},
@@ -24,6 +24,16 @@ @article{Gleich2005
   timestamp = {2007.12.12}
 }
 
+@article{graser2019human,
+  title={Human-sized magnetic particle imaging for brain applications},
+  author={Gr{\"a}ser, Matthias and Thieben, Florian and Szwargulski, Patryk and Werner, Franziska and Gdaniec, Nadine and Boberg, Marija and Griese, Florian and Hofmann, Martin and Ludewig, Peter and Ven, Dionys van de and Weber, {O.M.} and Woywode, Oliver and Gleich, Bernhard and Knopp Tobias},
+  journal={Nature communications},
+  volume={10},
+  number={1936},
+  pages={1--9},
+  year={2019},
+  doi={10.1038/s41467-019-09704-x}
+}
 
 @article{knopp2017magnetic,
   title={Magnetic particle imaging: From proof of principle to preclinical applications},
@@ -43,6 +53,7 @@ @article{knopp2016MDF
     title = "{MDF: Magnetic Particle Imaging Data Format}",
   journal = {ArXiv e-prints},
 archivePrefix = "arXiv",
+   volume = {1602.06072},
    eprint = {1602.06072},
  primaryClass = "physics.med-ph",
  keywords = {Physics - Medical Physics},

paper/paper.md

@@ -31,49 +31,39 @@ affiliations:
    index: 1
  - name: Institute for Biomedical Imaging, Hamburg University of Technology
    index: 2
-date: ?? March 2019
+date: ?? May 2019
 bibliography: paper.bib
 ---
 
 # Summary
 
-Tomographic imaging methods allows to visualize the interior of the human body in a
+Tomographic imaging methods allow to visualize the interior of the human body in a
 non-invasive way. Most prominent examples used for medical diagnosis are the
 computed tomography (CT) and magnetic resonance imaging (MRI).
 In 2015 [@Gleich2005], Bernhard Gleich and Jürgen Weizenecker introduced a new tomographic
 imaging method named Magnetic Particle Imaging (MPI) that allows to image
 the 3D distribution of magnetic nanoparticles (MNP) in realtime [@knopp2012magnetic; @knopp2017magnetic].
 The MNP can be injected intravenously and allow to image the vessel tree as well
-as organ perfusion. The MNPs are harmless for the human body and are degraded in the
+as organ perfusion [@graser2019human]. The MNPs are harmless for the human body and are degraded in the
 liver.
 
-When working with an MPI scanner there are various datasets involved. During an
-MPI experiment, the signal is measured using inductive receive coils. In order to
-reconstruct an image of the MNP distribution one requires knowledge of the MPI
-system matrix, which is usually measured within a calibration measurement.
-The software package ``MPIFiles.jl`` provides an interface to all these types of data.
-In particular it has full support for the Magnetic Particle Imaging
-Data Format (MDF) [@knopp2016MDF], which is an open, HDF5 based, data format that
-has been developed with the purpose of standardizing data storage in MPI. Additionally,
-``MPIFiles.jl`` has full read support for datasets measured with the preclinical
-MPI scanner from the vendor Bruker. Each data format is implemented using a dedicated
-type and implements a common interface such that the user of the package can write
-generic code for different file types. In addition to read support, the package also
-has conversion routines for creating MDF files from Brukerfiles.
+When working with an MPI scanner different datasets are involved. In addition to the raw data, which consist of the induced voltage signals, a calibration dataset is required to reconstruct the particle concentration. The latter describes the physical relationship between the particle concentration and the measurement signal and is usually recorded in MPI with a delta-shaped point sample.
+The software package ``MPIFiles.jl`` provides an interface to all these data types. Besides the proprietary data format recorded with MPI scanners from Bruker, ``MPIFiles.jl`` implements the vendor-independent Magnetic Particle Imaging
+Data Format (MDF)[@knopp2016MDF], which is based on HDF5 and was developed with the aim to standardize data storage in MPI. Each data format implements a common interface and enables the user to write generic code for different file types. Besides the read and write capability for different data formats, ``MPIFiles.jl`` also offers the possibility of converting different data formats into each other.
 
 ``MPIFiles.jl`` supports the following types of MPI data
+
 * measurements
 * calibration data, i.e. system matrices
 * reconstruction results
+
 In addition to a low level access to the data, the package also features
-high level routines that provide various post-processing methods such as
+high level routines providing various post-processing methods such as
 frequency filtering, spectral leakage correction, block-averaging, and
 transfer function correction.
 
-The API of ``MPIFiles.jl`` is aligned with the parameter names of the MDF
-specification such that the latter can be used as a reference for determining
-the content and dimensionality of certain parameters.
-``MPIFiles.jl`` is licensed under MIT license and is hosted on Github at
+The API of ``MPIFiles.jl`` is based on the parameter names of the MDF specification, so that the latter can be used as a reference for the description of parameters and their dimensionality.
+``MPIFiles.jl`` is licensed under the MIT license and hosted on Github at
 https://github.com/MagneticParticleImaging/MPIFiles.jl.
 
 # References

src/Brukerfile.jl

@@ -532,7 +532,7 @@ end
 recoResolution(f::BrukerFile) = push!(parse.(Float64,f["PVM_SpatResol"])./1000,
                                 parse(Float64,f["ACQ_slice_thick"])./1000)
 
-recoFov(f::BrukerFile) = recoResolution(f).*recoSize(f) 
+recoFov(f::BrukerFile) = recoResolution(f).*recoSize(f)
 
 recoFovCenter(f::BrukerFile) = zeros(3)
 recoSize(f::BrukerFile) = push!(parse.(Int,f["RECO_size",1]),