dkauf42/tablequery
%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: dkauf42@gmail.com
%
% 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)
%
Cite As
Dan K (2024). dkauf42/tablequery (https://github.com/dkauf42/tablequery), GitHub. Retrieved .
MATLAB Release Compatibility
Platform Compatibility
Windows macOS LinuxCategories
Tags
Community Treasure Hunt
Find the treasures in MATLAB Central and discover how the community can help you!
Start Hunting!Discover Live Editor
Create scripts with code, output, and formatted text in a single executable document.
Versions that use the GitHub default branch cannot be downloaded
Version | Published | Release Notes | |
---|---|---|---|
1.0.0.0 | added description |
|