Attribute Filters

In many cases when working with objects that have a descriptive attributes, such as it is helpful to be able to filter that variable to a subset based on some of those attributes. IMAT has a selection filter data type called imat_filt that allows you to do this. An imat_filt is simply a set of criteria which can be used to select a subset of indices of a given variable. A filter can have a single criterion, or multiple criteria can be combined to create more complicated filters. You use function filters to select functions from an imat_fn or imat_shp array, using the syntax f{filt}.

Data Format for Filters

Each imat_filt variable is a separate filter (though it can contain multiple criteria). You may not use indexing operations on filter variables.

An imat_filt can only be used with a single data type. For example, a filter generated for use with imat_fn cannot be used with an imat_shp, as the attributes are different. You also cannot combine filters created for more than one type together with logical expressions. The default data type (if not specified when creating the filter) is imat_fn.

Each imat_filt variable consists of one or more criteria, combined by logical operators. An individual criterion has three parts:

attribute,  relation,  value

The attribute of a criterion can be the name of any valid data attribute for an imat_fn or imat_shp, with the exception of Abscissa and Ordinate for imat_fn and Node and Shape for imat_shp. The relation of a criterion can be any of the following:

The last four relations are applicable only to numeric data attributes.

The value of a criterion should be a scalar (for numeric data attributes) or a string (for string attributes) suitable for the data attribute. String matching is case insensitive. Two special features should be noted:

• For the ReferenceCoord and ResponseCoord data attributes, you may specify a coordinate trace as the value of the criterion. In this case, equality is satisfied if the reference (or response) coordinate of a function is included in the coordinate trace.

• For string properties, you may include wildcard characters: a question mark matches any single character, and an asterisk matches zero or more characters. (For example, 'ab?d*' matches the strings 'AbCd' and 'abxdefg', but not 'abccd'.) Wildcards cannot be used for list attributes such as FunctionType, which have a restricted list of possible values.

You create a function filter by specifying the attribute, relation, and value to the imat_filt constructor function. Using this creation syntax will by default create an imat_filt for use with imat_fn. Here are some examples:

>> z=imat_filt('functiontype', '=', 'frequency response function');
>> z=imat_filt('abscissainc', '<', 0.005);
>> t=imat_ctrace('1x','2z-');
>> z=imat_filt('responsecoord', '=', t);

It is also possible to specify multiple criteria to the imat_filt constructor (using an Nx3 cell array), in which case the criteria must all be satisfied:

>> z=imat_filt(  { 'functiontype', '=', 'auto spectrum' ;
                   'idline1',     '=', 'Test*'          } )
z =
...for objects of type 'imat_fn'

  ( ( FunctionType == 'Auto Spectrum' ) & ( IDLine1 == 'Test*' ) )

>>

To create an imat_filt for use with another data type, or to explicitly specify the default data type when creating the filter (which could be useful for code self-documentation), pass in the valid data type as the first input argument, followed by the criteria. Here are a few examples:

>> zs = imat_filt(imat_shp,'ShapeType','=','Real')                % Create an imat_filt specifically for imat_shp
zs =
...for objects of type 'imat_shp'

ShapeType == 'Real'


>> zf = imat_filt(imat_fn,'FunctionType','=','Time Response')     % Create an imat_filt specifically for imat_f
zf =
...for objects of type 'imat_fn'

FunctionType == 'Time Response'

>> zf = imat_filt('FunctionType','=','Time Response')             % Default calling format, functionally equivalent to the above
zf =
...for objects of type 'imat_fn'

FunctionType == 'Time Response'

Filters have a few attributes accessible either through dot "." notation, or through the get and set methods, and are described below.

The "Name" attribute contains a string. This is useful for giving a description to the created filter. If the Name property has been defined, it will appear when displaying the filter contains, as shown below.

>> z=imat_filt(imat_fn,'functiontype', '=', 'frequency response function');
>> z.name='FRF'

Name: FRF
z =
...for objects of type 'imat_fn'

FunctionType == 'Frequency Response Function'

>> get(z,'name')
  FRF

>>

The "criteria" attribute contains a cell array of strings of the criteria for this filter. Its output is equivalent to the output from the criteria method. The corresponding "equation" property returns a string that specifies the equation showing how the criteria relate to each other.

>> z=imat_filt(imat_fn,{'functiontype', '=', 'frequency response function'; 'IDLine1','=','ABC*'});

>> z.criteria
ans =
    'FunctionType'    '=='    'Frequency Response…'
    'IDLine1'         '=='    'ABC*'

>> z.equation
ans =
( %s & %s )

>>

Manipulating Filters

Other than applying a filter to an imat_fn or imat_shp array, the only operations you can perform on function filters are logical combinations:

• Combining two filters with an and operation (z1&z2) creates a new filter that is satisfied only if both of the filters are satisfied;

• Combining two filters with an or operation (z1|z2) creates a new filter that is satisfied if either of the filters is satisfied;

• Logically negating a filter (~z) creates a new filter that is satisfied only if the original filter is not satisfied.

These logical operations can be nested to create arbitrarily complex filters.

Using Filters with other IMAT data types

Filters are not very useful on their own. However, they find a lot of use when used with other IMAT objects such as functions and shapes. For example, they can be used to extract functions matching the attribute values specified in the filter, as demonstrated here. You can use filters defined with shape attributes to extract shapes matching those attributes, as described here.