DBGetValues

DBGetValues - Group values for all variables that match given criteria.

  Concatenate individual values for all variables matching the optional query.
  Values must be scalars, vectors or matrices. Concatenation can be performed
  horizontally or vertically. Matrices can also be concatenated along the
  third dimension (z). By default, values of size MxN are concatenated
  vertically if M<=N, or horizontally otherwise.

  USAGE

    [data,eid,name] = DBGetValues(query,direction)

    query          optional list query (WHERE clause; see Example)
    direction      optional concatenation direction ('h', 'v' or 'z')

  OUTPUT

    data           concatenation of individual values
    eid            experiment ID (identifier string)
    name           descriptive name (identifier string)

  EXAMPLE

    In this example, place cells were recorded on successive days while the
    animal explored a maze, then during sleep. Firing fields were stored in a
    database using eids like '20120213-Maze-(1,2)' (where 1,2 corresponds to
    tetrode 1, cluster 2) and named 'FiringFields'. Mean firing rates during
    sleep were named 'MeanRate'.

    Get all firing fields (for details on query syntax, see an SQL manual):

    [fields,eid1] = DBGetValues('eid like "%Maze%" and name="FiringField"');

    Get all firing rates during sleep:

    [rates,eid2] = DBGetValues('eid like "%Sleep%" and name="MeanRate"');

  SEE

    See also DBMatchValues, DBGetVariables, DBAddVariable, DBGetFigures.

0001 function [data,eid,name] = DBGetValues(query,direction)
0002 
0003 %DBGetValues - Group values for all variables that match given criteria.
0004 %
0005 %  Concatenate individual values for all variables matching the optional query.
0006 %  Values must be scalars, vectors or matrices. Concatenation can be performed
0007 %  horizontally or vertically. Matrices can also be concatenated along the
0008 %  third dimension (z). By default, values of size MxN are concatenated
0009 %  vertically if M<=N, or horizontally otherwise.
0010 %
0011 %  USAGE
0012 %
0013 %    [data,eid,name] = DBGetValues(query,direction)
0014 %
0015 %    query          optional list query (WHERE clause; see Example)
0016 %    direction      optional concatenation direction ('h', 'v' or 'z')
0017 %
0018 %  OUTPUT
0019 %
0020 %    data           concatenation of individual values
0021 %    eid            experiment ID (identifier string)
0022 %    name           descriptive name (identifier string)
0023 %
0024 %  EXAMPLE
0025 %
0026 %    In this example, place cells were recorded on successive days while the
0027 %    animal explored a maze, then during sleep. Firing fields were stored in a
0028 %    database using eids like '20120213-Maze-(1,2)' (where 1,2 corresponds to
0029 %    tetrode 1, cluster 2) and named 'FiringFields'. Mean firing rates during
0030 %    sleep were named 'MeanRate'.
0031 %
0032 %    Get all firing fields (for details on query syntax, see an SQL manual):
0033 %
0034 %    [fields,eid1] = DBGetValues('eid like "%Maze%" and name="FiringField"');
0035 %
0036 %    Get all firing rates during sleep:
0037 %
0038 %    [rates,eid2] = DBGetValues('eid like "%Sleep%" and name="MeanRate"');
0039 %
0040 %  SEE
0041 %
0042 %    See also DBMatchValues, DBGetVariables, DBAddVariable, DBGetFigures.
0043 %
0044 
0045 % Copyright (C) 2007-2013 by Michaël Zugaro
0046 %
0047 % This program is free software; you can redistribute it and/or modify
0048 % it under the terms of the GNU General Public License as published by
0049 % the Free Software Foundation; either version 3 of the License, or
0050 % (at your option) any later version.
0051 
0052 % Make sure MyM is installed and functional
0053 CheckMyM;
0054 
0055 data = [];
0056 eid = {};
0057 name = {};
0058 
0059 % Parameters
0060 if nargin < 1,
0061     query = '';
0062     direction = [];
0063 elseif nargin == 1,
0064     if strcmp(lower(query),'h'),
0065         query = '';
0066         direction = 'h';
0067     elseif strcmp(lower(query),'v'),
0068         query = '';
0069         direction = 'v';
0070     elseif strcmp(lower(query),'z'),
0071         query = '';
0072         direction = 'z';
0073     else
0074         direction = [];
0075     end
0076 end
0077 
0078 % Query database
0079 results = DBGetVariables(query,'output','full');
0080 if isempty(results.v), return; end
0081 eid = results.eid;
0082 name = results.name;
0083 
0084 first = results.v{1};
0085 if ~isnumeric(first),
0086     error('Values are not numerical and cannot be concatenated (type ''help <a href="matlab:help DBGetValues">DBGetValues</a>'' for details).');
0087 end
0088 
0089 % Automatic concatenation direction
0090 if isempty(direction),
0091     if size(first,1) <= size(first,2),
0092         direction = 'v';
0093     else
0094         direction = 'h';
0095     end
0096 end
0097 
0098 % Concatenation
0099 
0100 % Determine sizes of retrieved values (arrays)
0101 sizes = cellfun(@size,results.v,'UniformOutput',false);
0102 % Make sure they all have the same number of dimensions
0103 nDims = cellfun(@length,sizes);
0104 if any(nDims~=nDims(1)),
0105     error('All values should have the same number of dimensions (type ''help <a href="matlab:help DBGetValues">DBGetValues</a>'' for details).');
0106 end
0107 % Determine 'circumscribed' array size
0108 s = max(unique(vertcat(sizes{:}),'rows'),[],1);
0109 % Extend all arrays
0110 results.v = cellfun(@(x) ExtendArray(x,s),results.v,'uniformoutput',false);
0111 % Concatenate in the appropriate direction
0112 if strcmp(direction,'v'),
0113     data = vertcat(results.v{:});
0114 elseif strcmp(direction,'h'),
0115     data = [results.v{:}];
0116 else
0117     data = cat(3,results.v{:});
0118 end