From 2f717e0aae3e11de7ccb9ae75727a4a24db6e7a0 Mon Sep 17 00:00:00 2001 From: mathiasg Date: Tue, 5 Nov 2019 16:49:14 -0500 Subject: [PATCH 1/2] initial joss draft --- joss/nt.bib | 51 ++++++++++++++++++++++ joss/paper.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 joss/nt.bib create mode 100644 joss/paper.md diff --git a/joss/nt.bib b/joss/nt.bib new file mode 100644 index 00000000..a70c8f93 --- /dev/null +++ b/joss/nt.bib @@ -0,0 +1,51 @@ +@article{cox_software_1997, + author = {Cox, Robert W. and Hyde, James S.}, + copyright = {Copyright © 1997 John Wiley \& Sons, Ltd.}, + doi = {10.1002/(SICI)1099-1492(199706/08)10:4/5{ extless}171::AID-NBM453{ extgreater}3.0.CO;2-L}, + issn = {1099-1492}, + journal = {NMR Biomed}, + language = {en}, + number = {4-5}, + pages = {171-178}, + title = {Software tools for analysis and visualization of fMRI data}, + url = {http://onlinelibrary.wiley.com/doi/10.1002/(SICI)1099-1492(199706/08)10:4/5{ extless}171::AID-NBM453{ extgreater}3.0.CO;2-L/abstract}, + volume = 10, + year = 1997 +} + +@article{brett_nibabel_2006, + author = {Brett, Matthew and Markiewicz, Christopher J. and Hanke, Michael and Cote, Marc-Alexandre and Cipollini, Ben and McCarthy, Paul and Cheng, Chris and Halchenko, Yaroslav O. and Ghosh, Satrajit S. and Larson, Eric and Wassermann, Demian and Gerhard, Stephan}, + doi = {10.5281/zenodo.591597}, + journal = {Zenodo}, + pages = 3458246, + title = {{Open Source Software: NiBabel}}, + url = {https://zenodo.org/record/3458246\#.XaS82-ZKi5M}, + year = 2006 +} + +@article{fischl_freesurfer_2012, + author = {Fischl, B.}, + doi = {10.1016/j.neuroimage.2012.01.021}, + issn = {1053-8119}, + journal = {NeuroImage}, + number = 2, + pages = {774-781}, + title = {{FreeSurfer}}, + url = {http://www.sciencedirect.com/science/article/pii/S1053811912000389}, + volume = 62, + year = 2012 +} + +@article{jenkinson_fsl_2012, + author = {Jenkinson, Mark and Beckmann, Christian F. and Behrens, Timothy E.J. and Woolrich, Mark W. and Smith, Stephen M.}, + doi = {10.1016/j.neuroimage.2011.09.015}, + issn = {1053-8119}, + journal = {NeuroImage}, + number = 2, + pages = {782-790}, + shorttitle = {FSL}, + title = {{FSL}}, + url = {http://www.sciencedirect.com/science/article/pii/S1053811911010603}, + volume = 62, + year = 2012 +} diff --git a/joss/paper.md b/joss/paper.md new file mode 100644 index 00000000..98c7d8fb --- /dev/null +++ b/joss/paper.md @@ -0,0 +1,118 @@ +--- +title: 'Nitransforms: A Python tool to read, represent, manipulate, and apply $n$-dimensional spatial transforms' +tags: + - Python + - neuroimaging + - image processing + - spatial transform + - nibabel +authors: + - name: Mathias Goncalves + orcid: 0000-0002-7252-7771 + affiliation: 1 + - name: Christopher J. Markiewicz + orcid: 0000-0002-6533-164X + affiliation: "1, 2" + - name: Satrajit S. Ghosh + orcid: 0000-0002-5312-6729 + affiliation: "2, 3" + - name: Russell A. Poldrack + orcid: 0000-0001-6755-0259 + affiliation: 1 + - name: Oscar Esteban + orcid: 0000-0001-8435-6191 + affiliation: 1 +affiliations: + - name: Department of Psychology, Stanford University, Stanford, CA, USA + index: 1 + - name: McGovern Institute for Brain Research, Massachusetts Institute of Technology (MIT), Cambridge, MA, USA + index: 2 + - name: Department of Otolaryngology, Harvard Medical School, Boston, MA, USA + index: 3 +date: 04 November 2019 +bibliography: nt.bib +--- + +# Summary + +Spatial transforms formalize mappings between coordinates of objects in +biomedical images. Transforms typically are the outcome of image registration +methodologies, which estimate the alignment between two images. Image +registration is a prominent task present in image processing. In neuroimaging, +the proliferation of image registration software implementations has resulted +in a disparate collection of structures and file formats used to preserve and +communicate the transformation. This assortment of formats presents the +challenge of compatibility between tools and endangers the reproducibility of +results. + +`nitransforms` is a Python tool capable of reading and writing tranforms +produced by the most popular neuroimaging software (AFNI [-@cox_software_1997], +FSL [-@jenkinson_fsl_2012], FreeSurfer [-@fischl_freesurfer_2012], ITK, and SPM). +Additionally, the tool provides seamless conversion between these formats, as +well as the ability of applying the transforms to other images. `nitransforms` +is inspired by `NiBabel` [@brett_nibabel_2006], a Python package with a +collection of tools to read, write and handle neuroimaging data, and will be +included as a new module. + + +# Software Architecture + +There are four main components within the tool: an `io` submodule to handle +the structure of the various file formats, a `base` submodule where abstract +classes are defined, a `linear` submodule implementing $n$-dimensional linear +transforms, and a `nonlinear` submodule for both parametric and non-parametric +nonlinear transforms. Furthermore, `nitranforms` provides a straightforward +API (Application Programming Interface) that allows researchers to map point +sets via transforms, as well as apply transforms (i.e., mapping the coordinates +and interpolating the data) to data structures with ease. + +To ensure the consistency and uniformity of internal operations, all transforms +are defined using a left-handed coordinate system of physical coordinates. In +words from the neuroimaging domain, the coordinate system of transforms is +_RAS+_ (or positive directions point to the Righthand for the first axis, +Anterior for the second, and Superior for the third axis). The internal +representation of transform coordinates is the most relevant design decision, +and implies that a conversion of coordinate system is necessary to correctly +interpret transforms generated by other software. When a transform that is +defined in another coordinate system is loaded, it is automatically converted +into _RAS+_ space. + +`nitransforms` was developed using a test-driven development paradigm, with the +battery of tests being written prior to the software implementations. Two +categories of tests were used: unit tests and cross-tool comparison tests. Unit +tests evaluate the formal correctness of the implementation, while cross-tool +comparison tests assess the correct implementation of third-party software. +The testing suite is incorporated into a continuous integration framework, which +assesses the continuity of the implementation along the development life and +ensures that code changes and additions do not break existing functionalities. + +# Spatial transforms + +Let $\vec{x}$ represent the coordinates of a point in the reference coordinate +system $R$, and $\vec{x}'$ its projection on to another coordinate system $M$: + +$T\colon R \subset \mathbb{R}^n \to M \subset \mathbb{R}^n$ + +$\vec{x} \mapsto \vec{x}' = f(\vec{x}).$ + +In an image registration problem, $M$ is a moving image from which we want to +sample data in order to bring the image into spatial alignment with the +reference image $R$. Hence, $f$ here is the spatial transformation function +that maps from coordinates in $R$ to coordinates in $M$. There are a +multiplicity of image registration algorithms and corresponding image +transformation models to estimate linear and nonlinear transforms. + +The problem has been traditionally confused by the need of _transforming_ or +mapping one image (generally referred to as _moving_) into another that serves +as reference, with the goal of _fusing_ the information from both. An example of +image fusion application would be the alignment of functional data from one +individual's brain to the same individual's corresponding anatomical MRI scan +for visualization. Therefore, "applying a transform" entails two operations: +first, transforming the coordinates of the samples in the reference image $R$ to +find their mapping $\vec{x}'$ on $M$ via $T\{\cdot\}$, and second, an +interpolation step as $\vec{x}'$ will likely fall off-the-grid of the moving +image $M$. These two operations are confusing because, while the spatial +transformation projects from $R$ to $M$, the data flows in reversed way after the +interpolation of the values of $M$ at the mapped coordinates $\vec{x}'$. + +# References From a1b1d64ee302d3f88ab20591e3903254dee05aa4 Mon Sep 17 00:00:00 2001 From: mathiasg Date: Tue, 12 Nov 2019 15:00:53 -0500 Subject: [PATCH 2/2] address comments from @oesteban review --- joss/nt.bib | 24 ++++++++++++ joss/paper.md | 102 +++++++++++++++++--------------------------------- 2 files changed, 58 insertions(+), 68 deletions(-) diff --git a/joss/nt.bib b/joss/nt.bib index a70c8f93..80e6d92d 100644 --- a/joss/nt.bib +++ b/joss/nt.bib @@ -49,3 +49,27 @@ @article{jenkinson_fsl_2012 volume = 62, year = 2012 } + +@article{avants_symmetric_2008, + author = {Avants, B.B. and Epstein, C.L. and Grossman, M. and Gee, J.C.}, + doi = {10.1016/j.media.2007.06.004}, + issn = {1361-8415}, + journal = {Medical Image Analysis}, + number = 1, + pages = {26-41}, + shorttitle = {Symmetric diffeomorphic image registration with cross-correlation}, + title = {Symmetric diffeomorphic image registration with cross-correlation: Evaluating automated labeling of elderly and neurodegenerative brain}, + url = {http://www.sciencedirect.com/science/article/pii/S1361841507000606}, + volume = 12, + year = 2008 +} + +@book{friston_statistical_2006, + address = {London}, + author = {Friston, Karl J. and Ashburner, John and Kiebel, Stefan J. and Nichols, Thomas E. and Penny, William D.}, + isbn = {978-0-12-372560-8}, + publisher = {Academic Press}, + shorttitle = {Statistical parametric mapping}, + title = {Statistical parametric mapping : the analysis of functional brain images}, + year = 2006 +} diff --git a/joss/paper.md b/joss/paper.md index 98c7d8fb..aa1f8c08 100644 --- a/joss/paper.md +++ b/joss/paper.md @@ -1,5 +1,5 @@ --- -title: 'Nitransforms: A Python tool to read, represent, manipulate, and apply $n$-dimensional spatial transforms' +title: 'NiTransforms: A Python tool to read, represent, manipulate, and apply $n$-dimensional spatial transforms' tags: - Python - neuroimaging @@ -35,84 +35,50 @@ bibliography: nt.bib # Summary -Spatial transforms formalize mappings between coordinates of objects in -biomedical images. Transforms typically are the outcome of image registration -methodologies, which estimate the alignment between two images. Image -registration is a prominent task present in image processing. In neuroimaging, -the proliferation of image registration software implementations has resulted -in a disparate collection of structures and file formats used to preserve and -communicate the transformation. This assortment of formats presents the -challenge of compatibility between tools and endangers the reproducibility of -results. +Spatial transforms formalize mappings between coordinates of objects in biomedical images. +Transforms typically are the outcome of image registration methodologies, which estimate the alignment between two images. +Image registration is a prominent task present in image processing. +In neuroimaging, the proliferation of image registration software implementations has resulted in a disparate collection of structures and file formats used to preserve and communicate the transformation. +This assortment of formats presents the challenge of compatibility between tools and endangers the reproducibility of results. -`nitransforms` is a Python tool capable of reading and writing tranforms -produced by the most popular neuroimaging software (AFNI [-@cox_software_1997], -FSL [-@jenkinson_fsl_2012], FreeSurfer [-@fischl_freesurfer_2012], ITK, and SPM). -Additionally, the tool provides seamless conversion between these formats, as -well as the ability of applying the transforms to other images. `nitransforms` -is inspired by `NiBabel` [@brett_nibabel_2006], a Python package with a -collection of tools to read, write and handle neuroimaging data, and will be -included as a new module. +_NiTransforms_ is a Python tool capable of reading and writing tranforms produced by the most popular neuroimaging software (AFNI [@cox_software_1997], FSL [@jenkinson_fsl_2012], FreeSurfer [@fischl_freesurfer_2012], ITK via ANTs [@avants_symmetric_2008], and SPM [@friston_statistical_2006]). +Additionally, the tool provides seamless conversion between these formats, as well as the ability of applying the transforms to other images. +_NiTransforms_ is inspired by `NiBabel` [@brett_nibabel_2006], a Python package with a collection of tools to read, write and handle neuroimaging data, and will be included as a new module. +# Spatial transforms -# Software Architecture +Let $\vec{x}$ represent the coordinates of a point in the reference coordinate system $R$, and $\vec{x}'$ its projection on to another coordinate system $M$: -There are four main components within the tool: an `io` submodule to handle -the structure of the various file formats, a `base` submodule where abstract -classes are defined, a `linear` submodule implementing $n$-dimensional linear -transforms, and a `nonlinear` submodule for both parametric and non-parametric -nonlinear transforms. Furthermore, `nitranforms` provides a straightforward -API (Application Programming Interface) that allows researchers to map point -sets via transforms, as well as apply transforms (i.e., mapping the coordinates -and interpolating the data) to data structures with ease. +$T\colon R \subset \mathbb{R}^n \to M \subset \mathbb{R}^n$ -To ensure the consistency and uniformity of internal operations, all transforms -are defined using a left-handed coordinate system of physical coordinates. In -words from the neuroimaging domain, the coordinate system of transforms is -_RAS+_ (or positive directions point to the Righthand for the first axis, -Anterior for the second, and Superior for the third axis). The internal -representation of transform coordinates is the most relevant design decision, -and implies that a conversion of coordinate system is necessary to correctly -interpret transforms generated by other software. When a transform that is -defined in another coordinate system is loaded, it is automatically converted -into _RAS+_ space. +$\vec{x} \mapsto \vec{x}' = f(\vec{x}).$ -`nitransforms` was developed using a test-driven development paradigm, with the -battery of tests being written prior to the software implementations. Two -categories of tests were used: unit tests and cross-tool comparison tests. Unit -tests evaluate the formal correctness of the implementation, while cross-tool -comparison tests assess the correct implementation of third-party software. -The testing suite is incorporated into a continuous integration framework, which -assesses the continuity of the implementation along the development life and -ensures that code changes and additions do not break existing functionalities. +In an image registration problem, $M$ is a moving image from which we want to sample data in order to bring the image into spatial alignment with the reference image $R$. +Hence, $f$ here is the spatial transformation function that maps from coordinates in $R$ to coordinates in $M$. +There are a multiplicity of image registration algorithms and corresponding image transformation models to estimate linear and nonlinear transforms. -# Spatial transforms +The problem has been traditionally confused by the need of _transforming_ or mapping one image (generally referred to as _moving_) into another that serves as reference, with the goal of _fusing_ the information from both. +An example of image fusion application would be the alignment of functional data from one individual's brain to the same individual's corresponding anatomical MRI scan for visualization. +Therefore, "applying a transform" entails two operations: first, transforming the coordinates of the samples in the reference image $R$ to find their mapping $\vec{x}'$ on $M$ via $T\{\cdot\}$, and second an interpolation step as $\vec{x}'$ will likely fall off-the-grid of the moving image $M$. +These two operations are confusing because, while the spatial transformation projects from $R$ to $M$, the data flows in reversed way after the interpolation of the values of $M$ at the mapped coordinates $\vec{x}'$. -Let $\vec{x}$ represent the coordinates of a point in the reference coordinate -system $R$, and $\vec{x}'$ its projection on to another coordinate system $M$: +# Software Architecture -$T\colon R \subset \mathbb{R}^n \to M \subset \mathbb{R}^n$ +There are four main components within the tool: an `io` submodule to handle the structure of the various file formats, a `base` submodule where abstract classes are defined, a `linear` submodule implementing $n$-dimensional linear transforms, and a `nonlinear` submodule for both parametric and non-parametric nonlinear transforms. +Furthermore, _NiTranforms_ provides a straightforward _Application Programming Interface_ (API) that allows researchers to map point sets via transforms, as well as apply transforms (i.e., mapping the coordinates and interpolating the data) to data structures with ease. -$\vec{x} \mapsto \vec{x}' = f(\vec{x}).$ +To ensure the consistency and uniformity of internal operations, all transforms are defined using a left-handed coordinate system of physical coordinates. +In words from the neuroimaging domain, the coordinate system of transforms is _RAS+_ (or positive directions point to the Righthand for the first axis, Anterior for the second, and Superior for the third axis). +The internal representation of transform coordinates is the most relevant design decision, and implies that a conversion of coordinate system is necessary to correctly interpret transforms generated by other software. +When a transform that is defined in another coordinate system is loaded, it is automatically converted into _RAS+_ space. -In an image registration problem, $M$ is a moving image from which we want to -sample data in order to bring the image into spatial alignment with the -reference image $R$. Hence, $f$ here is the spatial transformation function -that maps from coordinates in $R$ to coordinates in $M$. There are a -multiplicity of image registration algorithms and corresponding image -transformation models to estimate linear and nonlinear transforms. +_NiTransforms_ was developed using a test-driven development paradigm, with the +battery of tests being written prior to the software implementations. +Two categories of tests were used: unit tests and cross-tool comparison tests. +Unit tests evaluate the formal correctness of the implementation, while cross-tool +comparison tests assess the correct implementation of third-party software. +The testing suite is incorporated into a continuous integration framework, which assesses the continuity of the implementation along the development life and ensures that code changes and additions do not break existing functionalities. -The problem has been traditionally confused by the need of _transforming_ or -mapping one image (generally referred to as _moving_) into another that serves -as reference, with the goal of _fusing_ the information from both. An example of -image fusion application would be the alignment of functional data from one -individual's brain to the same individual's corresponding anatomical MRI scan -for visualization. Therefore, "applying a transform" entails two operations: -first, transforming the coordinates of the samples in the reference image $R$ to -find their mapping $\vec{x}'$ on $M$ via $T\{\cdot\}$, and second, an -interpolation step as $\vec{x}'$ will likely fall off-the-grid of the moving -image $M$. These two operations are confusing because, while the spatial -transformation projects from $R$ to $M$, the data flows in reversed way after the -interpolation of the values of $M$ at the mapped coordinates $\vec{x}'$. +# Examples # References