Review timeseries

+nf/extract.m

@@ -1,9 +1,9 @@
-%% Extract a specific subset of data from a neurofield output struct.
+%% Extract a specific subset of data from a nftsim output struct.
 %
 % The subset can be specified in terms of: traces; times; and nodes.
 %
 % ARGUMENTS:
-% obj -- A neurofield output struct (a Matlab struct containing data
+% obj -- A nftsim output struct (a Matlab struct containing data
 % from a simulation).
 % traces -- A cell array or a comma separated string of the traces
 % you want to extract, e.g. 'Propagator.2.phi, Coupling.2.nu'.
@@ -35,7 +35,7 @@
  % If no nodes are provided, output all nodes
  if ~isstruct(obj) || ~isfield(obj, 'data')
  error(['nf:' mfilename ':BadArgument'], ...
- 'The first argument must be a neurofield output struct.');
+ 'The first argument must be a nftsim output struct.');
  end
 
  if nargin < 4 || isempty(nodes)

+nf/get_frequencies.m

@@ -2,20 +2,20 @@
 % Return corresponding grids of frequencies and positions
 %
 % ARGUMENTS:
-% data -- .
-% fs -- .
-% Lx -- .
-% Ly -- .
+% data -- an 1D or 3D array of size space points along x, space points along y, tim points, 
+% fs -- sampling temporal frequency in [Hz]
+% Lx -- physical size of the spatial domain along x in [m] 
+% Ly -- physical size of the spatial domain along y in [m]
 %
 % OUTPUT:
-% f -- .
-% Kx -- .
-% Ky -- .
-% x -- .
-% y -- .
-% df -- .
-% dk -- .
-% dx -- .
+% f -- vector of (positives) frequencies in [Hz]
+% Kx -- vector of angular wavenumbers in [rad/m]
+% Ky -- vector of angular wavenumbers in [rad/m]
+% x -- vector with spatial coordinates in [m]
+% y -- vector with spatial coordinates in [m]
+% df -- temporal frequency resolution in [Hz]
+% dk -- radial spatial frequency resolution in [rad/m]
+% dx -- spatial resolution in [m]
 %
 % REQUIRES:
 % -- <description>
@@ -38,16 +38,19 @@
  x = [];
  y = [];
 
+ % This is the single positive sided frequency vector
  if isvector(data)
- f = (0:(fs / length(data)):(fs / 2)).'; % This is the single sided frequency
+ f = (0:(fs / length(data)):(fs / 2)).'; 
  return
  end
 
- f = (0:(fs / size(data, 3)):(fs / 2)).'; % This is the single sided frequency
+ % This is the single positive sided frequency
+ f = (0:(fs / size(data, 3)):(fs / 2)).'; 
  df = fs / size(data, 3);
-
- Kx = 2*pi*(0:1/Lx:size(data, 1)/Lx/2); % This is the single sided frequency
- Ky = 2*pi*(0:1/Ly:size(data, 2)/Ly/2); % This is the single sided frequency
+
+ % Wavenumbers / single sided and positive
+ Kx = 2*pi*(0:1/Lx:size(data, 1)/Lx/2);
+ Ky = 2*pi*(0:1/Ly:size(data, 2)/Ly/2);
 
  if mod(size(data, 1), 2) % If there is NO nyquist frequency component
  Kx = [-Kx(end:-1:2) Kx];
@@ -60,13 +63,24 @@
  else
  Ky = [-Ky(end:-1:2) Ky(1:end-1)];
  end
+
  [Kx, Ky] = meshgrid(Kx, Ky);
+
+ % Smallest wavenumber - resolution in k-space (angular spatial frequency)
+ % This is assuming the spatial domain is square (Lx=Ly)
+
  dk = 2 * pi / Lx;
+
+ % dx and dy should be the same
+ dx = Lx / size(data, 1); % [m]
+ dy = Ly / size(data, 1); % [m]
+
+ % the stencil in NFTsim assumes the coordinates of a parcel of the discretized domain
+ % is at the centre of the parcel, thus the first coordinate is at (dx/2; dy/2) 
+
+ x = dx * (0:size(data, 1)) + dx/2;
+ y = dy * (0:size(data, 1)) + dx/2;
 
- dx = Lx / size(data, 1); % Metres per pixel
- x = dx * (0:size(data, 1)-1);
- dy = Ly / size(data, 1);
- y = dy * (0:size(data, 1)-1);
  [x, y] = meshgrid(x, y);
 
 end %function get_frequencies()

+nf/grid.m

@@ -8,7 +8,7 @@
 % output all nodes), or the number of nodes is not a perfect square..
 %
 % ARGUMENTS:
-% obj -- A neurofield output struct (a Matlab struct containing data
+% obj -- A nftsim output struct (a Matlab struct containing data
 % from a simulation).
 % trace -- A string with the name of the array to reshape. 
 %
@@ -35,7 +35,7 @@
 
  if output_nodes ~= obj.input_nodes 
  error(['nf:' mfilename ':IncompatibleOutput'], ...
- 'Output from NeuroField must be for all nodes')
+ 'Output from NFTsim must be for all nodes')
  end 
 
  data = nf.extract(obj, trace);
@@ -48,7 +48,7 @@
  longside_nodes = obj.longside_nodes;
  shortside_nodes = obj.input_nodes / obj.longside_nodes;
  end
- %Reshape to an array of (n,m,tpts)
+ %Reshape to an array of (nx,ny,tpts)
 
  %data = reshape(data, grid_edge, grid_edge, obj.npoints);
 

+nf/plot_timeseries.m

@@ -12,12 +12,14 @@
 % node_idx -- cell array with vectors of node indices, one per trace.
 % reref -- boolean, true: removes spatial average at each time-step,
 % this is equivalent to the "grand-average" often used in EEG.
+% rm_linear_trend -- boolean, true: remove any linear trend from data before
+% plotting. Disable to view non-stationary time-series.
 %
 % OUTPUT: (Generates a time-series figure for each trace.)
 % figure_handles -- cell array of figure handles.
 %
 % REQUIRES:
-% nf.extract() -- Extract a specific subset of data from a neurofield
+% nf.extract() -- Extract a specific subset of data from a nftsim
 % output struct.
 %
 % AUTHOR:
@@ -28,7 +30,7 @@
 %{
  %Either run a simulation:
  nf_obj = nf.run('./configs/eirs-corticothalamic.conf')
- %Or load some neurofield output data
+ %Or load some nftsim output data
  nf_obj = nf.read('./configs/eirs-corticothalamic.output')
 
  %Plot every fourth node for the trace 'Propagator.1.phi'.
@@ -38,7 +40,7 @@
  close([figure_handles{:}])
 %}
 
-function figure_handles = plot_timeseries(obj, traces, node_idx, reref)
+function figure_handles = plot_timeseries(obj, traces, node_idx, reref, rm_linear_trend)
  % Default to plotting all fields.
  if nargin < 2 || isempty(traces)
  traces = obj.fields;
@@ -54,6 +56,10 @@
  if nargin < 4
  reref = true;
  end
+ % Default to linear detrend of data before plot.
+ if nargin < 5
+ rm_linear_trend = true;
+ end
  % Get some size info about data
  num_figs = length(traces);
  time = obj.time;
@@ -63,15 +69,21 @@
  for nof=1:num_figs
  num_nodes = length(node_idx{nof});
  labels = cell(1, num_nodes);
+ node_data_index = nan(1, num_nodes);
  for k = 1:num_nodes
- labels{k} = num2str(node_idx{nof}(k)); 
+ labels{k} = num2str(node_idx{nof}(k));
+ node_data_index(k) = find(obj.nodes{nof} == node_idx{nof}(k));
  end %index labels
 
  figure_handles{nof} = figure;
  fig_title = [traces{nof}];
- % Get fata to plot
+ % Get data to plot
  data = nf.extract(obj, traces{nof});
- data = detrend(data);
+
+ % Remove any linear trend from individual time-series.
+ if rm_linear_trend
+ data = detrend(data);
+ end
 
  % Rescale data to the range [0, 1]
  data = data - min(data(:)); 
@@ -88,7 +100,7 @@
  separate_by = 0.33*(max(data(:)) - min(data(:)));
  nodes_by_timestepsize = repmat((1:num_nodes), [time_steps,1]);
 
- plot(time, data(:, node_idx{nof}) + separate_by*nodes_by_timestepsize, ...
+ plot(time, data(:, node_data_index) + separate_by*nodes_by_timestepsize, ...
  'color', [0.42, 0.42, 0.42]);
 
  title(fig_title, 'interpreter', 'none');

+nf/read.m

@@ -1,11 +1,11 @@
-%% Read a neurofield output file and return a neurofield output struct.
+%% Read a nftsim output file and return a nftsim output struct.
 %
 % ARGUMENTS:
-% fname -- The name of the neurofield output file to read (absolute
+% fname -- The name of the nftsim output file to read (absolute
 % or relative path).
 %
 % OUTPUT:
-% obj -- A neurofield output struct. A Matlab struct containing data
+% obj -- A nftsim output struct. A Matlab struct containing data
 % and parameters from a simulation.
 %
 % AUTHOR:
@@ -20,7 +20,11 @@
 function [obj] = read(fname)
 
  % Check that our input arg is actually a file.
- if ~exist(fname, 'file')
+ if endsWith(fname,'.conf')
+ error(['nf:' mfilename ':BadArgument'], ...
+ 'The file provided is a configuration file: "%s".', fname)
+ end
+ if ~exist(fname, 'file') 
  % Try appending .output to the name we were provided.
  if ~exist([fname, '.output'], 'file')
  error(['nf:' mfilename ':FileDoesNotExist'], ...
@@ -42,7 +46,7 @@
 
 
  while isempty(strfind(buffer, '======================='))
- % TODO: consider cleaning up this part.
+ % TODO: CLEAN UP - this part refers to EEGCODE.
  if ~isempty(strfind(buffer, 'Time |'))
  error(['nf:' mfilename ':OldStyleOutput'], ...
  'Did you try and open and old-style output file? Found a | that looked like a delimiter.')

+nf/report.m

@@ -1,7 +1,7 @@
-%% Given a neurofield output struct, print some information about it.
+%% Given a nftsim output struct, print some information about it.
 %
 % ARGUMENTS:
-% obj -- A neurofield output struct (a Matlab struct containing data
+% obj -- A nftsim output struct (a Matlab struct containing data
 % from a simulation).
 %
 % OUTPUT: Prints to terminal.
@@ -16,7 +16,7 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 function report(obj)
- fprintf(1, 'Output for: neurofield -i "%s"\n', obj.conf_file)
+ fprintf(1, 'Output for: nftsim -i "%s"\n', obj.conf_file)
  fprintf(1, 'Traces: ');
  for j = 1:length(obj.fields)
  fprintf(1, '%s ', obj.fields{j});

+nf/rfft.m

@@ -21,6 +21,7 @@
 % http://www.brain-dynamics.net/~chris_rennie/fourier.pdf
 %
 % AUTHOR:
+% Original: Chris Rennie circa 2000
 % Romesh Abeysuriya (2012-03-22).
 %
 % USAGE:
@@ -75,9 +76,10 @@
  P(2:(end - 1), :) = P(2:(end - 1), :) .* 2.0;
  end
 
+ % TODO: check normalizations
  % P now contains properly normalized spectral power
  %f = fs / 2 * linspace(0, 1, NFFT / 2 + 1)';
- f = 0:(fs / NFFT):(fs / 2); % I think this is more correct
+ f = 0:(fs / NFFT):(fs / 2); % I think this is more correct 
  P = mean(P, 2);
  P = P ./ f(2); % Divide by frequency bin size to get power density
 

+nf/run.m

@@ -1,38 +1,38 @@
-%% Function to run neurofield and return a neurofield output struct.
+%% Function to run nftsim and return a nftsim output struct.
 %
-% Provided a configuration file-name (fname.conf), run the neurofield
+% Provided a configuration file-name (fname.conf), run the nftsim
 % executable, generating an output file (fname.output). Optionally, if an
 % output argument is provided then, parse the output file and return a
-% neurofield output struct containing the simulation results.
+% nftsim output struct containing the simulation results.
 %
 %
 % ARGUMENTS:
 % fname -- Name of the configuration file, it can be with or without
 % the .conf extension.
 % time_stamp -- boolean flag to use a time_stamp YYYY-MM-DDTHHMMSS
 % in the output file name.
-% neurofield_path -- neurofield executable (full or relative path).
+% nftsim_path -- nftsim executable (full or relative path).
 %
 % OUTPUT: Writes a .output file in the same location as the .conf file.
-% obj -- A neurofield output struct (a Matlab struct containing
+% obj -- A nftsim output struct (a Matlab struct containing
 % data from a simulation).
 %
 % REQUIRES:
-% neurofield -- The neurofield executable, must be in your path.
-% nf.read -- Read a neurofield output file and return a neurofield
+% nftsim -- The nftsim executable, must be in your path.
+% nf.read -- Read a nftsim output file and return a nftsim
 % output struct.
 %
 % AUTHOR:
 % Romesh Abeysuriya (2012-03-22).
 %
 % USAGE:
 %{
- %At a matlab command promt, from neurofield's main directory:
+ %At a matlab command promt, from nftsim's main directory:
  nf_obj = nf.run('./configs/eirs-corticothalamic.conf')
 %}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-function obj = run(fname, time_stamp, neurofield_path)
+function obj = run(fname, time_stamp, nftsim_path)
  %
  tic;
  fname = strrep(fname, '.conf', ''); %Strip any .conf suffix.
@@ -41,39 +41,39 @@
  if nargin < 2
  time_stamp = false;
  end
- % If we were not provided a path to neurofield, try to determine one.
- if nargin < 3 || isempty(neurofield_path)
+ % If we were not provided a path to nftsim, try to determine one.
+ if nargin < 3 || isempty(nftsim_path)
  % Check typical locations, the first path that exists will be selected.
- locations = {'neurofield', ...
- './bin/neurofield', ...
- './neurofield/bin/neurofield', ...
- 'neurofield.exe'};
+ locations = {'nftsim', ...
+ './bin/nftsim', ...
+ './nftsim/bin/nftsim', ...
+ 'nftsim.exe'};
  selected_path = find(cellfun(@(name) exist(name, 'file')==2, locations), 1, 'first');
  if ~isempty(selected_path)
- neurofield_path = locations{selected_path};
+ nftsim_path = locations{selected_path};
  else
  error(['nf:' mfilename ':BadPath'], ...
- 'neurofield not found. Either change into the neurofield base directory or make a symlink to neurofield in the current directory.');
+ 'nftsim not found. Either change into the nftsim base directory or make a symlink to nftsim in the current directory.');
  end
  % If we were provided a path, check that it is valid.
- elseif ~exist(neurofield_path, 'file')
+ elseif ~exist(nftsim_path, 'file')
  error(['nf:' mfilename ':BadPath'], ...
- 'The neurofield_path you provided is incorrect:"%s".',neurofield_path);
+ 'The nftsim_path you provided is incorrect:"%s".',nftsim_path);
  end
 
  if ~time_stamp
- neurofield_cmd = sprintf('%s -i %s.conf -o %s.output', neurofield_path, fname, fname);
+ nftsim_cmd = sprintf('%s -i %s.conf -o %s.output', nftsim_path, fname, fname);
  else
- neurofield_cmd = sprintf('%s -i %s.conf -t', neurofield_path, fname);
+ nftsim_cmd = sprintf('%s -i %s.conf -t', nftsim_path, fname);
  end
  fprintf('INFO: Executing command:\n') 
- fprintf('%s\n', neurofield_cmd);
- [status, cmdout] = system(neurofield_cmd);
+ fprintf('%s\n', nftsim_cmd);
+ [status, cmdout] = system(nftsim_cmd);
 
  string(cmdout)
  if status ~= 0
- error(['nf:' mfilename ':NeurofieldError'], ...
- 'An error occurred while running neurofield!');
+ error(['nf:' mfilename ':NFTsimError'], ...
+ 'An error occurred while running nftsim!');
  end
 
  fprintf(1, 'INFO: tic-toc: Took about %.3f seconds\n', toc);