dkauf42/tablequery

Query table variables based on multiple matching criteria or using ranges of values

%TABLEQUERY Query from a matlab DataTable, using match & range criteria
% TABLEQUERY operates as a logical AND query to a table, i.e.
% extracts the part of DataTable that satisfies ALL query criteria
% TABLEQUERY extracts data from a table based on combinations of
% Variable Names + Query Criteria
% TABLEQUERY supports two methods of specifying query criteria:
% 1) Using separate input cell arrays for 'match' and/or 'range'
% w/cells consisting of paired {VarName,QryCriteria,VN2,QC2,...}
% 2) Using an input structure with 'match' and/or 'range' fields
%
% SYNTAX
%
% TABLEQUERY(DataTable)
% TABLEQUERY(... 'match',matchCriteriaCell)
% TABLEQUERY(... 'range',rangeCriteriaCell)
% TABLEQUERY(... 'qryStruct',qryCriteriaStructure)
% TABLEQUERY(... 'varnameq',{'din','phy'})
% TABLEQUERY(... 'suppressoutput',false)
%
% INPUT (REQUIRED):
% - DataTable - The table from which to query a portion.
% Each var. column in DataTable has only one data type
% e.g. replace missing value chars w/NaN in numeric columns
%
% INPUT (OPTIONAL VARARGIN PARAMETER/VALUE PAIRS):
% - 'match' - a cell in the form:
% {'qryVarName', qryVarCriteria, 'qryVarName2', etc.}
% - 'range' - a cell in the form:
% {'qryVarName', qryVarCriteria, 'qryVarName2', etc.}
% NOTE: range is an INCLUSIVE range, & must contain two-
% element numeric vectors in a cell, such as
% {[ rangeMin rangeMax ]}
% - 'qryStruct' - an alternative method of specifying
% query criteria. A structure that contains two
% fields, each of which are structures themselves
% Default form: struct('match',struct(),'range',struct())
% NOTE: if match/range fields are empty then they are unused
% each criteria in the structure must be within a cell
% - 'varnameq' / default: {'all'}
% either - a char name of one of the table variables or
% - a cell containing multiple variable names or
% - a cell containing the string 'all'
% - 'suppressoutput' / default: false
% if set to true, then this function will display
% progress and matching in the MATLAB command window
%
% USAGE EXAMPLES:
% USAGE EXAMPLE 1:
% (using a 'qryStruct' parameter)
% >> varsToRetrieve = {'site','t','Concentration'}
% >> qCriteria.match.site = {'j171'}
% >> qCriteria.range.t = {[302.5 307]}
% >> qCriterua.range.z = {[100 150]}
%
% >> tablequery(DataTable, qCriteria, 'varnameq',varsToRetrieve)
%
% USAGE EXAMPLE 2:
% (using 'match' & 'range' parameters)
% >> Mqry = {'site', 'j171'}
% >> Rqry = {'time',[305 320], 'z',[100 150]}
%
% >> tablequery(DataTable, 'match', Mqry, 'range', Rqry);
%
% USAGE EXAMPLE 3:
% (using 'match' & 'range' parameters w/empty criteria)
% >> Mqry = {'time',[307.5 309.5], 'depth',40}
% >> Rqry = {'',''} % <<- signifies no criteria; could
% alternatively use {} or {'',[]'}
%
% >> tablequery(DataTable, 'match', Mqry, 'range', Rqry);
%
% MFILE: tableQuery.m
% MATLAB: 8.4.0.150421 (R2014b)
% AUTHOR: Daniel Edward Kaufman (USA)
% @ The Virginia Institute of Marine Science
% CONTACT: [e-mail]
%
% REVISIONS:
% - Added transfer of Data Table Units and Descriptions. (Apr, 2015)
% - Removed extraneous code and reordered inputs. (Mar, 2015)
% - Updated input options, increased speed and bug-fixes. (Feb, 2015)
% - Initial generation. (Jan, 2015)
%