ImageFolder.select

ImageFolder.select(*args, **kargs)

Select a subset of the objects in the folder based on flexible search criteria on the metadata.

Parameters:

args (various) – A single positional argument if present is interpreted as follows:

  • If a callable function is given, the entire metadataObject is presented to it. If it evaluates True then that metadataObject is selected. This allows arbitrary select operations

  • If a dict is given, then it and the kargs dictionary are merged and used to select the metadataObjects

Keyword Arguments:

  • recurse (bool) – Also recursively slect through the sub groups

  • kargs (varuous) –

    Arbitrary keyword arguments are interpreted as requestion matches against the corresponding metadata values. The keyword argument may have an additional __operator appended to it which is interpreted as follows:

    • eq metadata value equals argument value (this is the default test for scalar argument)

    • ne metadata value doe not equal argument value

    • gt metadata value doe greater than argument value

    • lt metadata value doe less than argument value

    • ge metadata value doe greater than or equal to argument value

    • le metadata value doe less than or equal to argument value

    • contains metadata value contains argument value

    • in metadata value is in the argument value (this is the default test for non-tuple iterable

      arguments)

    • startswith metadata value startswith argument value

    • endswith metadata value endwith argument value

    • icontains,*iin*, istartswith,*iendswith* as above but case insensitive

    • between metadata value lies between the minimum and maximum values of the argument (the default test for 2-length tuple arguments)

    • ibetween,*ilbetween*,*iubetween* as above but include both,lower or upper values

  • rich. (The syntax is inspired by the Django project for selecting, but is not quite as) –

Returns:

(baseFGolder) – A new baseFolder instance that contains just the matching metadataObjects.

Note

If any of the tests is True, then the metadataObject will be selected, so the effect is a logical OR. To achieve a logical AND, you can chain two selects together:

d.select(temp__le=4.2,vti_temp__lt=4.2).select(field_gt=3.0)

will select metadata objects that have either temp or vti_temp metadata values below 4.2 AND field metadata values greater than 3.

There are a few cases where special treatment is needed:

  • If you need to select on a aparameter called recurse, pass a dictionary of {“recurse”:value} as the sole positional argument.

  • If you need to select on a metadata value that ends in an operator word, then append __eq in the keyword name to force the equality test.

  • If the metadata keys to select on are not valid python identifiers, then pass them via the first positional dictionary value.

If the metadata item being checked exists in a regular expression file pattern for the folder, then the files are not loaded and the metadata is evaluated based on the filename. This can speed up operations where a file load is not required.