Feature APIs in VerifAI

class Feature(domain, distribution=None, lengthDomain=None, lengthDistribution=None, distanceMetric=None)

A feature or list of features with unknown length.

Parameters:

• domain – a Domain object specifying the Feature’s possible values;

• distribution (optional) – object specifying the distribution of values;

• lengthDomain (Domain) – if not None, this Feature is actually a list of features, with possible lengths given by this Domain;

• lengthDistribution (optional) – distribution over lengths;

• distanceMetric (optional) – if not None, custom distance metric.

# Feature consisting of list of 10 cars
carDomain = Struct({
    'position': Array(Real(), [3]),
    'heading': Box((0, math.pi))
})
Feature(Array(carDomain, [10]))

# Feature consisting of list of 1-10 cars
Feature(carDomain, lengthDomain=DiscreteBox((1, 10)))

class FeatureSpace(features, distanceMetric=None)

A space consisting of named features.

FeatureSpace({
    'weather': Feature(DiscreteBox([0, 12])),
    'egoCar': Feature(carDomain),
    'traffic': Feature(Array(carDomain, [4]))
})

flatten(point, fixedDimension=False)

Flatten a point in this space. See Domain.flatten.

If fixedDimension is True, the point is flattened out as if all feature lists had their maximum lengths, with None as a placeholder. This means that all points in the space will flatten to the same length.

meaningOfFlatCoordinate(index, pointName='point')

Meaning of a coordinate of a flattened point in this space.

See the corresponding function of Domain. Works only for points flattened with fixedDimension=True, since otherwise a given index can have different meaning depending on the lengths of feature lists.

pandasIndexForFlatCoordinate(index)

Pandas index of a coordinate of a flattened point in this space.

See meaningOfFlatCoordinate, and Domain.pandasIndexForFlatCoordinate.

coordinateIsNumerical(index)

Whether the value of a coordinate is intrinsically numerical.

See meaningOfFlatCoordinate, and Domain.coordinateIsNumerical.

unflatten(coords, fixedDimension=False)

Unflatten a tuple of coordinates to a point in this space.

class Domain

Abstract class of domains

uniformPoint()

Sample a uniformly random point in this Domain

flatten(point)

Flatten a point in this Domain to a tuple of coordinates.

Useful for analyses that do not understand the internal structure of Domains. This representation of a point is also hashable, and so can be put into sets and dicts.

flattenOnto(point, targetList)

Flatten a point onto the end of the given list.

meaningOfFlatCoordinate(index, pointName='point')

Meaning of a coordinate of a flattened point in this Domain.

If pointName is the name of a variable storing a point in the Domain, then this function returns an expression extracting from that variable the value which would be stored in the given coordinate index when the point is flattened. For example:

>>> struct = Struct({'a': Real(), 'b': Real()})
>>> point = struct.makePoint(a=4, b=3)
>>> struct.flatten(point)
(4.0, 3.0)
>>> struct.meaningOfFlatCoordinate(1)
'point.b'
>>> eval(struct.meaningOfFlatCoordinate(1))
3

pandasIndexForFlatCoordinate(index)

Like meaningOfFlatCoordinate, but giving a MultiIndex for pandas.

coordinateIsNumerical(index)

Whether the value of a coordinate is intrinsically numerical.

In particular, whether it makes sense to use the Euclidean distance between different values of the coordinate. This would not be the case for Domains whose points are strings, for example, even if those are converted to numbers for the purpose of flattening.

numericizeCoordinate(coord)

Make a coordinate numeric. For internal use.

denumericizeCoordinate(coord)

Reconstitute a coordinate’s original value. For internal use.

unflatten(coords)

Unflatten a tuple of coordinates to a point in this Domain.

unflattenIterator(coords)

Unflatten an iterator of coordinates to a point in this Domain.

standardize(point)

Map the point into a hyperbox, preserving measure.

If the Domain is continuous, this should map into a unit hyperbox. If it is discrete, it should map into a discrete hyperbox. Which (if either) of these is the case can be determined by calling standardizedDimension and standardizedIntervals: for primitive Domains, at least one will return the ‘not supported’ value.

standardizeOnto(point, targetList)

Standardize a point onto the end of the given list.

unstandardize(coords)

Unstandardize a tuple of coordinates to a point in this Domain.

unstandardizeIterator(coords)

Unstandardize an iterator of coords to a point in this Domain.

partition(predicate)

Split this Domain into parts satisfying/falsifying the predicate.

rejoinPoints(*components)

Join points from the partitioned components of a Domain.

class Constant(value)

Domain consisting of a single value

class Categorical(*values)

Domain consisting of a finite set of values

class Real

Domain of real numbers

class Integer

Domain of integers

class Box(*intervals)

A hyper-box over the reals.

Points in a Box are tuples of floats.

class DiscreteBox(*intervals)

A hyper-box over the integers.

Points in a DiscreteBox are tuples of ints.

class Array(domain, shape)

A multidimensional array of elements in a common domain.

For example, Array(Box((-1, 1)), (10, 5)) represents a 10x5 grid of real numbers, each in the interval [-1, 1].

Points in an Array are nested tuples of elements. For example, a point in the Array above would be a tuple of 10 elements, each of which is a tuple of 5 elements, each of which is a point in the underlying Box domain.

pointWithElements(it)

Build a point in this domain from an iterable of elements.

This is similar to numpy.reshape, building a multidimensional array from a flat list of elements. For example:

>>> elts = [1, 2, 3, 4, 5, 6]
>>> array = Array(Real(), (2, 3))
>>> array.pointWithElements(elts)
((1, 2, 3), (4, 5, 6))
>>> array = Array(Real(), (3, 2))
>>> array.pointWithElements(elts)
((1, 2), (3, 4), (5, 6))

elementsOfPoint(point)

Return an iterator over the elements of a point in this domain.

This is similar to numpy.flatten, turning a multidimensional array into a flat list of elements. For example:

>>> array = Array(Real(), (3, 2))
>>> list(array.elementsOfPoint(((1, 2), (3, 4), (5, 6))))
[1, 2, 3, 4, 5, 6]

class ScalarArray(domain, shape)

An array whose elements are integers or reals.

This is a specialized implementation of Array optimized for large arrays of scalars like images.

class Struct(domains)

A domain consisting of named sub-domains.

The order of the sub-domains is arbitrary: two Structs are considered equal if they have the same named sub-domains, regardless of order. As the order is an implementation detail, accessing the values of sub-domains in points sampled from a Struct should be done by name:

>>> struct = Struct({'a': Box((0, 1)), 'b': Box((2, 3))})
>>> point = struct.uniformPoint()
>>> point.b
(2.20215292046797,)

Within a given version of VerifAI, the sub-domain order is consistent, so that the order of columns in error tables is also consistent.