Permalink
Browse files

Adding the BrainVoyager tools supplied to Alex Ahmed to the contrib/i…

…o directory.
  • Loading branch information...
Wildcarde committed Sep 21, 2012
1 parent bb4de22 commit d6ffbc2fa8a1d392ed41afafa220630908db7306
Showing with 302 additions and 0 deletions.
  1. +28 −0 contrib/io/BV/README.txt
  2. +63 −0 contrib/io/BV/importVTC.m
  3. +70 −0 contrib/io/BV/load_bv_mask-AA.m
  4. +141 −0 contrib/io/BV/load_bv_pattern-AA.m
@@ -0,0 +1,28 @@
This set of tools is provided by Alex Ahmed (alex.ahmed AT yale DOT edu)
of Yale University for the purposes of importing Brainvoyager data into
Matlab/MVPA.

To use this package you will need to have a copy of the NeuroElf I/O
functions (http://neuroelf.net/)in your Matlab PATH because it is used
to import the actual BV data.

The package consists of modified versions of load_afni_pattern and mask
repurposed to load brainvoyager data and a helper function that may be
useful as a referrence for importing VTC files, it however appears to be
lab workflow specific so YMMV. The primary new tools are named
load_bv_mask-AA and _pattern-AA. To enable these functions you will need
to edit your 'mvpa_add_paths' to uncomment the line
"%myaddpath('contrib/io/BV');" to enable these functions.

As this is an external contribution, it has the same level of support as
other contributed files. Namely that it recieves as much or as little
support as the original author is willing to provide.

In addition to these scripts you will need to manually create a
regressor table in the format expected by MVPA and save it as a .mat
file for use with your data. This is due to there being no readily
available way to import Brainvoyager PRT protocol files.

-Garrett McGrath
Sysadmin Princeton Neuroscience Institute
gmcgrath AT princeton DOT edu
@@ -0,0 +1,63 @@
clear all

% Author: Alex Ahmed (alex.ahmed AT yale DOT edu)

% License:
%=====================================================================
%
% This is part of the Princeton MVPA toolbox, released under
% the GPL. See http://www.csbmb.princeton.edu/mvpa for more
% information.
%
% The Princeton MVPA toolbox is available free and
% unsupported to those who might find it useful. We do not
% take any responsibility whatsoever for any problems that
% you have related to the use of the MVPA toolbox.
%
% ======================================================================

%set data_dir equal to the path to your data directory
data_dir = '';
cd(data_dir)

%find all the files
files = dir(fullfile(data_dir));
numfiles = size(files,1);
subjects = {};
num_subjects = 1;

%Starts at 3 because 1 and 2 are "." and ".."
for n = 3:numfiles

%this section is specific to our experiments and was made to find only
%the directories that hold subject data. If all the folders in your
%data directory correspond to subjects, you can remove this section and
%simply let the array "subjects" be equal to all the folders in the
%directory
if files(n).isdir == 1
if strcmp(files(n).name(1:2),'AC') || strcmp(files(n).name(1:2),'CC')
subjects{num_subjects} = files(n).name;
num_subjects = num_subjects+1;
end
end

end

%import VTC data of each subject. Change x to be a range of the folders
%that correspond to subjects. I ran into memory errors while doing this,
%even while using "clear" to remove the present data after saving,
%so I had to do it in parts (hence why it only goes from 41 to 44 here)

%This creates a series of Subject1.mat...Subject"x".mat files that are used as input for load_bv_pattern
for x = 41:44
cd(subjects{x})
vtcname = dir('*vtc');
vtc_obj = xff(vtcname.name);

vtc_data = vtc_obj.VTCData;

save(['C:\Documents and Settings\pelphreylab\My Documents\MATLAB\mvpa\VTC Data\Subject' num2str(x) '.mat'],'vtc_data');
clear vtc_obj
clear vtc_data
cd ..
end
@@ -0,0 +1,70 @@
function [subj] = load_bv_mask(subj,new_maskname,filename,varargin)

% Loads an AFNI dataset into the subj structure as a mask
%
% [SUBJ] = LOAD_BV_MASK-AA(SUBJ,NEW_MASKNAME,FILENAME,...)

% Author: Alex Ahmed (alex.ahmed AT yale DOT edu)

% License:
%=====================================================================
%
% This is part of the Princeton MVPA toolbox, released under
% the GPL. See http://www.csbmb.princeton.edu/mvpa for more
% information.
%
% The Princeton MVPA toolbox is available free and
% unsupported to those who might find it useful. We do not
% take any responsibility whatsoever for any problems that
% you have related to the use of the MVPA toolbox.
%
% ======================================================================

% To load a mask named "filename.msk" from Brainvoyager, use the following NeuroElf command:
% maskObject = xff('filename.msk');
% mask = maskObject.Mask;
%
% Use this variable as your "filename" input for this script.


defaults.sub_brik = [];
defaults.logical = false;
defaults.filter_by = [];
args = propval(varargin,defaults);

% Initialize the new mask
subj = init_object(subj,'mask',new_maskname);

V = filename;

if isempty(find(V,1))
error('There were no voxels active in the %s mask',filename);
end

% Does this consist of solely ones and zeros?
if length(find(V)) ~= (length(find(V==0))+length(find(V==1)))
fprintf('Setting all non-zero values in the mask to one');
V(find(V)) = 1;
end

if args.logical
V = logical(V);
end

% Store the data in the new mask structure
subj = set_mat(subj,'mask',new_maskname,V);

% Add the AFNI header to the patterns
hist_str = sprintf('Mask ''%s'' created by load_afni_pattern',new_maskname);
subj = add_history(subj,'mask',new_maskname,hist_str,true);

% Add information to the new mask's header, for future reference
subj = set_objsubfield(subj,'mask',new_maskname,'header', ...
'ignore_absence',true);
subj = set_objsubfield(subj,'mask',new_maskname,'header', ...
'ignore_absence',true);

% Record how this mask was created
created.function = 'load_bv_mask';
subj = add_created(subj,'mask',new_maskname,created);

@@ -0,0 +1,141 @@
function [subj] = load_bv_pattern(subj,new_patname,maskname,filenames,varargin)

% Loads an BrainVoyager dataset into a subject structure
%
% [SUBJ] = LOAD_BV_PATTERN-AA(SUBJ,NEW_PATNAME,MASKNAME,FILENAMES,...)
%
% Adds the following objects:
% - pattern object called NEW_PATNAME masked by MASKNAME
%
% NEW_PATNAME is the name of the pattern to be created
%
% MASKNAME is an existing boolean mask in the same reference space
% that filters which voxels get loaded in. It should
%
% All patterns need a 'masked_by' mask to be associated with. The mask
% contains information about where the voxels are in the brain, and
% allows two patterns with different subsets of voxels from the same
% reference space to be compared
%
%
% FILENAMES is a cell array of strings, of BRIK filenames to load
% in. Just the stem, not the extension. If FILENAMES is a string,
% it will automatically get turned into a single-cell array for you.

% Author: Alex Ahmed (alex.ahmed AT yale DOT edu)

% License:
%=====================================================================
%
% This is part of the Princeton MVPA toolbox, released under
% the GPL. See http://www.csbmb.princeton.edu/mvpa for more
% information.
%
% The Princeton MVPA toolbox is available free and
% unsupported to those who might find it useful. We do not
% take any responsibility whatsoever for any problems that
% you have related to the use of the MVPA toolbox.
%
% ======================================================================

% Load the mask
maskvol = get_mat(subj,'mask',maskname);
mDims = size(maskvol);
mask = find(maskvol);

% check mask isn't empty
if isempty(mask)
error('Empty mask passed to load_bv_pattern()');
end

% Initialize the data structure
subj = init_object(subj,'pattern',new_patname);

if ischar(filenames)
filenames = {filenames};
end

% Determine the size of the incoming data
for i=1:length(filenames)
cur_filename = filenames{i};

cur_mat = load(cur_filename);
cur_dat = cur_mat.vtc_data;
cur_size = size(cur_dat);
bDims(i,:)= cur_size(2:4);
bLen(i) = cur_size(1);

end
clear cur_mat
clear cur_dat

% Initialize the data structure
tmp_data = zeros(length(mask),sum(bLen));

nFiles = length(filenames);

disp( sprintf('Starting to load BV pattern from %i files',nFiles) );

for h = 1:nFiles
fprintf('\t%i',h);

%filenames should be strings of names of .mat files created from data
%imported via NeuroElf, and saved using the save() function
cur_filename = filenames{h};
Vdata_mat = load(cur_filename);
Vdata_dat = Vdata_mat.vtc_data;

% Ensure that the mask dimensions match the data
vDims = size(Vdata_dat);
if any(vDims(2:4) ~= mDims(1:3))
error('Mask dimensions do not match data');
end

% Reshape the data to be Voxels X Time
% edited by Matt on 3/24/06 to allow MVPA to read 1-timepoint patterns
% from BRIK
if length(vDims) == 3
vDims = [vDims 1];
end

%This part has been changed to work with the way VTC files are imported
%by NeuroElf (time by X by Y by Z)
Vdata_dat = reshape(Vdata_dat,prod(vDims(2:4)), vDims(1));

% Apply the mask, and append to the matrix

%the current TRs
curTRs = sum(bLen(1:h-1))+1;
curTRs = (curTRs:curTRs+bLen(h)-1);

%write the data for each TR separately
%"mask" contains non-zero indices; write only non-zero indices to
%tmp_data
tmp_data(:,curTRs) = Vdata_dat(mask,:);

end % for h

disp(' ');

% Store the data in the pattern structure
subj = set_mat(subj,'pattern',new_patname,tmp_data);

% Set the masked_by field in the pattern
subj = set_objfield(subj,'pattern',new_patname,'masked_by',maskname);

% Add the history to the pattern
hist_str = sprintf('Pattern ''%s'' created by load_bv_pattern',new_patname);
subj = add_history(subj,'pattern',new_patname,hist_str,true);

% Add information to the new pattern's header, for future reference
subj = set_objsubfield(subj,'pattern',new_patname,'header', ...
'ignore_absence',true);
subj = set_objsubfield(subj,'pattern',new_patname,'header', ...
'ignore_absence',true);

% This object was conceived under a tree. Store that information in
% the SUBJ structure
created.function = 'load_bv_pattern';
subj = add_created(subj,'pattern',new_patname,created);


0 comments on commit d6ffbc2

Please sign in to comment.