Utilities

Display

Various generally useful classes and methods.

Functions:

display(*imgs, **kwargs)	Display 2D and 3D ndarrays as images with matplotlib.
save_image(filename, *imgs, **kwargs)	Save 2D and 3D ndarrays as images with matplotlib.

display(*imgs, **kwargs)

Display 2D and 3D ndarrays as images with matplotlib.

The ndarrays must either be 2D, or 3D with 1 or 3 bands. If they are 3D masked arrays, the mask will be used as an alpha channel.

Unlike matplotlib’s imshow, arrays can be any dtype; internally, each is normalized to the range [0..1].

Parameters:

• *imgs (1 or more ndarrays) – When multiple images are given, each is displayed on its own row by default.

• bands_axis (int, default 0) – Axis which contains bands in each array.

• title (str, or sequence of str; optional) – Title for each image. If a sequence, must be the same length as imgs.

• size (int, default 10) – Length, in inches, to display the longer side of each image.

• robust (bool, default True) – Use the 2nd and 98th percentiles to compute color limits. Otherwise, the minimum and maximum values in each array are used.

• interpolation (str, default "bilinear") –

  Interpolation method for matplotlib to use when scaling images for display.

  Bilinear is the default, since it produces smoother results when scaling down continuously-valued data (i.e. images). For displaying discrete data, however, choose ‘nearest’ to prevent values not existing in the input from appearing in the output.

  Acceptable values are ‘none’, ‘nearest’, ‘bilinear’, ‘bicubic’, ‘spline16’, ‘spline36’, ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’, ‘quadric’, ‘catrom’, ‘gaussian’, ‘bessel’, ‘mitchell’, ‘sinc’, ‘lanczos’

• colormap (str, default None) –

  The name of a Colormap registered with matplotlib. Some commonly used built-in options are ‘plasma’, ‘magma’, ‘viridis’, ‘inferno’. See https://matplotlib.org/users/colormaps.html for more options.

  To use a Colormap, the input images must have a single band. The Colormap will be ignored for images with more than one band.

• figsize (tuple(int), default (size, (size / ncols) * nrows)) – Width, height in inches.

• nrows (int, default is the number of images) – Number of rows if there are multiple images.

• ncols (int, default 1) – Number of columns if there are multiple images.

• layout_direction (str, default "left-to-right") – If ncols is greated than 1, it determines whether the layout is left-to-right for the images, or top-to-bottom.

Raises:

ImportError – If matplotlib is not installed.

save_image(filename, *imgs, **kwargs)

Save 2D and 3D ndarrays as images with matplotlib.

For an explanation of the rest of the arguments, please look under display(). For an explanation of valid extension types, please look under matplotlib :func:’savefig’.

Parameters:

filename (str) – The name and extension of the image to be saved.

DotDict

Classes:

DotDict	Subclass of dict, with "dot" (attribute) access to keys, a pretty-printed repr, which indents and truncates large containers, and a JSON repr for Jupyter Lab.
DotList([iterable])	Returns contained dicts as DotDicts (and contained lists as DotLists), soley to allow attribute access past list indexing

class DotDict

Subclass of dict, with “dot” (attribute) access to keys, a pretty-printed repr, which indents and truncates large containers, and a JSON repr for Jupyter Lab.

Any dicts stored in DotDict are returned as DotDicts, to allow chained attribute access. Any lists stored in DotDict are returned as DotLists, which return any contained dict items as DotDicts, allowing chained attribute access past list indexing.

The repr() of a DotDict is truncated for readability, but str() is not.

Example

>>> d = DotDict(a=1, b=[{"foo": "bar"}])
>>> d.a
    1
>>> d["a"]
    1
>>> d.b
    [
      {
        'foo': 'bar'
      }
    ]
>>> d.b[0].foo
    'bar'

asdict() → a deep copy of D, where any DotDicts or DotLists contained are converted to plain types.

Raises RuntimeError if the container is recursive (contains itself as a value).

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

Values that are dicts or lists are cast to DotDicts and DotLists.

items()

Equivalent to dict.items. Values that are plain dicts or lists are returned as DotDicts or DotLists.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised. If v is a dict or list, it is returned as a DotDict or DotList.

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty. If v is a dict or list, it is returned as a DotDict or DotList.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

If d is a dict or list, it is returned as a DotDict or DotList.

values()

Equivalent to dict.values. Values that are plain dicts or lists are returned as DotDicts or DotLists.

class DotList(iterable=(), /)

Returns contained dicts as DotDicts (and contained lists as DotLists), soley to allow attribute access past list indexing

aslist() → a deep copy of L, where any DotDicts or DotLists contained are converted to plain types.

Raises RuntimeError if the container is recursive (contains itself as a value).

pop([index]) → item -- remove and return item at index (default last).

If item is a dict or list, it is returned as a DotDict or DotList. Raises IndexError if list is empty or index is out of range.

Properties

A property or attribute is any field listed as part of a catalog object. For example, the property or attribute modified of a product:

Product.modified

You cannot filter on all attributes. The documentation will indicate whether an attribute is filterable.

The easiest way to generate a property or attribute, is to name it in a GenericProperties instance. Typically such an instance is already included as a properties instance in the corresponding module, for example descarteslabs.catalog.properties.

from descarteslabs.catalog import properties as p
p.modified

or

from descarteslabs.common.property_filtering import GenericProperties
p = GenericProperties()
p.modified

or

from descarteslabs.common.property_filtering import Properties
p = Properties("modified", "created")
p.modified

or

from descarteslabs.common.property_filtering import Property
Property("modified")

You can use a property in an expression. An expression is the result of any filtering operation. Refer to the explanation in Expression for more information.

Classes:

Expression()	An expression is the result of a filtering operation.
ILikeExpression(name, value)	Whether a property value matches the given case insensitive wildcard expression.
LikeExpression(name, value)	Whether a property value matches the given wildcard expression.
NeExpression(name, value)	Whether a property value is not equal to the given value.
Properties(*args)	A wrapper object to construct filter properties by referencing instance attributes.
Property(name[, parts])	A filter property that can be used in an expression.
RangeExpression(name, parts)	Whether a property value is within the given range.

class Expression

An expression is the result of a filtering operation.

An expression can contain a Property, a comparison operator, and a value (or set of values):

property operator value

or

value operator property

where the operator can be

• ==

• !=

• <

• <=

• >

• >=

If the operator is <, <=, > or >=, you can construct a range using

value operator property operator value

Expressions can be combined using the Boolean operators & and | to form larger expressions. Due to language limitations the operator for and is expressed as & and the operator for or is expressed as |. Also, because of operator precedence, you must bracket expressions with ( and ) to avoid unexpected behavior:

( property operator value ) & ( value operator property )

In addition there is a method-like operator that can be used on a property.

• Property.any_of() or Property.in_()

And a couple of properties that allow you to verify whether a property value has been set or not. A property value is considered null when it’s either set to None or to the empty list [] in case of a list property. These are only available for the Catalog Service.

• Property.isnull

• Property.isnotnull

Examples

>>> from descarteslabs.common.property_filtering import Properties
>>> p = Properties()
>>> e = p.foo == 5
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.EqExpression'>
>>> e = p.foo.any_of([1, 2, 3, 4, 5])
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.OrExpression'>
>>> e = 5 < p.foo < 10
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.RangeExpression'>
>>> e = (5 < p.foo < 10) & p.foo.any_of([1, 2, 3, 4, 5])
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.AndExpression'>
>>> e = p.foo.isnotnull
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.IsNotNullExpression'>
>>> e = p.foo.isnull
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.IsNullExpression'>

is_same(other: Any) → bool

Determine if two expressions are the same. This is different from testing for equivalence (eg a == b and b == a are equivalent, bit not the same).

classmethod parse(data: str | Dict[str, Any] | List[Dict[str, Any]]) → AnyExpression

Parses a serialized filter into a series of expression objects.

Parameters:

data (str or dict) – The serialized filter expression. This can be a JSON string or a dict.

class ILikeExpression(name, value)

Whether a property value matches the given case insensitive wildcard expression.

The wildcard expression can contain % for zero or more characters and _ for a single character.

This expression is not supported by the Catalog service.

is_same(other: Any) → bool

Determine if two expressions are the same. This is different from testing for equivalence (eg a == b and b == a are equivalent, bit not the same).

class LikeExpression(name, value)

Whether a property value matches the given wildcard expression.

The wildcard expression can contain % for zero or more characters and _ for a single character.

This expression is not supported by the Catalog service.

is_same(other: Any) → bool

Determine if two expressions are the same. This is different from testing for equivalence (eg a == b and b == a are equivalent, bit not the same).

class NeExpression(name, value)

Whether a property value is not equal to the given value.

is_same(other: Any) → bool

Determine if two expressions are the same. This is different from testing for equivalence (eg a == b and b == a are equivalent, bit not the same).

class Properties(*args)

A wrapper object to construct filter properties by referencing instance attributes.

By referring to any instance attribute, a corresponding property will be created. The instance validates whether the generated property is in the list of property names that this instance was created with.

See Properties Introduction for a more detailed explanation.

Parameters:

name (str) – The property names that are allowed, each as a positional parameter.

Examples

>>> p = Properties("modified", "created")
>>> e = p.modified > "2020-01-01"
>>> e = p.deleted > "2020-01-01"  
Traceback (most recent call last):
  ...
AttributeError: 'Properties' object has no attribute 'deleted'
>>>

class Property(name, parts=None)

A filter property that can be used in an expression.

Although you can generate filter properties by instantiating this class, a more convenient method is to use a Properties instance. By referencing any attribute of a Properties instance the corresponding filter property will be created.

See Properties Introduction for a more detailed explanation.

Examples

>>> e = Property("modified") > "2020-01-01"

any_of(iterable)

The property must have any of the given values.

Asserts that this property must have a value equal to one of the values in the given iterable. This can be thought of as behaving like an in expression in Python or an IN expression in SQL.

ilike(wildcard)

Compare against a case insensitive wildcard string.

This can only be used in expressions for the Vector service. This allows for wildcards, e.g. ilike("bar%foo") where any string that starts with 'bar' and ends with 'foo' will be matched.

This uses the SQL LIKE syntax with single character wildcard '_' and arbitrary character wildcard '%'.

To escape either of these wilcard characters prepend it with a backslash, which becomes a double backslash in the python string, i.e. use like("bar\\%foo") to match exactly 'bar%foo'.

in_(iterable)

The property must have any of the given values.

Asserts that this property must have a value equal to one of the values in the given iterable. This can be thought of as behaving like an in expression in Python or an IN expression in SQL.

like(wildcard)

Compare against a wildcard string.

This can only be used in expressions for the Vector service. This allows for wildcards, e.g. like("bar%foo") where any string that starts with 'bar' and ends with 'foo' will be matched.

This uses the SQL LIKE syntax with single character wildcard '_' and arbitrary character wildcard '%'.

To escape either of these wilcard characters prepend it with a backslash, which becomes a double backslash in the python string, i.e. use like("bar\\%foo") to match exactly 'bar%foo'.

prefix(prefix)

Compare against a prefix string.

startswith(prefix)

Compare against a prefix string.

property isnotnull

Whether a property value is not None or [].

This can only be used in expressions for the Catalog service.

property isnull

Whether a property value is None or [].

This can only be used in expressions for the Catalog service.

class RangeExpression(name, parts)

Whether a property value is within the given range.

A range can have a single value that must be >, >=, < or <= than the value of the property. If the range has two values, the property value must be between the given range values.

is_same(other: Any) → bool

Determine if two expressions are the same. This is different from testing for equivalence (eg a == b and b == a are equivalent, bit not the same).