brainhack-report-formatted.tex

%% BioMed_Central_Tex_Template_v1.06
%%                                      %
%  bmc_article.tex            ver: 1.06 %
%                                       %

%%IMPORTANT: do not delete the first line of this template
%%It must be present to enable the BMC Submission system to
%%recognise this template!!

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                     %%
%%  LaTeX template for BioMed Central  %%
%%     journal article submissions     %%
%%                                     %%
%%          <8 June 2012>              %%
%%                                     %%
%%                                     %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                                                 %%
%% For instructions on how to fill out this Tex template           %%
%% document please refer to Readme.html and the instructions for   %%
%% authors page on the biomed central website                      %%
%% http://www.biomedcentral.com/info/authors/                      %%
%%                                                                 %%
%% Please do not use \input{...} to include other tex files.       %%
%% Submit your LaTeX manuscript as one .tex document.              %%
%%                                                                 %%
%% All additional figures and files should be attached             %%
%% separately and not embedded in the \TeX\ document itself.       %%
%%                                                                 %%
%% BioMed Central currently use the MikTex distribution of         %%
%% TeX for Windows) of TeX and LaTeX.  This is available from      %%
%% http://www.miktex.org                                           %%
%%                                                                 %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% additional documentclass options:
%  [doublespacing]
%  [linenumbers]   - put the line numbers on margins

%%% loading packages, author definitions

\documentclass[twocolumn]{bmcart}% uncomment this for twocolumn layout and comment line below
%\documentclass{bmcart}

%%% Load packages
\usepackage{amsthm,amsmath}
\usepackage{siunitx}
\usepackage{mfirstuc}
%\RequirePackage{natbib}
\usepackage[colorinlistoftodos]{todonotes}
\RequirePackage{hyperref}
\usepackage[utf8]{inputenc} %unicode support
%\usepackage[applemac]{inputenc} %applemac support if unicode package fails
%\usepackage[latin1]{inputenc} %UNIX support if unicode package fails
\usepackage[htt]{hyphenat}

\usepackage{array}
\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                             %%
%%  If you wish to display your graphics for   %%
%%  your own use using includegraphic or       %%
%%  includegraphics, then comment out the      %%
%%  following two lines of code.               %%
%%  NB: These line *must* be included when     %%
%%  submitting to BMC.                         %%
%%  All figure files must be submitted as      %%
%%  separate graphics through the BMC          %%
%%  submission process, not included in the    %%
%%  submitted article.                         %%
%%                                             %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%\def\includegraphic{}
%\def\includegraphics{}

%%% Put your definitions there:
\startlocaldefs
\endlocaldefs


%%% Begin ...
\begin{document}

%%% Start of article front matter
\begin{frontmatter}

\begin{fmbox}
\dochead{Report from 2015 Brainhack Americas (MX)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                          %%
%% Enter the title of your article here     %%
%%                                          %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\title{The Neuroimaging Data Model (NIDM) API}
\vskip2ex
\projectURL{Project URL: \url{http://nidm-api.readthedocs.org}}

\author[
addressref={aff1},
corref={aff1},
email={vsochat@stanford.edu}
]{\inits{VS} \fnm{Vanessa} \snm{Sochat}}
\author[
addressref={aff2,aff3},
%
email={nolan.nichols@gmail.com}
]{\inits{NN} \fnm{B Nolan} \snm{Nichols}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                          %%
%% Enter the authors' addresses here        %%
%%                                          %%
%% Repeat \address commands as much as      %%
%% required.                                %%
%%                                          %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\address[id=aff1]{%
  \orgname{Program in Biomedical Informatics, Stanford University},
  \city{Stanford},
  \street{1265 Welch Road},
  \postcode{94306},
  \postcode{California},
  \cny{USA}
}
\address[id=aff2]{%
  \orgname{SRI International},
  \city{Menlo Park},
  \street{333 Ravenswood Ave},
  \postcode{94025},
  \postcode{California},
  \cny{USA}
}
\address[id=aff3]{%
  \orgname{Department of Psychiatry and Behavioral Sciences, Stanford University},
  \city{Stanford},
  \street{1265 Welch Road},
  \postcode{94306},
  \postcode{California},
  \cny{USA}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                          %%
%% Enter short notes here                   %%
%%                                          %%
%% Short notes will be after addresses      %%
%% on first page.                           %%
%%                                          %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{artnotes}
\end{artnotes}

%\end{fmbox}% comment this for two column layout

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                          %%
%% The Abstract begins here                 %%
%%                                          %%
%% Please refer to the Instructions for     %%
%% authors on http://www.biomedcentral.com  %%
%% and include the section headings         %%
%% accordingly for your article type.       %%
%%                                          %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%\begin{abstractbox}

%\begin{abstract} % abstract
	
%Blank Abstract

%\end{abstract}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                          %%
%% The keywords begin here                  %%
%%                                          %%
%% Put each keyword in separate \kwd{}.     %%
%%                                          %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%\vskip1ex

%\projectURL{\url{http://github.com/ccraddock/afni}}
%\projectURL{http://github.com/ccraddock/afni}

% MSC classifications codes, if any
%\begin{keyword}[class=AMS]
%\kwd[Primary ]{}
%\kwd{}
%\kwd[; secondary ]
%\end{keyword}

%\end{abstractbox}
%
\end{fmbox}% uncomment this for twcolumn layout

\end{frontmatter}

%{\sffamily\bfseries\fontsize{10}{12}\selectfont Project URL: \url{http://github.com/ccraddock/afni}}

%%% Import the body from pandoc formatted text
\section{Introduction}\label{introduction}
Sharing of brain research can be aided by the Neuroimaging Data Model (NIDM) \cite{Keator2013-rc,noauthor_undated-jz,noauthor_undated-pr}. NIDM provides a community-based framework for developing data exchange standards that describe the primary observations, computational workflows, and derived results of neuroimaging studies \cite{noauthor_undated-jv}. For example, a researcher sharing a statistical brain map could include with the brain map a data structure, ``NIDM Results,'' that contains complete information about the parameters used to generate the result, significant coordinate points in the brain map paired with test criteria, along with other meta-data exported from the software that generated it. This additional information cannot be represented in the brain map itself, and provides a complete description of the result that can be compared to other results, or used to reproduce it. 

While work is underway to integrate NIDM into the software used by the human brain mapping community, only low-level tools are currently available to access and query NIDM documents that rely on a graph-based representation called the Resource Description Framework (RDF) \cite{noauthor_undated-hj}. Further, technologies like RDF and the corresponding query language, SPARQL \cite{noauthor_undated-cp}, pose a steep learning curve for users of standard Web development workflows. With the recent migration of tools for neuroimaging meta analysis \cite{Yarkoni2011-rg,Reid2015-gt}, sharing \cite{Crawford2016-zl,Landis2016-wo,Book2016-ro,Herrick2016-bw,Hodge2016-ht,Jernigan2016-dz,Kini2016-sg,Wang2016-nd,Gorgolewski2015-sf}, and visualization \cite{Gutman2014-hz,Gao2015-pz,noauthor_undated-ca} into the Web browser, Web developers will be incentivized by the ability to easily integrate brain data into Web applications using familiar languages and formats. The goal of this Brainhack project was to develop infrastructure to serve NIDM documents and queries using an API with a syntax that allows for the easy development of Web-based tools for the neuroimaging community. These tools are publicly available on Github (RRID:SCR\_002630) at \href{https://github.com/incf-nidash/nidm-api}{https://github.com/incf-nidash/nidm-api} and \href{https://github.com/incf-nidash/nidm-query}{https://github.com/incf-nidash/nidm-query} for the API and queries, respectfully, along with complete documentation at \href{https://nidm-api.readthedocs.org}{https://nidm-api.readthedocs.org}.

\section{Approach}\label{approach}
The \texttt{nidm-api} \cite{noauthor_undated-hq} is a RESTful API and Web application that provides a simplified view of NIDM documents using formats (e.g., JavaScript Object Notation (JSON) \cite{Wikipedia_contributors2015-on,noauthor_undated-tz}) that are accessible to Web developers and researchers without expertise in Linked Open Data (LOD) technologies. This project includes two components. First, the \href{https://github.com/incf-nidash/nidm-api}{\texttt{nidm-api}} is a Python-based executable that works both as a command-line tool to run queries over NIDM documents, as well as to serve a RESTful API to allow a local or cloud-based server to execute queries on documents accessible by URL. Second, \href{https://github.com/incf-nidash/nidm-query}{\texttt{nidm-query}} is a repository of SPARQL queries that the \texttt{nidm-api} application dynamically downloads, validates, and serves upon starting the application. This strategy means that NIDM developers can collaboratively construct SPARQL queries without requiring Web developers to gain expertise in LOD technology. The \texttt{nidm-api}, along with serving the queries, also provides a graphical Web interfaces to contribute new queries to the shared repository. Because the \texttt{nidm-api} is a Python Flask \cite{noauthor_undated-ia} application, it can be used both as an executable to serve the API \cite{noauthor_undated-ii}, and contains a set of functions that can be integrated into other Python-based frameworks \cite{noauthor_undated-ej} or cloud platforms that provide Python accessibility \cite{noauthor_undated-jw,Google_undated-aj}. A schematic of the tool is provided in (Figure \ref{fig:01})  \newline \newline

\begin{figure}[h!]
\begin{center}
\includegraphics[width=7cm]{img/figure1}
\end{center}
 \textbf{\refstepcounter{figure}\label{fig:01}Figure \arabic{figure}.}{The nidm-api (nidm) provides programmatic access to queries in the nidm-query repository, including RESTful access (left panel) and access from python applications (right panel).}
\end{figure}


\section{Results}\label{results}
\subparagraph{\texorpdfstring{\texttt{Using the API}:}{:}}\label{section}
Installation produces an executable, “nidm” that downloads, validates, and provides a summary of available queries in the \texttt{nidm-query} repository. A query can be further investigated by selecting its unique identifier: \newline

\textbf{http://localhost:8088/api/7950f524-90e8-4d54-ad6d-7b22af2e895d}\newline

and can then be executed in a RESTful fashion by including a variable to point to a local path or URL of a NIDM document:\newline

\textbf{http://localhost:8088/api/query/7950f524-90e 8-4d54-ad6d-7b22af2e895d?ttl=/home/nidm.ttl}\newline

The API then runs the query over the document, and returns the result to the user in JSON. The same functionality can be achieved on the \href{http://nidm-api.readthedocs.org/en/latest/getting-started.html#integration-into-python}{command line}, supporting direct integration into server-based Python applications.\newline

\subparagraph{\texorpdfstring{\texttt{Generating new queries}:}{:}}\label{section}
Researchers familiar with LOD can run the application in the same fashion, and go to a URL in their local browser:\newline

\textbf{http://localhost:8088/query/new}\newline

which reveals \href{http://nidm-api.readthedocs.org/en/latest/development.html#web-query-generator}{an interface} to generate new queries. The web interface asks for a set of \href{http://nidm-api.readthedocs.org/en/latest/development.html#fields}{variables} that are necessary for the \texttt{nidm-api} to serve the query. The query can be previewed, and then downloaded as a JSON object that can be submitted to the \texttt{nidm-query} repository and added to the application.\newline

\subparagraph{\texorpdfstring{\texttt{Applications using NIDM}:}{:}}\label{section}
As an example of the type of Web applications that can be built with the NIDM API, the NIDM Results object model \cite{noauthor_undated-if} was recently integrated into the \href{http://www.neurovault.org}{NeuroVault} database, meaning that neuroimaging researchers can export results pertaining to statistical brain maps from common software \cite{Jenkinson2012-pr} into NeuroVault. A \href{https://github.com/vsoch/nidmviewer}{nidm-viewer} (\href{https://github.com/vsoch/nidmviewer}{https://github.com/vsoch/nidmviewer}) that runs queries over the nidm-results can then parse the coordinates and statistical parameters associated with significant locations of activations to be rendered in a table alongside a visualization of the brain map itself (Figure \ref{fig:02} and \href{http://neurovault.org/collections/877/fsl_course_av.nidm}{example}). The raw data and parameters of the analysis are thus immediately available for sharing and publication, programatically accessible, and viewed from any web browser. 

\begin{figure}[h!]
\begin{center}
\includegraphics[width=7cm]{img/figure2}
\end{center}
 \textbf{\refstepcounter{figure}\label{fig:02}Figure \arabic{figure}.}{The nidm-viewer in the NeuroVault database queries NIDM Results objects to generate an interactive table and statistical brain map.}
\end{figure}

\section{Conclusions}\label{conclusions}

By providing tools to integrate the NIDM standard into modern web technology, NIDM can be more easily deployed into applications to empower neuroimaging researchers to explore and synthesize results, workflows, and experiments. This application will be extended to return more modern and desired outputs such as images and interactive graphs \cite{noauthor_undated-fs}, and additional functionality will be added as the NIDM experiment, workflows, and results standards are further developed. The software and queries are both \href{https://github.com/incf-nidash}{publicly available} and open to contributions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                                          %%
%% Backmatter begins here                   %%
%%                                          %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{backmatter}

\section*{Availability of Supporting Data}
More information about this project can be found at: \url{http://nidm-api.readthedocs.org}. Further data and files supporting this project are hosted in the \emph{INCF NIDASH} repositories https://github.com/incf-nidash/nidm-api and https://github.com/incf-nidash/nidm-query.

\section*{Competing interests}
None

\section*{Author's contributions}
VS and NN wrote the software and wrote the report.

\section*{Acknowledgements}
The authors would like to thank the INCF Neuroimaging Data Sharing Task Force, organizers and attendees of Brainhack MX, along with David Keator for helpful edits to the manuscript. VS is supported by a William R. Hewlett Stanford Graduate Fellowship and a National Science Foundation Fellowship. NN is supported by NIH NIAAA and OD (NCANDA Data Analysis Component, NIH 1 U01 AA021697; BD2K Supplement, NIH 1 U01 AA021697-04S1).
  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%                  The Bibliography                       %%
%%                                                         %%
%%  Bmc_mathpys.bst  will be used to                       %%
%%  create a .BBL file for submission.                     %%
%%  After submission of the .TEX file,                     %%
%%  you will be prompted to submit your .BBL file.         %%
%%                                                         %%
%%                                                         %%
%%  Note that the displayed Bibliography will not          %%
%%  necessarily be rendered by Latex exactly as specified  %%
%%  in the online Instructions for Authors.                %%
%%                                                         %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% if your bibliography is in bibtex format, use those commands:
\bibliographystyle{bmc-mathphys} % Style BST file
\bibliography{brainhack-report} % Bibliography file (usually '*.bib' )

\end{backmatter}
\end{document}