fiftyone.core.expressions¶
Expressions for fiftyone.core.stages.ViewStage
definitions.
Classes:

A 

An expression defining a possiblycomplex manipulation of a document. 

A 
Data:
A 
Functions:

Converts an expression to its MongoDB representation. 

fiftyone.core.expressions.
to_mongo
(expr, prefix=None)¶ Converts an expression to its MongoDB representation.
 Parameters
expr – a
ViewExpression
or an already serialized MongoDB expressionprefix (None) – an optional prefix to prepend to all
ViewField
instances in the expression
 Returns
a MongoDB expression

class
fiftyone.core.expressions.
ViewExpression
(expr)¶ Bases:
object
An expression defining a possiblycomplex manipulation of a document.
View expressions enable you to specify manipulations of documents that can then be executed on your data in the context of a
fiftyone.core.stages.ViewStage
.Typically,
ViewExpression
instances are built by creating one or moreViewField
instances and then defining the desired operation by recursively invoking methods on these objects:from fiftyone import ViewField as F # An expression that tests whether the `confidence` field of a document # is greater than 0.9 F("confidence") > 0.9 # An expression that computes the area of a bounding box # Bboxes are in [topleftx, toplefty, width, height] format F("bounding_box")[2] * F("bounding_box")[3] # # A more complex expression that returns one of three strings based on # the number of high confidence predictions in the `detections` field # of a document with the label "cat" or "dog" after normalizing to # lowercase # F("detections").map( F().set_field("label", F("label").lower()) ).filter( F("label").is_in(("cat", "dog")) & (F("confidence") > 0.9) ).length().switch( { (F() >= 10): "zoo", (F() > 2) & (F() < 10): "party", (F() <= 2): "home", } )
There are a few cases where you may need to instantitate a
ViewExpression
directly, typically when you need to write an expression that begins with a literal Python value:from fiftyone import ViewExpression as E from fiftyone import ViewField as F # Concatenates the "animal" string to the `label` field of a document F("label").concat("animal") # Prepends the "animal" string to the `label` field E("animal").concat(F("label")) # Appends the strings "test" and "validation" to the contents of the # `tags` field array # assumed to be an array F("tags").extend(["test", "validation"]) # Prepends the "test" and "validation" strings to the `tags` field E(["test", "validation"]).extend(F("tags"))
See MongoDB expressions for more details about the underlying expression language that this class encapsulates.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # # Create a view that only contains predictions whose bounding boxes # have area < 0.2 with confidence > 0.9, and only include samples with # at least 15 such objects # view = dataset.filter_labels( "predictions", (bbox_area < 0.2) & (F("confidence") > 0.9) ).match( F("predictions.detections").length() > 15 ) session = fo.launch_app(view=view)

__eq__
(other)¶ Determines whether this expression is equal to the given value or expression,
self == other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset( "cifar10", split="test", max_samples=500, shuffle=True ) # Get samples whose ground truth `label` is "airplane" view = dataset.match(F("ground_truth.label") == "airplane") print(view.distinct("ground_truth.label"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__ge__
(other)¶ Determines whether this expression is greater than or equal to the given value or expression,
self >= other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 view = dataset.match(F("uniqueness") >= 0.5) print(view.bounds("uniqueness"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__gt__
(other)¶ Determines whether this expression is greater than the given value or expression,
self >= other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is > 0.5 view = dataset.match(F("uniqueness") > 0.5) print(view.bounds("uniqueness"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__le__
(other)¶ Determines whether this expression is less than or equal to the given value or expression,
self <= other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is <= 0.5 view = dataset.match(F("uniqueness") <= 0.5) print(view.bounds("uniqueness"))
 Parameters
other – a literal value or
ViewExpression
other – a
ViewExpression
or a python primitive understood by MongoDB
 Returns

__lt__
(other)¶ Determines whether this expression is less than the given value or expression,
self <= other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is < 0.5 view = dataset.match(F("uniqueness") < 0.5) print(view.bounds("uniqueness"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__ne__
(other)¶ Determines whether this expression is not equal to the given value or expression,
self != other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset( "cifar10", split="test", max_samples=500, shuffle=True ) # Get samples whose ground truth `label` is NOT "airplane" view = dataset.match(F("ground_truth.label") != "airplane") print("airplane" in view.distinct("ground_truth.label"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__and__
(other)¶ Computes the logical AND of this expression and the given value or expression,
self & other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains predictions with label "cat" and confidence > 0.9 view = dataset.filter_labels( "predictions", (F("label") == "cat") & (F("confidence") > 0.9) ) print(view.count_values("predictions.detections.label")) print(view.bounds("predictions.detections.confidence"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__invert__
()¶ Inverts this expression,
~self
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add a new field to one sample sample = dataset.first() sample["new_field"] = ["hello", "there"] sample.save() # Get samples that do NOT have a value for `new_field` view = dataset.match(~F("new_field").exists()) print(len(view))
 Returns

__or__
(other)¶ Computes the logical OR of this expression and the given value or expression,
self  other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains predictions with label "cat" or confidence > 0.9 view = dataset.filter_labels( "predictions", (F("label") == "cat")  (F("confidence") > 0.9) ) print(view.count_values("predictions.detections.label")) print(view.bounds("predictions.detections.confidence"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__abs__
()¶ Computes the absolute value of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match(abs(F("uniqueness")  0.5) < 0.25) print(view.bounds("uniqueness"))
 Returns

__add__
(other)¶ Adds the given value to this expression, which must resolve to a numeric value,
self + other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format manhattan_dist = F("bounding_box")[0] + F("bounding_box")[1] # Only contains predictions whose bounding boxes' upper left corner # is a Manhattan distance of at least 1 from the origin dataset.filter_labels("predictions, manhattan_dist > 1) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
other – a number or
ViewExpression
 Returns

__ceil__
()¶ Computes the ceiling of this expression, which must resolve to a numeric value.
Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match(math.ceil(F("uniqueness") + 0.5) == 2) print(view.bounds("uniqueness"))
 Returns

__floor__
()¶ Computes the floor of this expression, which must resolve to a numeric value.
Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match(math.floor(F("uniqueness") + 0.5) == 1) print(view.bounds("uniqueness"))
 Returns

__round__
(place=0)¶ Rounds this expression, which must resolve to a numeric value, at the given decimal place.
Positive values of
place
will round toplace
decimal places:place=2: 1234.5678 > 1234.57
Negative values of
place
will round digits left of the decimal:place=2: 1234.5678 > 1200
 Parameters
place (0) – the decimal place at which to round. Must be an integer in range
(20, 100)
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match(round(2 * F("uniqueness")) == 1) print(view.bounds("uniqueness"))
 Returns

__mod__
(other)¶ Computes the modulus of this expression, which must resolve to a numeric value,
self % other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with an even number of predictions view = dataset.match( (F("predictions.detections").length() % 2) == 0 ) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
other – a number or
ViewExpression
 Returns

__mul__
(other)¶ Computes the product of the given value and this expression, which must resolve to a numeric value,
self * other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Only contains predictions whose bounding box area is > 0.2 view = dataset.filter_labels("predictions", bbox_area > 0.2)
 Parameters
other – a number or
ViewExpression
 Returns

__pow__
(power, modulo=None)¶ Raises this expression, which must resolve to a numeric value, to the given power,
self ** power
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format center_dist = ( (F("bounding_box")[0] + 0.5 * F("bounding_box")[2]  0.5) ** 2 + (F("bounding_box")[1] + 0.5 * F("bounding_box")[3]  0.5) ** 2 ).sqrt() # Only contains predictions whose bounding box center is a distance # of at most 0.02 from the center of the image view = dataset.select_fields("predictions").filter_labels( "predictions", center_dist < 0.02 ) session = fo.launch_app(view=view)
 Parameters
power – the power
 Returns

__sub__
(other)¶ Subtracts the given value from this expression, which must resolve to a numeric value,
self  other
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") dataset.compute_metadata() # Bboxes are in [topleftx, toplefty, width, height] format rectangleness = abs( F("$metadata.width") * F("bounding_box")[2]  F("$metadata.height") * F("bounding_box")[3] ) # Only contains predictions whose bounding boxes are within 1 pixel # of being square view = ( dataset .select_fields("predictions") .filter_labels("predictions", rectangleness <= 1) ) session = fo.launch_app(view=view)
 Parameters
other – a number or
ViewExpression
 Returns

__truediv__
(other)¶ Divides this expression, which must resolve to a numeric value, by the given value,
self / other
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") dataset.compute_metadata() # Bboxes are in [topleftx, toplefty, width, height] format aspect_ratio = ( (F("$metadata.width") * F("bounding_box")[2]) / (F("$metadata.height") * F("bounding_box")[3]) ) # Only contains predictions whose aspect ratio is > 2 view = ( dataset .select_fields("predictions") .filter_labels("predictions", aspect_ratio > 2) ) session = fo.launch_app(view=view)
 Parameters
other – a number or
ViewExpression
 Returns

__getitem__
(idx_or_slice)¶ Returns the element or slice of this expression, which must resolve to an array.
All of the typical slicing operations are supported, except for specifying a nonunit step:
expr[3] # the fourth element expr[1] # the last element expr[:10] # the first (up to) 10 elements expr[3:] # the last (up to) 3 elements expr[3:10] # the fourth through tenth elements
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Only contains objects in the `predictions` field with area > 0.2 view = dataset.filter_labels("predictions", bbox_area > 0.2) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
idx_or_slice – the index or slice
 Returns
 Parameters
expr – the MongoDB expression
Methods:
abs
()Computes the absolute value of this expression, which must resolve to a numeric value.
all
(exprs)Checks whether all of the given expressions evaluate to True.
any
(exprs)Checks whether any of the given expressions evaluate to True.
append
(value)Appends the given value to this expression, which must resolve to an array.
apply
(expr)Applies the given expression to this expression.
arccos
()Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians.
arccosh
()Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
arcsin
()Computes the inverse sine of this expression, which must resolve to a numeric value, in radians.
arcsinh
()Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
arctan
()Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians.
arctanh
()Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
cases
(mapping[, default])Applies a case statement to this expression, which effectively computes the following pseudocode.
ceil
()Computes the ceiling of this expression, which must resolve to a numeric value.
concat
(*args)Concatenates the given string(s) to this expression, which must resolve to a string.
contains
(values[, all])Checks whether this expression, which must resolve to an array, contains any of the given values.
contains_str
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, contains the given string or string(s).
cos
()Computes the cosine of this expression, which must resolve to a numeric value, in radians.
cosh
()Computes the hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
Returns the day of the month of this date expression (in UTC) as a number between 1 and 31.
Returns the day of the week of this date expression (in UTC) as a number between 1 (Sunday) and 7 (Saturday).
Returns the day of the year of this date expression (in UTC) as a number between 1 and 366.
difference
(values)Computes the set difference of this expression, which must resolve to an array, and the given array or array expression.
ends_with
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, ends with the given string or string(s).
enumerate
(array[, start])Returns an array of
[index, element]
pairs enumerating the elements of the given expression, which must resolve to an array.exists
([bool])Determines whether this expression, which must resolve to a field, exists and is not None.
exp
()Raises Euler’s number to this expression, which must resolve to a numeric value.
extend
(*args)Concatenates the given array(s) or array expression(s) to this expression, which must resolve to an array.
filter
(expr)Applies the given filter to the elements of this expression, which must resolve to an array.
floor
()Computes the floor of this expression, which must resolve to a numeric value.
hour
()Returns the hour portion of this date expression (in UTC) as a number between 0 and 23.
if_else
(true_expr, false_expr)Returns either
true_expr
orfalse_expr
depending on the value of this expression, which must resolve to a boolean.insert
(index, value)Inserts the value before the given index in this expression, which must resolve to an array.
intersection
(*args)Computes the set intersection of this expression, which must resolve to an array, and the given array(s) or array expression(s).
is_array
()Determines whether this expression is an array.
is_in
(values)Creates an expression that returns a boolean indicating whether
self in values
.Determines whether this expression refers to a missing field.
is_null
()Determines whether this expression is null.
Determines whether this expression is a number.
Determines whether this expression is a string.
is_subset
(values)Checks whether this expression’s contents, which must resolve to an array, are a subset of the given array or array expression’s contents.
join
(delimiter)Joins the elements of this expression, which must resolve to a string array, by the given delimiter.
length
()Computes the length of this expression, which must resolve to an array.
let_in
(expr)Returns an equivalent expression where this expression is defined as a variable that is used wherever necessary in the given expression.
literal
(value)Returns an expression representing the given value without parsing.
ln
()Computes the natural logarithm of this expression, which must resolve to a numeric value.
log
(base)Computes the logarithm base
base
of this expression, which must resolve to a numeric value.log10
()Computes the logarithm base 10 of this expression, which must resolve to a numeric value.
lower
()Converts this expression, which must resolve to a string, to lowercase.
lstrip
([chars])Removes whitespace characters from the beginning of this expression, which must resolve to a string.
map
(expr)Applies the given expression to the elements of this expression, which must resolve to an array.
map_values
(mapping)Replaces this expression with the corresponding value in the provided mapping dict, if it is present as a key.
matches_str
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, exactly matches the given string or string(s).
max
([value])Returns the maximum value of either this expression, which must resolve to an array, or the maximum of this expression and the given value.
mean
()Returns the average value in this expression, which must resolve to a numeric array.
Returns the millisecond portion of this date expression (in UTC) as an integer between 0 and 999.
min
([value])Returns the minimum value of either this expression, which must resolve to an array, or the minimum of this expression and the given value.
minute
()Returns the minute portion of this date expression (in UTC) as a number between 0 and 59.
month
()Returns the month of this date expression (in UTC) as a number between 1 and 12.
pow
(power)Raises this expression, which must resolve to a numeric value, to the given power,
self ** power
.prepend
(value)Prepends the given value to this expression, which must resolve to an array.
rand
()Returns an expression that generates a uniform random float in
[0, 1]
each time it is called.randn
()Returns an expression that generates a sample from the standard Gaussian distribution each time it is called.
range
(start[, stop])Returns an array expression containing the sequence of integers from the specified start (inclusive) to stop (exclusive).
re_match
(regex[, options])Performs a regular expression pattern match on this expression, which must resolve to a string.
reduce
(expr[, init_val])Applies the given reduction to this expression, which must resolve to an array, and returns the single value computed.
replace
(old, new)Replaces all occurances of
old
withnew
in this expression, which must resolve to a string.reverse
()Reverses the order of the elements in the expression, which must resolve to an array.
round
([place])Rounds this expression, which must resolve to a numeric value, at the given decimal place.
rsplit
(delimiter[, maxsplit])Splits this expression, which must resolve to a string, by the given delimiter.
rstrip
([chars])Removes whitespace characters from the end of this expression, which must resolve to a string.
second
()Returns the second portion of this date expression (in UTC) as a number between 0 and 59.
set_equals
(*args)Checks whether this expression, which must resolve to an array, contains the same distinct values as each of the given array(s) or array expression(s).
set_field
(field, value_or_expr[, relative])Sets the specified field or embedded field of this expression, which must resolve to a document, to the given value or expression.
sin
()Computes the sine of this expression, which must resolve to a numeric value, in radians.
sinh
()Computes the hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
sort
([key, reverse])Sorts this expression, which must resolve to an array.
split
(delimiter[, maxsplit])Splits this expression, which must resolve to a string, by the given delimiter.
sqrt
()Computes the square root of this expression, which must resolve to a numeric value.
starts_with
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, starts with the given string or string(s).
std
([sample])Returns the standard deviation of the values in this expression, which must resolve to a numeric array.
strip
([chars])Removes whitespace characters from the beginning and end of this expression, which must resolve to a string.
strlen
()Computes the length of this expression, which must resolve to a string.
substr
([start, end, count])Extracts the specified substring from this expression, which must resolve to a string.
sum
()Returns the sum of the values in this expression, which must resolve to a numeric array.
switch
(mapping[, default])Applies a switch statement to this expression, which effectively computes the given pseudocode.
tan
()Computes the tangent of this expression, which must resolve to a numeric value, in radians.
tanh
()Computes the hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
to_bool
()Converts the expression to a boolean value.
to_date
()Converts the expression to a date value.
Converts the expression to a double precision value.
to_int
()Converts the expression to an integer value.
to_mongo
([prefix])Returns a MongoDB representation of the expression.
Converts the expression to a string value.
trunc
([place])Truncates this expression, which must resolve to a numeric value, at the specified decimal place.
type
()Returns the type string of this expression.
union
(*args)Computes the set union of this expression, which must resolve to an array, and the given array(s) or array expression(s).
unique
()Returns an array containing the unique values in this expression, which must resolve to an array.
upper
()Converts this expression, which must resolve to a string, to uppercase.
week
()Returns the week of the year of this date expression (in UTC) as a number between 0 and 53.
year
()Returns the year of this date expression (in UTC).
zip
(*args[, use_longest, defaults])Zips the given expressions, which must resolve to arrays, into an array whose ith element is an array containing the ith element from each input array.
Attributes:
Whether this expression’s prefix is frozen.

property
is_frozen
¶ Whether this expression’s prefix is frozen.

to_mongo
(prefix=None)¶ Returns a MongoDB representation of the expression.
 Parameters
prefix (None) – an optional prefix to prepend to all
ViewField
instances in the expression Returns
a MongoDB expression

exists
(bool=True)¶ Determines whether this expression, which must resolve to a field, exists and is not None.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset( "quickstart", dataset_name=fo.get_default_dataset_name() ) # Add a new field to one sample sample = dataset.first() sample["new_field"] = ["hello", "there"] sample.save() # Get samples that have a value for `new_field` view = dataset.match(F("new_field").exists()) print(len(view))
 Parameters
bool (True) – whether to determine whether this expression exists (True) or is None or nonexistent (False)
 Returns

abs
()¶ Computes the absolute value of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match((F("uniqueness")  0.5).abs() < 0.25) print(view.bounds("uniqueness"))
 Returns

floor
()¶ Computes the floor of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match((F("uniqueness") + 0.5).floor() == 1) print(view.bounds("uniqueness"))
 Returns

ceil
()¶ Computes the ceiling of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match((F("uniqueness") + 0.5).ceil() == 2) print(view.bounds("uniqueness"))
 Returns

round
(place=0)¶ Rounds this expression, which must resolve to a numeric value, at the given decimal place.
Positive values of
place
will round toplace
decimal places:place=2: 1234.5678 > 1234.57
Negative values of
place
will roundplace
digits left of the decimal:place=1: 1234.5678 > 1230
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match((2 * F("uniqueness")).round() == 1) print(view.bounds("uniqueness"))
 Parameters
place (0) – the decimal place at which to round. Must be an integer in range
(20, 100)
 Returns

trunc
(place=0)¶ Truncates this expression, which must resolve to a numeric value, at the specified decimal place.
Positive values of
place
will truncate toplace
decimal places:place=2: 1234.5678 > 1234.56
Negative values of
place
will replaceplace
digits left of the decimal with zero:place=1: 1234.5678 > 1230
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") dataset.compute_metadata() # Only contains samples whose height is in [500, 600) pixels view = dataset.match(F("metadata.height").trunc(2) == 500) print(view.bounds("metadata.height"))
 Parameters
place (0) – the decimal place at which to truncate
 Returns

exp
()¶ Raises Euler’s number to this expression, which must resolve to a numeric value.
 Returns

ln
()¶ Computes the natural logarithm of this expression, which must resolve to a numeric value.
Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 view = dataset.match(F("uniqueness").ln() >= math.log(0.5)) print(view.bounds("uniqueness"))
 Returns

log
(base)¶ Computes the logarithm base
base
of this expression, which must resolve to a numeric value.Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 view = dataset.match(F("uniqueness").log(2) >= math.log2(0.5)) print(view.bounds("uniqueness"))
 Parameters
base – the logarithm base
 Returns

log10
()¶ Computes the logarithm base 10 of this expression, which must resolve to a numeric value.
Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 view = dataset.match(F("uniqueness").log10() >= math.log10(0.5)) print(view.bounds("uniqueness"))
 Returns

pow
(power)¶ Raises this expression, which must resolve to a numeric value, to the given power,
self ** power
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format center_dist = ( (F("bounding_box")[0] + 0.5 * F("bounding_box")[2]  0.5).pow(2) + (F("bounding_box")[1] + 0.5 * F("bounding_box")[3]  0.5).pow(2) ).sqrt() # Only contains predictions whose bounding box center is a distance # of at most 0.02 from the center of the image view = dataset.select_fields("predictions").filter_labels( "predictions", center_dist < 0.02 ) session = fo.launch_app(view=view)
 Parameters
power – the power
 Returns

sqrt
()¶ Computes the square root of this expression, which must resolve to a numeric value.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format center_dist = ( (F("bounding_box")[0] + 0.5 * F("bounding_box")[2]  0.5) ** 2 + (F("bounding_box")[1] + 0.5 * F("bounding_box")[3]  0.5) ** 2 ).sqrt() # Only contains predictions whose bounding box center is a distance # of at most 0.02 from the center of the image view = dataset.select_fields("predictions").filter_labels( "predictions", center_dist < 0.02 ) session = fo.launch_app(view=view)
 Returns

cos
()¶ Computes the cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `cos()` view = dataset.match(F("uniqueness").cos() <= np.cos(0.5)) print(view.bounds("uniqueness"))
 Returns

cosh
()¶ Computes the hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `cosh()` view = dataset.match(F("uniqueness").cosh() >= np.cosh(0.5)) print(view.bounds("uniqueness"))
 Returns

sin
()¶ Computes the sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `sin()` view = dataset.match(F("uniqueness").sin() >= np.sin(0.5)) print(view.bounds("uniqueness"))
 Returns

sinh
()¶ Computes the hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `sinh()` view = dataset.match(F("uniqueness").sinh() >= np.sinh(0.5)) print(view.bounds("uniqueness"))
 Returns

tan
()¶ Computes the tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `tan()` view = dataset.match(F("uniqueness").tan() >= np.tan(0.5)) print(view.bounds("uniqueness"))
 Returns

tanh
()¶ Computes the hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `tanh()` view = dataset.match(F("uniqueness").tanh() >= np.tanh(0.5)) print(view.bounds("uniqueness"))
 Returns

arccos
()¶ Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arccos()` view = dataset.match(F("uniqueness").arccos() <= np.arccos(0.5)) print(view.bounds("uniqueness"))
 Returns

arccosh
()¶ Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arccosh()` view = dataset.match((1 + F("uniqueness")).arccosh() >= np.arccosh(1.5)) print(view.bounds("uniqueness"))
 Returns

arcsin
()¶ Computes the inverse sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arcsin()` view = dataset.match(F("uniqueness").arcsin() >= np.arcsin(0.5)) print(view.bounds("uniqueness"))
 Returns

arcsinh
()¶ Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arcsinh()` view = dataset.match(F("uniqueness").arcsinh() >= np.arcsinh(0.5)) print(view.bounds("uniqueness"))
 Returns

arctan
()¶ Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arctan()` view = dataset.match(F("uniqueness").arctan() >= np.arctan(0.5)) print(view.bounds("uniqueness"))
 Returns

arctanh
()¶ Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arctanh()` view = dataset.match(F("uniqueness").arctanh() >= np.arctanh(0.5)) print(view.bounds("uniqueness"))
 Returns

type
()¶ Returns the type string of this expression.
See this page for more details.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.75 to None view = dataset.set_field( "uniqueness", (F("uniqueness") > 0.75).if_else(F("uniqueness"), None) ) # Create a view that only contains samples with nonNone uniqueness unique_only_view = view.match(F("uniqueness").type() != "null") print(len(unique_only_view))
 Returns

is_null
()¶ Determines whether this expression is null.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.25 to None view = dataset.set_field( "uniqueness", (F("uniqueness") >= 0.25).if_else(F("uniqueness"), None) ) # Create view that only contains samples with uniqueness = None not_unique_view = view.match(F("uniqueness").is_null()) print(len(not_unique_view))
 Returns

is_number
()¶ Determines whether this expression is a number.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.25 to None view = dataset.set_field( "uniqueness", (F("uniqueness") >= 0.25).if_else(F("uniqueness"), None) ) # Create view that only contains samples with uniqueness values has_unique_view = view.match(F("uniqueness").is_number()) print(len(has_unique_view))
 Returns

is_string
()¶ Determines whether this expression is a string.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Verify that filepaths are strings view = dataset.match(F("filepath").is_string()) print(len(view))
 Returns

is_array
()¶ Determines whether this expression is an array.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Verify that tags are arrays view = dataset.match(F("tags").is_array()) print(len(view))
 Returns

is_missing
()¶ Determines whether this expression refers to a missing field.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Verify that `foobar` is a nonexistent field on all samples view = dataset.match(F("foobar").is_missing()) print(len(view) == len(dataset))
 Returns

is_in
(values)¶ Creates an expression that returns a boolean indicating whether
self in values
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F ANIMALS = [ "bear", "bird", "cat", "cow", "dog", "elephant", "giraffe", "horse", "sheep", "zebra" ] dataset = foz.load_zoo_dataset("quickstart") # Create a view that only contains animal predictions view = dataset.filter_labels( "predictions", F("label").is_in(ANIMALS) ) print(view.count_values("predictions.detections.label"))
 Parameters
values – a value or iterable of values
 Returns

to_bool
()¶ Converts the expression to a boolean value.
See this page for conversion rules.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart").clone() # Adds a `uniqueness_bool` field that is False when # `uniqueness < 0.5` and True when `uniqueness >= 0.5` dataset.add_sample_field("uniqueness_bool", fo.BooleanField) view = dataset.set_field( "uniqueness_bool", (2.0 * F("uniqueness")).floor().to_bool() ) print(view.count_values("uniqueness_bool"))
 Returns

to_int
()¶ Converts the expression to an integer value.
See this page for conversion rules.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart").clone() # Adds a `uniqueness_int` field that contains the value of the # first decimal point of the `uniqueness` field dataset.add_sample_field("uniqueness_int", fo.IntField) view = dataset.set_field( "uniqueness_int", (10.0 * F("uniqueness")).floor().to_int() ) print(view.count_values("uniqueness_int"))
 Returns

to_double
()¶ Converts the expression to a double precision value.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart").clone() # Adds a `uniqueness_float` field that is 0.0 when # `uniqueness < 0.5` and 1.0 when `uniqueness >= 0.5` dataset.add_sample_field("uniqueness_float", fo.FloatField) view = dataset.set_field( "uniqueness_float", (F("uniqueness") >= 0.5).to_double() ) print(view.count_values("uniqueness_float"))
See this page for conversion rules.
 Returns

to_string
()¶ Converts the expression to a string value.
See this page for conversion rules.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart").clone() # Adds a `uniqueness_str` field that is "true" when # `uniqueness >= 0.5` and "false" when `uniqueness < 0.5` dataset.add_sample_field("uniqueness_str", fo.StringField) view = dataset.set_field( "uniqueness_str", (F("uniqueness") >= 0.5).to_string() ) print(view.count_values("uniqueness_str"))
 Returns

to_date
()¶ Converts the expression to a date value.
See this page for conversion rules.
Examples:
from datetime import datetime import pytz import fiftyone as fo from fiftyone import ViewField as F now = datetime.utcnow().replace(tzinfo=pytz.utc) sample = fo.Sample( filepath="image.png", date_ms=1000 * now.timestamp(), date_str=now.isoformat(), ) dataset = fo.Dataset() dataset.add_sample(sample) # Convert string/millisecond representations into datetimes dataset.add_sample_field("date1", fo.DateTimeField) dataset.add_sample_field("date2", fo.DateTimeField) ( dataset .set_field("date1", F("date_ms").to_date()) .set_field("date2", F("date_str").to_date()) .save() ) print(dataset.first())
 Returns

apply
(expr)¶ Applies the given expression to this expression.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples with `uniqueness` in [0.25, 0.75] view = dataset.match( F("uniqueness").apply((F() > 0.25) & (F() < 0.75)) ) print(view.bounds("uniqueness"))
 Parameters
expr – a
ViewExpression
 Returns

if_else
(true_expr, false_expr)¶ Returns either
true_expr
orfalse_expr
depending on the value of this expression, which must resolve to a boolean.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.75 to None view = dataset.set_field( "uniqueness", (F("uniqueness") > 0.75).if_else(F("uniqueness"), None) ) print(view.bounds("uniqueness"))
 Parameters
true_expr – a
ViewExpression
or MongoDB expression dictfalse_expr – a
ViewExpression
or MongoDB expression dict
 Returns

cases
(mapping, default=None)¶ Applies a case statement to this expression, which effectively computes the following pseudocode:
for key, value in mapping.items(): if self == key: return value if default is not None: return default
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.75 to None view = dataset.set_field( "uniqueness", (F("uniqueness") > 0.75).if_else(F("uniqueness"), None) ) # Map numeric `uniqueness` values to 1 and null values to 0 cases_view = view.set_field( "uniqueness", F("uniqueness").type().cases({"double": 1, "null": 0}), ) print(cases_view.count_values("uniqueness"))
 Parameters
mapping – a dict mapping literals or
ViewExpression
keys to literal orViewExpression
valuesdefault (None) – an optional literal or
ViewExpression
to return if none of the switch branches are taken
 Returns

switch
(mapping, default=None)¶ Applies a switch statement to this expression, which effectively computes the given pseudocode:
for key, value in mapping.items(): if self.apply(key): return value if default is not None: return default
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Round `uniqueness` values to either 0.25 or 0.75 view = dataset.set_field( "uniqueness", F("uniqueness").switch( { (0.0 < F()) & (F() <= 0.5): 0.25, (0.5 < F()) & (F() <= 1.0): 0.75, }, ) ) print(view.count_values("uniqueness"))
 Parameters
mapping – a dict mapping boolean
ViewExpression
keys to literal orViewExpression
valuesdefault (None) – an optional literal or
ViewExpression
to return if none of the switch branches are taken
 Returns

map_values
(mapping)¶ Replaces this expression with the corresponding value in the provided mapping dict, if it is present as a key.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F ANIMALS = [ "bear", "bird", "cat", "cow", "dog", "elephant", "giraffe", "horse", "sheep", "zebra" ] dataset = foz.load_zoo_dataset("quickstart") # # Replace the `label` of all animal objects in the `predictions` # field with "animal" # mapping = {a: "animal" for a in ANIMALS} view = dataset.set_field( "predictions.detections", F("detections").map( F().set_field("label", F("label").map_values(mapping)) ) ) print(view.count_values("predictions.detections.label"))
 Parameters
mapping – a dict mapping keys to replacement values
 Returns

set_field
(field, value_or_expr, relative=True)¶ Sets the specified field or embedded field of this expression, which must resolve to a document, to the given value or expression.
By default, the provided expression is computed by applying it to this expression via
self.apply(value_or_expr)
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # # Replaces the `label` attritubes of the objects in the # `predictions` field according to the following rule: # # If the `label` starts with `b`, replace it with `b`. Otherwise, # replace it with "other" # view = dataset.set_field( "predictions.detections", F("detections").map( F().set_field( "label", F("label").re_match("^b").if_else("b", "other"), ) ) ) print(view.count_values("predictions.detections.label"))
 Parameters
field – the “field” or “embedded.field.name” to set
value_or_expr – a literal value or
ViewExpression
defining the field to setrelative (True) – whether to compute
value_or_expr
by applying it to this expression (True), or to use it untouched (False)
 Returns

let_in
(expr)¶ Returns an equivalent expression where this expression is defined as a variable that is used wherever necessary in the given expression.
This method is useful when
expr
contains multiple instances of this expression, since it avoids duplicate computation of this expression in the final pipeline.If
expr
is a simple expression such as aViewField
, no variable is defined andexpr
is directly returned.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] good_bboxes = (bbox_area > 0.25) & (bbox_area < 0.75) # Optimize the expression good_bboxes_opt = bbox_area.let_in(good_bboxes) # Contains predictions whose bounding box areas are in [0.25, 0.75] view = dataset.filter_labels("predictions", good_bboxes_opt) print(good_bboxes) print(good_bboxes_opt) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
expr – a
ViewExpression
 Returns

min
(value=None)¶ Returns the minimum value of either this expression, which must resolve to an array, or the minimum of this expression and the given value.
Missing or
None
values are ignored.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Adds a `min_area` property to the `predictions` field that # records the minimum prediction area in that sample view = dataset.set_field( "predictions.min_area", F("detections").map(bbox_area).min() ) print(view.bounds("predictions.min_area"))
 Parameters
value (None) – an optional value to compare to
 Returns

max
(value=None)¶ Returns the maximum value of either this expression, which must resolve to an array, or the maximum of this expression and the given value.
Missing or
None
values are ignored.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Adds a `max_area` property to the `predictions` field that # records the maximum prediction area in that sample view = dataset.set_field( "predictions.max_area", F("detections").map(bbox_area).max() ) print(view.bounds("predictions.max_area"))
 Parameters
value (None) – an optional value to compare to
 Returns

length
()¶ Computes the length of this expression, which must resolve to an array.
If this expression’s value is null or missing, zero is returned.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with at least 15 predicted objects view = dataset.match(F("predictions.detections").length() >= 15) print(dataset.count()) print(view.count())
 Returns

contains
(values, all=False)¶ Checks whether this expression, which must resolve to an array, contains any of the given values.
Pass
all=True
to require that this expression contains all of the given values.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") print(dataset.count()) # Only contains samples with a "cat" prediction view = dataset.match( F("predictions.detections.label").contains("cat") ) print(view.count()) # Only contains samples with "cat" or "dog" predictions view = dataset.match( F("predictions.detections.label").contains(["cat", "dog"]) ) print(view.count()) # Only contains samples with "cat" and "dog" predictions view = dataset.match( F("predictions.detections.label").contains(["cat", "dog"], all=True) ) print(view.count())
 Parameters
values – a value, iterable of values, or
ViewExpression
that resolves to an array of valuesall (False) – whether this expression must contain all (True) or any (False) of the given values
 Returns

is_subset
(values)¶ Checks whether this expression’s contents, which must resolve to an array, are a subset of the given array or array expression’s contents.
The arrays are treated as sets, so duplicate values are ignored.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b", "a", "b"], other_tags=["a", "b", "c"], ) ] ) print(dataset.values(F("tags").is_subset(F("other_tags")))) # [True]
 Parameters
values – an iterable of values or a
ViewExpression
that resolves to an array Returns

set_equals
(*args)¶ Checks whether this expression, which must resolve to an array, contains the same distinct values as each of the given array(s) or array expression(s).
The arrays are treated as sets, so all duplicates are ignored.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b", "a", "b"], other_tags=["a", "b", "b"], ) ] ) print(dataset.values(F("tags").set_equals(F("other_tags")))) # [True]
 Parameters
*args – one or more arrays or
ViewExpression
instances that resolve to array expressions Returns

unique
()¶ Returns an array containing the unique values in this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b", "a", "b"], ) ] ) print(dataset.values(F("tags").unique())) # [['a', 'b']]
 Returns

union
(*args)¶ Computes the set union of this expression, which must resolve to an array, and the given array(s) or array expression(s).
The arrays are treated as sets, so all duplicates are removed.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b"], other_tags=["a", "c"] ) ] ) print(dataset.values(F("tags").union(F("other_tags")))) # [['a', 'b', 'c']]
 Parameters
*args – one or more arrays or
ViewExpression
instances that resolve to array expressions Returns

intersection
(*args)¶ Computes the set intersection of this expression, which must resolve to an array, and the given array(s) or array expression(s).
The arrays are treated as sets, so all duplicates are removed.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b"], other_tags=["a", "c"] ) ] ) print(dataset.values(F("tags").intersection(F("other_tags")))) # [['a']]
 Parameters
*args – one or more arrays or
ViewExpression
instances that resolve to array expressions Returns

difference
(values)¶ Computes the set difference of this expression, which must resolve to an array, and the given array or array expression.
The arrays are treated as sets, so all duplicates are removed.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b"], other_tags=["a", "c"] ) ] ) print(dataset.values(F("tags").difference(F("other_tags")))) # [['b']]
 Parameters
values – an iterable of values or a
ViewExpression
that resolves to an array Returns

reverse
()¶ Reverses the order of the elements in the expression, which must resolve to an array.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") first_obj = F("predictions.detections")[0] last_obj = F("predictions.detections").reverse()[0] # Only contains samples whose first and last prediction have the # same label view = dataset.match( first_obj.apply(F("label")) == last_obj.apply(F("label")) ) print(dataset.count()) print(view.count())
 Returns

sort
(key=None, reverse=False)¶ Sorts this expression, which must resolve to an array.
If no
key
is provided, this array must contain elements whose BSON representation can be sorted by JavaScript’s.sort()
method.If a
key
is provided, the array must contain documents, which are sorted bykey
, which must be a field or embedded field.Examples:
# # Sort the tags of each sample in a dataset # import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="im1.jpg", tags=["z", "f", "p", "a"]), fo.Sample(filepath="im2.jpg", tags=["y", "q", "h", "d"]), fo.Sample(filepath="im3.jpg", tags=["w", "c", "v", "l"]), ] ) # Sort the `tags` of each sample view = dataset.set_field("tags", F("tags").sort()) print(view.first().tags) # # Sort the predictions in each sample of a dataset by `confidence` # import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") view = dataset.set_field( "predictions.detections", F("detections").sort(key="confidence", reverse=True) ) sample = view.first() print(sample.predictions.detections[0].confidence) print(sample.predictions.detections[1].confidence)
 Parameters
key (None) – an optional field or
embedded.field.name
to sort byreverse (False) – whether to sort in descending order
 Returns

filter
(expr)¶ Applies the given filter to the elements of this expression, which must resolve to an array.
The output array will only contain elements of the input array for which
expr
returnsTrue
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only include predictions with `confidence` of at least 0.9 view = dataset.set_field( "predictions.detections", F("detections").filter(F("confidence") > 0.9) ) print(view.bounds("predictions.detections.confidence"))
 Parameters
expr – a
ViewExpression
that returns a boolean Returns

map
(expr)¶ Applies the given expression to the elements of this expression, which must resolve to an array.
The output will be an array with the applied results.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Only include predictions with `confidence` of at least 0.9 view = dataset.set_field( "predictions.detections", F("detections").map(F().set_field("area", bbox_area)) ) print(view.bounds("predictions.detections.area"))
 Parameters
expr – a
ViewExpression
 Returns

reduce
(expr, init_val=0)¶ Applies the given reduction to this expression, which must resolve to an array, and returns the single value computed.
The provided
expr
must include theVALUE
expression to properly define the reduction.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F from fiftyone.core.expressions import VALUE # # Compute the number of keypoints in each sample of a dataset # dataset = fo.Dataset() dataset.add_sample( fo.Sample( filepath="image.jpg", keypoints=fo.Keypoints( keypoints=[ fo.Keypoint(points=[(0, 0), (1, 1)]), fo.Keypoint(points=[(0, 0), (1, 0), (1, 1), (0, 1)]), ] ) ) ) view = dataset.set_field( "keypoints.count", F("$keypoints.keypoints").reduce(VALUE + F("points").length()), ) print(view.first().keypoints.count) # # Generate a `list,of,labels` for the `predictions` of each sample # dataset = foz.load_zoo_dataset("quickstart") join_labels = F("detections").reduce( VALUE.concat(",", F("label")), init_val="" ).lstrip(",") view = dataset.set_field("predictions.labels", join_labels) print(view.first().predictions.labels)
 Parameters
expr – a
ViewExpression
defining the reduction expression to apply. Must contain theVALUE
expressioninit_val (0) – an initial value for the reduction
 Returns

prepend
(value)¶ Prepends the given value to this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["b", "c"]), fo.Sample(filepath="image2.jpg", tags=["b", "c"]), ] ) # Adds the "a" tag to each sample view = dataset.set_field("tags", F("tags").prepend("a")) print(view.first().tags)
 Parameters
value – the value or
ViewExpression
 Returns

append
(value)¶ Appends the given value to this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b"]), fo.Sample(filepath="image2.jpg", tags=["a", "b"]), ] ) # Appends the "c" tag to each sample view = dataset.set_field("tags", F("tags").append("c")) print(view.first().tags)
 Parameters
value – the value or
ViewExpression
 Returns

insert
(index, value)¶ Inserts the value before the given index in this expression, which must resolve to an array.
If
index <= 0
, the value is prepended to this array. Ifindex >= self.length()
, the value is appended to this array.Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "c"]), fo.Sample(filepath="image2.jpg", tags=["a", "c"]), ] ) # Adds the "ready" tag to each sample view = dataset.set_field("tags", F("tags").insert(1, "b")) print(view.first().tags)
 Parameters
index – the index at which to insert the value
value – the value or
ViewExpression
 Returns

extend
(*args)¶ Concatenates the given array(s) or array expression(s) to this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b"]), fo.Sample(filepath="image2.jpg", tags=["a", "b"]), ] ) # Adds the "c" and "d" tags to each sample view = dataset.set_field("tags", F("tags").extend(["c", "d"])) print(view.first().tags)
 Parameters
*args – one or more arrays or
ViewExpression
instances that resolve to array expressions Returns

sum
()¶ Returns the sum of the values in this expression, which must resolve to a numeric array.
Missing, nonnumeric, or
None
valued elements are ignored.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add a field to each `predictions` object that records the total # confidence of the predictions view = dataset.set_field( "predictions.total_conf", F("detections").map(F("confidence")).sum() ) print(view.bounds("predictions.total_conf"))
 Returns

mean
()¶ Returns the average value in this expression, which must resolve to a numeric array.
Missing or
None
valued elements are ignored.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add a field to each `predictions` object that records the average # confidence of the predictions view = dataset.set_field( "predictions.conf_mean", F("detections").map(F("confidence")).mean() ) print(view.bounds("predictions.conf_mean"))
 Returns

std
(sample=False)¶ Returns the standard deviation of the values in this expression, which must resolve to a numeric array.
Missing or
None
valued elements are ignored.By default, the population standard deviation is returned. If you wish to compute the sample standard deviation instead, set
sample=True
.See https://en.wikipedia.org/wiki/Standard_deviation#Estimation for more information on population (biased) vs sample (unbiased) standard deviation.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add a field to each `predictions` object that records the # standard deviation of the confidences view = dataset.set_field( "predictions.conf_std", F("detections").map(F("confidence")).std() ) print(view.bounds("predictions.conf_std"))
 Parameters
sample (False) – whether to compute the sample standard deviation rather than the population standard deviation
 Returns

join
(delimiter)¶ Joins the elements of this expression, which must resolve to a string array, by the given delimiter.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Generate a `list,of,labels` for the `predictions` of each sample view = dataset.set_field( "predictions.labels", F("detections").map(F("label")).join(",") ) print(view.first().predictions.labels)
 Parameters
delimiter – the delimiter string
 Returns

substr
(start=None, end=None, count=None)¶ Extracts the specified substring from this expression, which must resolve to a string.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Truncate the `label` of each prediction to 3 characters truncate_label = F().set_field("label", F("label").substr(count=3)) view = dataset.set_field( "predictions.detections", F("detections").map(truncate_label), ) print(view.distinct("predictions.detections.label"))
 Parameters
start (None) – the starting index of the substring. If negative, specifies an offset from the end of the string
end (None) – the ending index of the substring. If negative, specifies an offset from the end of the string
count (None) – the substring length to extract. If
None
, the rest of the string is returned
 Returns

strlen
()¶ Computes the length of this expression, which must resolve to a string.
If this expression’s value is null or missing, zero is returned.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Records the length of each predicted object's `label` label_len = F().set_field("label_len", F("label").strlen()) view = dataset.set_field( "predictions.detections", F("detections").map(label_len), ) print(view.bounds("predictions.detections.label_len"))
 Returns

lower
()¶ Converts this expression, which must resolve to a string, to lowercase.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Converts all tags to lowercase transform_tag = F().lower() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Returns

upper
()¶ Converts this expression, which must resolve to a string, to uppercase.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Converts all tags to uppercase transform_tag = F().upper() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Returns

concat
(*args)¶ Concatenates the given string(s) to this expression, which must resolve to a string.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Appends "tag" to all tags transform_tag = F().concat("tag") view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
*args – one or more strings or string
ViewExpression
instancesbefore (False) – whether to position
args
before this string in the output string
 Returns

strip
(chars=None)¶ Removes whitespace characters from the beginning and end of this expression, which must resolve to a string.
If
chars
is provided, those characters are removed instead of whitespace.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewExpression as E from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Adds and then strips whitespace from each tag transform_tag = E(" ").concat(F(), " ").rstrip() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
chars (None) – an optional string or
ViewExpression
resolving to a string expression specifying characters to remove Returns

lstrip
(chars=None)¶ Removes whitespace characters from the beginning of this expression, which must resolve to a string.
If
chars
is provided, those characters are removed instead of whitespace.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewExpression as E from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Adds and then strips whitespace from the beginning of each tag transform_tag = E(" ").concat(F()).lstrip() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
chars (None) – an optional string or
ViewExpression
resolving to a string expression specifying characters to remove Returns

rstrip
(chars=None)¶ Removes whitespace characters from the end of this expression, which must resolve to a string.
If
chars
is provided, those characters are removed instead of whitespace.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Adds and then strips whitespace from the end of each tag transform_tag = F().concat(" ").rstrip() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
chars (None) – an optional string or
ViewExpression
resolving to a string expression specifying characters to remove Returns

replace
(old, new)¶ Replaces all occurances of
old
withnew
in this expression, which must resolve to a string.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Replaces "val" with "VAL" in each tag transform_tag = F().replace("val", "VAL") view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
old – a string or
ViewExpression
resolving to a string expression specifying the substring to replacenew – a string or
ViewExpression
resolving to a string expression specifying the replacement value
 Returns

re_match
(regex, options=None)¶ Performs a regular expression pattern match on this expression, which must resolve to a string.
The output of the expression will be
True
if the pattern matches andFalse
otherwise.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # # Get samples whose images are JPEGs # view = dataset.match(F("filepath").re_match("\.jpg$")) print(view.count()) print(view.first().filepath) # # Get samples whose images are in the "/Users" directory # view = dataset.match(F("filepath").re_match("^/Users/")) print(view.count()) print(view.first().filepath)
 Parameters
 Returns

starts_with
(str_or_strs, case_sensitive=True)¶ Determines whether this expression, which must resolve to a string, starts with the given string or string(s).
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose images are in "/Users" or "/home" directories view = dataset.match(F("filepath").starts_with(("/Users", "/home")) print(view.count()) print(view.first().filepath)
 Parameters
str_or_strs – a string or iterable of strings
case_sensitive (True) – whether to perform a case sensitive match
 Returns

ends_with
(str_or_strs, case_sensitive=True)¶ Determines whether this expression, which must resolve to a string, ends with the given string or string(s).
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose images are JPEGs or PNGs view = dataset.match(F("filepath").ends_with((".jpg", ".png"))) print(view.count()) print(view.first().filepath)
 Parameters
str_or_strs – a string or iterable of strings
case_sensitive (True) – whether to perform a case sensitive match
 Returns

contains_str
(str_or_strs, case_sensitive=True)¶ Determines whether this expression, which must resolve to a string, contains the given string or string(s).
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains predictions whose `label` contains "be" view = dataset.filter_labels( "predictions", F("label").contains_str("be") ) print(view.distinct("predictions.detections.label"))
 Parameters
str_or_strs – a string or iterable of strings
case_sensitive (True) – whether to perform a case sensitive match
 Returns

matches_str
(str_or_strs, case_sensitive=True)¶ Determines whether this expression, which must resolve to a string, exactly matches the given string or string(s).
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains predictions whose `label` is "cat" or "dog", case # insensitive view = dataset.map_labels( "predictions", {"cat": "CAT", "dog": "DOG"} ).filter_labels( "predictions", F("label").matches_str(("cat", "dog"), case_sensitive=False) ) print(view.distinct("predictions.detections.label"))
 Parameters
str_or_strs – a string or iterable of strings
case_sensitive (True) – whether to perform a case sensitive match
 Returns

split
(delimiter, maxsplit=None)¶ Splits this expression, which must resolve to a string, by the given delimiter.
The result is a string array that contains the chunks with the delimiter removed. If the delimiter is not found, this full string is returned as a single element array.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add "good" to the first tag and then split on "" to create two # tags for each sample view = dataset.set_field( "tags", F("tags")[0].concat("good").split("") ) print(view.first().tags)
 Parameters
delimiter – the delimiter string or
ViewExpression
resolving to a string expressionmaxsplit (None) – a maximum number of splits to perform, from the left
 Returns

rsplit
(delimiter, maxsplit=None)¶ Splits this expression, which must resolve to a string, by the given delimiter.
If the number of chunks exceeds
maxsplit
, splits are only performed on the lastmaxsplit
occurances of the delimiter.The result is a string array that contains the chunks with the delimiter removed. If the delimiter is not found, this full string is returned as a single element array.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add "okgo" to the first tag and then split once on "" from the # right to create two tags for each sample view = dataset.set_field( "tags", F("tags")[0].concat("okgo").rsplit("", 1) ) print(view.first().tags)
 Parameters
delimiter – the delimiter string or
ViewExpression
resolving to a string expressionmaxsplit (None) – a maximum number of splits to perform, from the right
 Returns

millisecond
()¶ Returns the millisecond portion of this date expression (in UTC) as an integer between 0 and 999.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 0, 1000), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 0, 2000), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 0, 3000), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 0, 4000), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the millisecond portion of the dates in the dataset print(dataset.values(F("created_at").millisecond())) # Samples with even milliseconds view = dataset.match(F("created_at").millisecond() % 2 == 0) print(len(view))
 Returns

second
()¶ Returns the second portion of this date expression (in UTC) as a number between 0 and 59.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the second portion of the dates in the dataset print(dataset.values(F("created_at").second())) # Samples with even seconds view = dataset.match(F("created_at").second() % 2 == 0) print(len(view))
 Returns

minute
()¶ Returns the minute portion of this date expression (in UTC) as a number between 0 and 59.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the minute portion of the dates in the dataset print(dataset.values(F("created_at").minute())) # Samples with even minutes view = dataset.match(F("created_at").minute() % 2 == 0) print(len(view))
 Returns

hour
()¶ Returns the hour portion of this date expression (in UTC) as a number between 0 and 23.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the hour portion of the dates in the dataset print(dataset.values(F("created_at").hour())) # Samples with even hours view = dataset.match(F("created_at").hour() % 2 == 0) print(len(view))
 Returns

day_of_week
()¶ Returns the day of the week of this date expression (in UTC) as a number between 1 (Sunday) and 7 (Saturday).
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 4), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 5), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 6), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 7), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the days of the week for the dataset print(dataset.values(F("created_at").day_of_week())) # Samples with even days of the week view = dataset.match(F("created_at").day_of_week() % 2 == 0) print(len(view))
 Returns

day_of_month
()¶ Returns the day of the month of this date expression (in UTC) as a number between 1 and 31.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the days of the month for the dataset print(dataset.values(F("created_at").day_of_month())) # Samples with even days of the month view = dataset.match(F("created_at").day_of_month() % 2 == 0) print(len(view))
 Returns

day_of_year
()¶ Returns the day of the year of this date expression (in UTC) as a number between 1 and 366.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the days of the year for the dataset print(dataset.values(F("created_at").day_of_year())) # Samples with even days of the year view = dataset.match(F("created_at").day_of_year() % 2 == 0) print(len(view))
 Returns

week
()¶ Returns the week of the year of this date expression (in UTC) as a number between 0 and 53.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 2, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 3, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 4, 1), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the weeks of the year for the dataset print(dataset.values(F("created_at").week())) # Samples with even months of the week view = dataset.match(F("created_at").week() % 2 == 0) print(len(view))
 Returns

month
()¶ Returns the month of this date expression (in UTC) as a number between 1 and 12.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 2, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 3, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 4, 1), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the months of the year for the dataset print(dataset.values(F("created_at").month())) # Samples from even months of the year view = dataset.match(F("created_at").month() % 2 == 0) print(len(view))
 Returns

year
()¶ Returns the year of this date expression (in UTC).
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1971, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1972, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1973, 1, 1), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the years for the dataset print(dataset.values(F("created_at").year())) # Samples from even years view = dataset.match(F("created_at").year() % 2 == 0) print(len(view))
 Returns

static
literal
(value)¶ Returns an expression representing the given value without parsing.
See this page for more information on when this method is reqiured.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add the "$money" tag to each sample # The "$" character ordinarily has special meaning, so we must wrap # it in `literal()` in order to add it via this method view = dataset.set_field( "tags", F("tags").append(F.literal("$money")) ) print(view.first().tags)
 Parameters
value – a value
 Returns

static
rand
()¶ Returns an expression that generates a uniform random float in
[0, 1]
each time it is called.Warning
This expression will generate new values each time it is used, so you likely do not want to use it to construct dataset views, since such views would produce different outputs each time they are used.
A typical usage for this expression is in conjunction with
fiftyone.core.view.DatasetView.set_field()
andfiftyone.core.view.DatasetView.save()
to populate a randomized field on a dataset.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewExpression as E dataset = foz.load_zoo_dataset("quickstart").clone() # # Populate a new `rand` field with random numbers # dataset.add_sample_field("rand", fo.FloatField) dataset.set_field("rand", E.rand()).save("rand") print(dataset.bounds("rand")) # # Create a view that contains a different 10%% of the dataset each # time it is used # view = dataset.match(E.rand() < 0.1) print(view.first().id) print(view.first().id) # probably different!
 Returns

static
randn
()¶ Returns an expression that generates a sample from the standard Gaussian distribution each time it is called.
Warning
This expression will generate new values each time it is used, so you likely do not want to use it to construct dataset views, since such views would produce different outputs each time they are used.
A typical usage for this expression is in conjunction with
fiftyone.core.view.DatasetView.set_field()
andfiftyone.core.view.DatasetView.save()
to populate a randomized field on a dataset.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewExpression as E dataset = foz.load_zoo_dataset("quickstart").clone() # # Populate a new `randn` field with random numbers # dataset.add_sample_field("randn", fo.FloatField) dataset.set_field("randn", E.randn()).save("randn") print(dataset.bounds("randn")) # # Create a view that contains a different 50%% of the dataset each # time it is used # view = dataset.match(E.randn() < 0) print(view.first().id) print(view.first().id) # probably different!
 Returns

static
any
(exprs)¶ Checks whether any of the given expressions evaluate to True.
If no expressions are provided, returns False.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Create a view that only contains predictions that are "cat" or # highly confident is_cat = F("label") == "cat" is_confident = F("confidence") > 0.95 view = dataset.filter_labels( "predictions", F.any([is_cat, is_confident]) ) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
exprs – a
ViewExpression
or iterable ofViewExpression
instances Returns

static
all
(exprs)¶ Checks whether all of the given expressions evaluate to True.
If no expressions are provided, returns True.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Create a view that only contains predictions that are "cat" and # highly confident is_cat = F("label") == "cat" is_confident = F("confidence") > 0.95 view = dataset.filter_labels( "predictions", F.all([is_cat, is_confident]) ) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
exprs – a
ViewExpression
or iterable ofViewExpression
instances Returns

static
range
(start, stop=None)¶ Returns an array expression containing the sequence of integers from the specified start (inclusive) to stop (exclusive).
If
stop
is provided, returns[start, start + 1, ..., stop  1]
.If no
stop
is provided, returns[0, 1, ..., start  1]
.Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b", "c"]), fo.Sample(filepath="image2.jpg", tags=["y", "z"]), ] ) # Populates an `ints` field based on the number of `tags` dataset.add_sample_field("ints", fo.ListField) view = dataset.set_field("ints", F.range(F("tags").length())) print(view.first())
 Parameters
start – the starting value, or stopping value if no
stop
is providedstop (None) – the stopping value, if both input arguments are provided
 Returns

static
enumerate
(array, start=0)¶ Returns an array of
[index, element]
pairs enumerating the elements of the given expression, which must resolve to an array.Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b", "c"]), fo.Sample(filepath="image2.jpg", tags=["y", "z"]), ] ) # Populates an `enumerated_tags` field with the enumerated `tag` dataset.add_sample_field("enumerated_tags", fo.ListField) view = dataset.set_field("enumerated_tags", F.enumerate(F("tags"))) print(view.first())
 Parameters
array – a
ViewExpression
that resolves to an arraystart (0) – the starting enumeration index to use
 Returns

static
zip
(*args, use_longest=False, defaults=None)¶ Zips the given expressions, which must resolve to arrays, into an array whose ith element is an array containing the ith element from each input array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b", "c"], ints=[1, 2, 3, 4, 5], ), fo.Sample( filepath="image2.jpg", tags=["y", "z"], ints=[25, 26, 27, 28], ), ] ) dataset.add_sample_field("tags_ints", fo.ListField) # Populates an `tags_ints` field with the zipped `tags` and `ints` view = dataset.set_field("tags_ints", F.zip(F("tags"), F("ints"))) print(view.first()) # Same as above but use the longest array to determine output size view = dataset.set_field( "tags_ints", F.zip(F("tags"), F("ints"), use_longest=True, defaults=("", 0)) ) print(view.first())
 Parameters
*args – one or more arrays or
ViewExpression
instances resolving to arraysuse_longest (False) – whether to use the longest array to determine the number of elements in the output array. By default, the length of the shortest array is used
defaults (None) – an optional array of default values of same length as
*args
to use whenuse_longest == True
and the input arrays are of different lengths. If no defaults are provided anduse_longest == True
, then missing values are set toNone
 Returns


class
fiftyone.core.expressions.
ViewField
(name=None)¶ Bases:
fiftyone.core.expressions.ViewExpression
A
ViewExpression
that refers to a field or embedded field of a document.You can use dot notation to refer to subfields of embedded objects within fields.
When you create a
ViewField
using a string field likeViewField("embedded.field.name")
, the meaning of this field is interpreted relative to the context in which theViewField
object is used. For example, when passed to theViewExpression.map()
method, this object will refer to theembedded.field.name
object of the array element being processed.In other cases, you may wish to create a
ViewField
that always refers to the root document. You can do this by prepending"$"
to the name of the field, as inViewField("$embedded.field.name")
.Examples:
from fiftyone import ViewField as F # Reference the root of the current context F() # Reference the `ground_truth` field in the current context F("ground_truth") # Reference the `label` field of the `ground_truth` object in the # current context F("ground_truth.label") # Reference the root document in any context F("$") # Reference the `label` field of the root document in any context F("$label") # Reference the `label` field of the `ground_truth` object in the root # document in any context F("$ground_truth.label")

__eq__
(other)¶ Determines whether this expression is equal to the given value or expression,
self == other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset( "cifar10", split="test", max_samples=500, shuffle=True ) # Get samples whose ground truth `label` is "airplane" view = dataset.match(F("ground_truth.label") == "airplane") print(view.distinct("ground_truth.label"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__ge__
(other)¶ Determines whether this expression is greater than or equal to the given value or expression,
self >= other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 view = dataset.match(F("uniqueness") >= 0.5) print(view.bounds("uniqueness"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__gt__
(other)¶ Determines whether this expression is greater than the given value or expression,
self >= other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is > 0.5 view = dataset.match(F("uniqueness") > 0.5) print(view.bounds("uniqueness"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__le__
(other)¶ Determines whether this expression is less than or equal to the given value or expression,
self <= other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is <= 0.5 view = dataset.match(F("uniqueness") <= 0.5) print(view.bounds("uniqueness"))
 Parameters
other – a literal value or
ViewExpression
other – a
ViewExpression
or a python primitive understood by MongoDB
 Returns

__lt__
(other)¶ Determines whether this expression is less than the given value or expression,
self <= other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is < 0.5 view = dataset.match(F("uniqueness") < 0.5) print(view.bounds("uniqueness"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__ne__
(other)¶ Determines whether this expression is not equal to the given value or expression,
self != other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset( "cifar10", split="test", max_samples=500, shuffle=True ) # Get samples whose ground truth `label` is NOT "airplane" view = dataset.match(F("ground_truth.label") != "airplane") print("airplane" in view.distinct("ground_truth.label"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__and__
(other)¶ Computes the logical AND of this expression and the given value or expression,
self & other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains predictions with label "cat" and confidence > 0.9 view = dataset.filter_labels( "predictions", (F("label") == "cat") & (F("confidence") > 0.9) ) print(view.count_values("predictions.detections.label")) print(view.bounds("predictions.detections.confidence"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__invert__
()¶ Inverts this expression,
~self
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add a new field to one sample sample = dataset.first() sample["new_field"] = ["hello", "there"] sample.save() # Get samples that do NOT have a value for `new_field` view = dataset.match(~F("new_field").exists()) print(len(view))
 Returns

__or__
(other)¶ Computes the logical OR of this expression and the given value or expression,
self  other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains predictions with label "cat" or confidence > 0.9 view = dataset.filter_labels( "predictions", (F("label") == "cat")  (F("confidence") > 0.9) ) print(view.count_values("predictions.detections.label")) print(view.bounds("predictions.detections.confidence"))
 Parameters
other – a literal value or
ViewExpression
 Returns

__abs__
()¶ Computes the absolute value of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match(abs(F("uniqueness")  0.5) < 0.25) print(view.bounds("uniqueness"))
 Returns

__add__
(other)¶ Adds the given value to this expression, which must resolve to a numeric value,
self + other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format manhattan_dist = F("bounding_box")[0] + F("bounding_box")[1] # Only contains predictions whose bounding boxes' upper left corner # is a Manhattan distance of at least 1 from the origin dataset.filter_labels("predictions, manhattan_dist > 1) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
other – a number or
ViewExpression
 Returns

__ceil__
()¶ Computes the ceiling of this expression, which must resolve to a numeric value.
Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match(math.ceil(F("uniqueness") + 0.5) == 2) print(view.bounds("uniqueness"))
 Returns

__floor__
()¶ Computes the floor of this expression, which must resolve to a numeric value.
Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match(math.floor(F("uniqueness") + 0.5) == 1) print(view.bounds("uniqueness"))
 Returns

__round__
(place=0)¶ Rounds this expression, which must resolve to a numeric value, at the given decimal place.
Positive values of
place
will round toplace
decimal places:place=2: 1234.5678 > 1234.57
Negative values of
place
will round digits left of the decimal:place=2: 1234.5678 > 1200
 Parameters
place (0) – the decimal place at which to round. Must be an integer in range
(20, 100)
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match(round(2 * F("uniqueness")) == 1) print(view.bounds("uniqueness"))
 Returns

__mod__
(other)¶ Computes the modulus of this expression, which must resolve to a numeric value,
self % other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with an even number of predictions view = dataset.match( (F("predictions.detections").length() % 2) == 0 ) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
other – a number or
ViewExpression
 Returns

__mul__
(other)¶ Computes the product of the given value and this expression, which must resolve to a numeric value,
self * other
.Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Only contains predictions whose bounding box area is > 0.2 view = dataset.filter_labels("predictions", bbox_area > 0.2)
 Parameters
other – a number or
ViewExpression
 Returns

__pow__
(power, modulo=None)¶ Raises this expression, which must resolve to a numeric value, to the given power,
self ** power
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format center_dist = ( (F("bounding_box")[0] + 0.5 * F("bounding_box")[2]  0.5) ** 2 + (F("bounding_box")[1] + 0.5 * F("bounding_box")[3]  0.5) ** 2 ).sqrt() # Only contains predictions whose bounding box center is a distance # of at most 0.02 from the center of the image view = dataset.select_fields("predictions").filter_labels( "predictions", center_dist < 0.02 ) session = fo.launch_app(view=view)
 Parameters
power – the power
 Returns

__sub__
(other)¶ Subtracts the given value from this expression, which must resolve to a numeric value,
self  other
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") dataset.compute_metadata() # Bboxes are in [topleftx, toplefty, width, height] format rectangleness = abs( F("$metadata.width") * F("bounding_box")[2]  F("$metadata.height") * F("bounding_box")[3] ) # Only contains predictions whose bounding boxes are within 1 pixel # of being square view = ( dataset .select_fields("predictions") .filter_labels("predictions", rectangleness <= 1) ) session = fo.launch_app(view=view)
 Parameters
other – a number or
ViewExpression
 Returns

__truediv__
(other)¶ Divides this expression, which must resolve to a numeric value, by the given value,
self / other
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") dataset.compute_metadata() # Bboxes are in [topleftx, toplefty, width, height] format aspect_ratio = ( (F("$metadata.width") * F("bounding_box")[2]) / (F("$metadata.height") * F("bounding_box")[3]) ) # Only contains predictions whose aspect ratio is > 2 view = ( dataset .select_fields("predictions") .filter_labels("predictions", aspect_ratio > 2) ) session = fo.launch_app(view=view)
 Parameters
other – a number or
ViewExpression
 Returns

__getitem__
(idx_or_slice)¶ Returns the element or slice of this expression, which must resolve to an array.
All of the typical slicing operations are supported, except for specifying a nonunit step:
expr[3] # the fourth element expr[1] # the last element expr[:10] # the first (up to) 10 elements expr[3:] # the last (up to) 3 elements expr[3:10] # the fourth through tenth elements
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Only contains objects in the `predictions` field with area > 0.2 view = dataset.filter_labels("predictions", bbox_area > 0.2) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
idx_or_slice – the index or slice
 Returns
 Parameters
name (None) – the name of the field, with an optional “$” preprended if you wish to freeze this field to the root document
Methods:
abs
()Computes the absolute value of this expression, which must resolve to a numeric value.
all
(exprs)Checks whether all of the given expressions evaluate to True.
any
(exprs)Checks whether any of the given expressions evaluate to True.
append
(value)Appends the given value to this expression, which must resolve to an array.
apply
(expr)Applies the given expression to this expression.
arccos
()Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians.
arccosh
()Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
arcsin
()Computes the inverse sine of this expression, which must resolve to a numeric value, in radians.
arcsinh
()Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
arctan
()Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians.
arctanh
()Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
cases
(mapping[, default])Applies a case statement to this expression, which effectively computes the following pseudocode.
ceil
()Computes the ceiling of this expression, which must resolve to a numeric value.
concat
(*args)Concatenates the given string(s) to this expression, which must resolve to a string.
contains
(values[, all])Checks whether this expression, which must resolve to an array, contains any of the given values.
contains_str
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, contains the given string or string(s).
cos
()Computes the cosine of this expression, which must resolve to a numeric value, in radians.
cosh
()Computes the hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
Returns the day of the month of this date expression (in UTC) as a number between 1 and 31.
Returns the day of the week of this date expression (in UTC) as a number between 1 (Sunday) and 7 (Saturday).
Returns the day of the year of this date expression (in UTC) as a number between 1 and 366.
difference
(values)Computes the set difference of this expression, which must resolve to an array, and the given array or array expression.
ends_with
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, ends with the given string or string(s).
enumerate
(array[, start])Returns an array of
[index, element]
pairs enumerating the elements of the given expression, which must resolve to an array.exists
([bool])Determines whether this expression, which must resolve to a field, exists and is not None.
exp
()Raises Euler’s number to this expression, which must resolve to a numeric value.
extend
(*args)Concatenates the given array(s) or array expression(s) to this expression, which must resolve to an array.
filter
(expr)Applies the given filter to the elements of this expression, which must resolve to an array.
floor
()Computes the floor of this expression, which must resolve to a numeric value.
hour
()Returns the hour portion of this date expression (in UTC) as a number between 0 and 23.
if_else
(true_expr, false_expr)Returns either
true_expr
orfalse_expr
depending on the value of this expression, which must resolve to a boolean.insert
(index, value)Inserts the value before the given index in this expression, which must resolve to an array.
intersection
(*args)Computes the set intersection of this expression, which must resolve to an array, and the given array(s) or array expression(s).
is_array
()Determines whether this expression is an array.
is_in
(values)Creates an expression that returns a boolean indicating whether
self in values
.Determines whether this expression refers to a missing field.
is_null
()Determines whether this expression is null.
Determines whether this expression is a number.
Determines whether this expression is a string.
is_subset
(values)Checks whether this expression’s contents, which must resolve to an array, are a subset of the given array or array expression’s contents.
join
(delimiter)Joins the elements of this expression, which must resolve to a string array, by the given delimiter.
length
()Computes the length of this expression, which must resolve to an array.
let_in
(expr)Returns an equivalent expression where this expression is defined as a variable that is used wherever necessary in the given expression.
literal
(value)Returns an expression representing the given value without parsing.
ln
()Computes the natural logarithm of this expression, which must resolve to a numeric value.
log
(base)Computes the logarithm base
base
of this expression, which must resolve to a numeric value.log10
()Computes the logarithm base 10 of this expression, which must resolve to a numeric value.
lower
()Converts this expression, which must resolve to a string, to lowercase.
lstrip
([chars])Removes whitespace characters from the beginning of this expression, which must resolve to a string.
map
(expr)Applies the given expression to the elements of this expression, which must resolve to an array.
map_values
(mapping)Replaces this expression with the corresponding value in the provided mapping dict, if it is present as a key.
matches_str
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, exactly matches the given string or string(s).
max
([value])Returns the maximum value of either this expression, which must resolve to an array, or the maximum of this expression and the given value.
mean
()Returns the average value in this expression, which must resolve to a numeric array.
Returns the millisecond portion of this date expression (in UTC) as an integer between 0 and 999.
min
([value])Returns the minimum value of either this expression, which must resolve to an array, or the minimum of this expression and the given value.
minute
()Returns the minute portion of this date expression (in UTC) as a number between 0 and 59.
month
()Returns the month of this date expression (in UTC) as a number between 1 and 12.
pow
(power)Raises this expression, which must resolve to a numeric value, to the given power,
self ** power
.prepend
(value)Prepends the given value to this expression, which must resolve to an array.
rand
()Returns an expression that generates a uniform random float in
[0, 1]
each time it is called.randn
()Returns an expression that generates a sample from the standard Gaussian distribution each time it is called.
range
(start[, stop])Returns an array expression containing the sequence of integers from the specified start (inclusive) to stop (exclusive).
re_match
(regex[, options])Performs a regular expression pattern match on this expression, which must resolve to a string.
reduce
(expr[, init_val])Applies the given reduction to this expression, which must resolve to an array, and returns the single value computed.
replace
(old, new)Replaces all occurances of
old
withnew
in this expression, which must resolve to a string.reverse
()Reverses the order of the elements in the expression, which must resolve to an array.
round
([place])Rounds this expression, which must resolve to a numeric value, at the given decimal place.
rsplit
(delimiter[, maxsplit])Splits this expression, which must resolve to a string, by the given delimiter.
rstrip
([chars])Removes whitespace characters from the end of this expression, which must resolve to a string.
second
()Returns the second portion of this date expression (in UTC) as a number between 0 and 59.
set_equals
(*args)Checks whether this expression, which must resolve to an array, contains the same distinct values as each of the given array(s) or array expression(s).
set_field
(field, value_or_expr[, relative])Sets the specified field or embedded field of this expression, which must resolve to a document, to the given value or expression.
sin
()Computes the sine of this expression, which must resolve to a numeric value, in radians.
sinh
()Computes the hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
sort
([key, reverse])Sorts this expression, which must resolve to an array.
split
(delimiter[, maxsplit])Splits this expression, which must resolve to a string, by the given delimiter.
sqrt
()Computes the square root of this expression, which must resolve to a numeric value.
starts_with
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, starts with the given string or string(s).
std
([sample])Returns the standard deviation of the values in this expression, which must resolve to a numeric array.
strip
([chars])Removes whitespace characters from the beginning and end of this expression, which must resolve to a string.
strlen
()Computes the length of this expression, which must resolve to a string.
substr
([start, end, count])Extracts the specified substring from this expression, which must resolve to a string.
sum
()Returns the sum of the values in this expression, which must resolve to a numeric array.
switch
(mapping[, default])Applies a switch statement to this expression, which effectively computes the given pseudocode.
tan
()Computes the tangent of this expression, which must resolve to a numeric value, in radians.
tanh
()Computes the hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
to_bool
()Converts the expression to a boolean value.
to_date
()Converts the expression to a date value.
Converts the expression to a double precision value.
to_int
()Converts the expression to an integer value.
to_mongo
([prefix])Returns a MongoDB representation of the field.
Converts the expression to a string value.
trunc
([place])Truncates this expression, which must resolve to a numeric value, at the specified decimal place.
type
()Returns the type string of this expression.
union
(*args)Computes the set union of this expression, which must resolve to an array, and the given array(s) or array expression(s).
unique
()Returns an array containing the unique values in this expression, which must resolve to an array.
upper
()Converts this expression, which must resolve to a string, to uppercase.
week
()Returns the week of the year of this date expression (in UTC) as a number between 0 and 53.
year
()Returns the year of this date expression (in UTC).
zip
(*args[, use_longest, defaults])Zips the given expressions, which must resolve to arrays, into an array whose ith element is an array containing the ith element from each input array.
Attributes:
Whether this expression’s prefix is frozen.

to_mongo
(prefix=None)¶ Returns a MongoDB representation of the field.
 Parameters
prefix (None) – an optional prefix to prepend to the field name
 Returns
a string

abs
()¶ Computes the absolute value of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match((F("uniqueness")  0.5).abs() < 0.25) print(view.bounds("uniqueness"))
 Returns

static
all
(exprs)¶ Checks whether all of the given expressions evaluate to True.
If no expressions are provided, returns True.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Create a view that only contains predictions that are "cat" and # highly confident is_cat = F("label") == "cat" is_confident = F("confidence") > 0.95 view = dataset.filter_labels( "predictions", F.all([is_cat, is_confident]) ) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
exprs – a
ViewExpression
or iterable ofViewExpression
instances Returns

static
any
(exprs)¶ Checks whether any of the given expressions evaluate to True.
If no expressions are provided, returns False.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Create a view that only contains predictions that are "cat" or # highly confident is_cat = F("label") == "cat" is_confident = F("confidence") > 0.95 view = dataset.filter_labels( "predictions", F.any([is_cat, is_confident]) ) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
exprs – a
ViewExpression
or iterable ofViewExpression
instances Returns

append
(value)¶ Appends the given value to this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b"]), fo.Sample(filepath="image2.jpg", tags=["a", "b"]), ] ) # Appends the "c" tag to each sample view = dataset.set_field("tags", F("tags").append("c")) print(view.first().tags)
 Parameters
value – the value or
ViewExpression
 Returns

apply
(expr)¶ Applies the given expression to this expression.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples with `uniqueness` in [0.25, 0.75] view = dataset.match( F("uniqueness").apply((F() > 0.25) & (F() < 0.75)) ) print(view.bounds("uniqueness"))
 Parameters
expr – a
ViewExpression
 Returns

arccos
()¶ Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arccos()` view = dataset.match(F("uniqueness").arccos() <= np.arccos(0.5)) print(view.bounds("uniqueness"))
 Returns

arccosh
()¶ Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arccosh()` view = dataset.match((1 + F("uniqueness")).arccosh() >= np.arccosh(1.5)) print(view.bounds("uniqueness"))
 Returns

arcsin
()¶ Computes the inverse sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arcsin()` view = dataset.match(F("uniqueness").arcsin() >= np.arcsin(0.5)) print(view.bounds("uniqueness"))
 Returns

arcsinh
()¶ Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arcsinh()` view = dataset.match(F("uniqueness").arcsinh() >= np.arcsinh(0.5)) print(view.bounds("uniqueness"))
 Returns

arctan
()¶ Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arctan()` view = dataset.match(F("uniqueness").arctan() >= np.arctan(0.5)) print(view.bounds("uniqueness"))
 Returns

arctanh
()¶ Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arctanh()` view = dataset.match(F("uniqueness").arctanh() >= np.arctanh(0.5)) print(view.bounds("uniqueness"))
 Returns

cases
(mapping, default=None)¶ Applies a case statement to this expression, which effectively computes the following pseudocode:
for key, value in mapping.items(): if self == key: return value if default is not None: return default
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.75 to None view = dataset.set_field( "uniqueness", (F("uniqueness") > 0.75).if_else(F("uniqueness"), None) ) # Map numeric `uniqueness` values to 1 and null values to 0 cases_view = view.set_field( "uniqueness", F("uniqueness").type().cases({"double": 1, "null": 0}), ) print(cases_view.count_values("uniqueness"))
 Parameters
mapping – a dict mapping literals or
ViewExpression
keys to literal orViewExpression
valuesdefault (None) – an optional literal or
ViewExpression
to return if none of the switch branches are taken
 Returns

ceil
()¶ Computes the ceiling of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match((F("uniqueness") + 0.5).ceil() == 2) print(view.bounds("uniqueness"))
 Returns

concat
(*args)¶ Concatenates the given string(s) to this expression, which must resolve to a string.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Appends "tag" to all tags transform_tag = F().concat("tag") view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
*args – one or more strings or string
ViewExpression
instancesbefore (False) – whether to position
args
before this string in the output string
 Returns

contains
(values, all=False)¶ Checks whether this expression, which must resolve to an array, contains any of the given values.
Pass
all=True
to require that this expression contains all of the given values.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") print(dataset.count()) # Only contains samples with a "cat" prediction view = dataset.match( F("predictions.detections.label").contains("cat") ) print(view.count()) # Only contains samples with "cat" or "dog" predictions view = dataset.match( F("predictions.detections.label").contains(["cat", "dog"]) ) print(view.count()) # Only contains samples with "cat" and "dog" predictions view = dataset.match( F("predictions.detections.label").contains(["cat", "dog"], all=True) ) print(view.count())
 Parameters
values – a value, iterable of values, or
ViewExpression
that resolves to an array of valuesall (False) – whether this expression must contain all (True) or any (False) of the given values
 Returns

contains_str
(str_or_strs, case_sensitive=True)¶ Determines whether this expression, which must resolve to a string, contains the given string or string(s).
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains predictions whose `label` contains "be" view = dataset.filter_labels( "predictions", F("label").contains_str("be") ) print(view.distinct("predictions.detections.label"))
 Parameters
str_or_strs – a string or iterable of strings
case_sensitive (True) – whether to perform a case sensitive match
 Returns

cos
()¶ Computes the cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `cos()` view = dataset.match(F("uniqueness").cos() <= np.cos(0.5)) print(view.bounds("uniqueness"))
 Returns

cosh
()¶ Computes the hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `cosh()` view = dataset.match(F("uniqueness").cosh() >= np.cosh(0.5)) print(view.bounds("uniqueness"))
 Returns

day_of_month
()¶ Returns the day of the month of this date expression (in UTC) as a number between 1 and 31.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the days of the month for the dataset print(dataset.values(F("created_at").day_of_month())) # Samples with even days of the month view = dataset.match(F("created_at").day_of_month() % 2 == 0) print(len(view))
 Returns

day_of_week
()¶ Returns the day of the week of this date expression (in UTC) as a number between 1 (Sunday) and 7 (Saturday).
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 4), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 5), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 6), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 7), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the days of the week for the dataset print(dataset.values(F("created_at").day_of_week())) # Samples with even days of the week view = dataset.match(F("created_at").day_of_week() % 2 == 0) print(len(view))
 Returns

day_of_year
()¶ Returns the day of the year of this date expression (in UTC) as a number between 1 and 366.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the days of the year for the dataset print(dataset.values(F("created_at").day_of_year())) # Samples with even days of the year view = dataset.match(F("created_at").day_of_year() % 2 == 0) print(len(view))
 Returns

difference
(values)¶ Computes the set difference of this expression, which must resolve to an array, and the given array or array expression.
The arrays are treated as sets, so all duplicates are removed.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b"], other_tags=["a", "c"] ) ] ) print(dataset.values(F("tags").difference(F("other_tags")))) # [['b']]
 Parameters
values – an iterable of values or a
ViewExpression
that resolves to an array Returns

ends_with
(str_or_strs, case_sensitive=True)¶ Determines whether this expression, which must resolve to a string, ends with the given string or string(s).
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose images are JPEGs or PNGs view = dataset.match(F("filepath").ends_with((".jpg", ".png"))) print(view.count()) print(view.first().filepath)
 Parameters
str_or_strs – a string or iterable of strings
case_sensitive (True) – whether to perform a case sensitive match
 Returns

static
enumerate
(array, start=0)¶ Returns an array of
[index, element]
pairs enumerating the elements of the given expression, which must resolve to an array.Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b", "c"]), fo.Sample(filepath="image2.jpg", tags=["y", "z"]), ] ) # Populates an `enumerated_tags` field with the enumerated `tag` dataset.add_sample_field("enumerated_tags", fo.ListField) view = dataset.set_field("enumerated_tags", F.enumerate(F("tags"))) print(view.first())
 Parameters
array – a
ViewExpression
that resolves to an arraystart (0) – the starting enumeration index to use
 Returns

exists
(bool=True)¶ Determines whether this expression, which must resolve to a field, exists and is not None.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset( "quickstart", dataset_name=fo.get_default_dataset_name() ) # Add a new field to one sample sample = dataset.first() sample["new_field"] = ["hello", "there"] sample.save() # Get samples that have a value for `new_field` view = dataset.match(F("new_field").exists()) print(len(view))
 Parameters
bool (True) – whether to determine whether this expression exists (True) or is None or nonexistent (False)
 Returns

exp
()¶ Raises Euler’s number to this expression, which must resolve to a numeric value.
 Returns

extend
(*args)¶ Concatenates the given array(s) or array expression(s) to this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b"]), fo.Sample(filepath="image2.jpg", tags=["a", "b"]), ] ) # Adds the "c" and "d" tags to each sample view = dataset.set_field("tags", F("tags").extend(["c", "d"])) print(view.first().tags)
 Parameters
*args – one or more arrays or
ViewExpression
instances that resolve to array expressions Returns

filter
(expr)¶ Applies the given filter to the elements of this expression, which must resolve to an array.
The output array will only contain elements of the input array for which
expr
returnsTrue
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only include predictions with `confidence` of at least 0.9 view = dataset.set_field( "predictions.detections", F("detections").filter(F("confidence") > 0.9) ) print(view.bounds("predictions.detections.confidence"))
 Parameters
expr – a
ViewExpression
that returns a boolean Returns

floor
()¶ Computes the floor of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match((F("uniqueness") + 0.5).floor() == 1) print(view.bounds("uniqueness"))
 Returns

hour
()¶ Returns the hour portion of this date expression (in UTC) as a number between 0 and 23.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the hour portion of the dates in the dataset print(dataset.values(F("created_at").hour())) # Samples with even hours view = dataset.match(F("created_at").hour() % 2 == 0) print(len(view))
 Returns

if_else
(true_expr, false_expr)¶ Returns either
true_expr
orfalse_expr
depending on the value of this expression, which must resolve to a boolean.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.75 to None view = dataset.set_field( "uniqueness", (F("uniqueness") > 0.75).if_else(F("uniqueness"), None) ) print(view.bounds("uniqueness"))
 Parameters
true_expr – a
ViewExpression
or MongoDB expression dictfalse_expr – a
ViewExpression
or MongoDB expression dict
 Returns

insert
(index, value)¶ Inserts the value before the given index in this expression, which must resolve to an array.
If
index <= 0
, the value is prepended to this array. Ifindex >= self.length()
, the value is appended to this array.Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "c"]), fo.Sample(filepath="image2.jpg", tags=["a", "c"]), ] ) # Adds the "ready" tag to each sample view = dataset.set_field("tags", F("tags").insert(1, "b")) print(view.first().tags)
 Parameters
index – the index at which to insert the value
value – the value or
ViewExpression
 Returns

intersection
(*args)¶ Computes the set intersection of this expression, which must resolve to an array, and the given array(s) or array expression(s).
The arrays are treated as sets, so all duplicates are removed.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b"], other_tags=["a", "c"] ) ] ) print(dataset.values(F("tags").intersection(F("other_tags")))) # [['a']]
 Parameters
*args – one or more arrays or
ViewExpression
instances that resolve to array expressions Returns

is_array
()¶ Determines whether this expression is an array.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Verify that tags are arrays view = dataset.match(F("tags").is_array()) print(len(view))
 Returns

property
is_frozen
¶ Whether this expression’s prefix is frozen.

is_in
(values)¶ Creates an expression that returns a boolean indicating whether
self in values
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F ANIMALS = [ "bear", "bird", "cat", "cow", "dog", "elephant", "giraffe", "horse", "sheep", "zebra" ] dataset = foz.load_zoo_dataset("quickstart") # Create a view that only contains animal predictions view = dataset.filter_labels( "predictions", F("label").is_in(ANIMALS) ) print(view.count_values("predictions.detections.label"))
 Parameters
values – a value or iterable of values
 Returns

is_missing
()¶ Determines whether this expression refers to a missing field.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Verify that `foobar` is a nonexistent field on all samples view = dataset.match(F("foobar").is_missing()) print(len(view) == len(dataset))
 Returns

is_null
()¶ Determines whether this expression is null.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.25 to None view = dataset.set_field( "uniqueness", (F("uniqueness") >= 0.25).if_else(F("uniqueness"), None) ) # Create view that only contains samples with uniqueness = None not_unique_view = view.match(F("uniqueness").is_null()) print(len(not_unique_view))
 Returns

is_number
()¶ Determines whether this expression is a number.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.25 to None view = dataset.set_field( "uniqueness", (F("uniqueness") >= 0.25).if_else(F("uniqueness"), None) ) # Create view that only contains samples with uniqueness values has_unique_view = view.match(F("uniqueness").is_number()) print(len(has_unique_view))
 Returns

is_string
()¶ Determines whether this expression is a string.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Verify that filepaths are strings view = dataset.match(F("filepath").is_string()) print(len(view))
 Returns

is_subset
(values)¶ Checks whether this expression’s contents, which must resolve to an array, are a subset of the given array or array expression’s contents.
The arrays are treated as sets, so duplicate values are ignored.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b", "a", "b"], other_tags=["a", "b", "c"], ) ] ) print(dataset.values(F("tags").is_subset(F("other_tags")))) # [True]
 Parameters
values – an iterable of values or a
ViewExpression
that resolves to an array Returns

join
(delimiter)¶ Joins the elements of this expression, which must resolve to a string array, by the given delimiter.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Generate a `list,of,labels` for the `predictions` of each sample view = dataset.set_field( "predictions.labels", F("detections").map(F("label")).join(",") ) print(view.first().predictions.labels)
 Parameters
delimiter – the delimiter string
 Returns

length
()¶ Computes the length of this expression, which must resolve to an array.
If this expression’s value is null or missing, zero is returned.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with at least 15 predicted objects view = dataset.match(F("predictions.detections").length() >= 15) print(dataset.count()) print(view.count())
 Returns

let_in
(expr)¶ Returns an equivalent expression where this expression is defined as a variable that is used wherever necessary in the given expression.
This method is useful when
expr
contains multiple instances of this expression, since it avoids duplicate computation of this expression in the final pipeline.If
expr
is a simple expression such as aViewField
, no variable is defined andexpr
is directly returned.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] good_bboxes = (bbox_area > 0.25) & (bbox_area < 0.75) # Optimize the expression good_bboxes_opt = bbox_area.let_in(good_bboxes) # Contains predictions whose bounding box areas are in [0.25, 0.75] view = dataset.filter_labels("predictions", good_bboxes_opt) print(good_bboxes) print(good_bboxes_opt) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
expr – a
ViewExpression
 Returns

static
literal
(value)¶ Returns an expression representing the given value without parsing.
See this page for more information on when this method is reqiured.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add the "$money" tag to each sample # The "$" character ordinarily has special meaning, so we must wrap # it in `literal()` in order to add it via this method view = dataset.set_field( "tags", F("tags").append(F.literal("$money")) ) print(view.first().tags)
 Parameters
value – a value
 Returns

ln
()¶ Computes the natural logarithm of this expression, which must resolve to a numeric value.
Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 view = dataset.match(F("uniqueness").ln() >= math.log(0.5)) print(view.bounds("uniqueness"))
 Returns

log
(base)¶ Computes the logarithm base
base
of this expression, which must resolve to a numeric value.Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 view = dataset.match(F("uniqueness").log(2) >= math.log2(0.5)) print(view.bounds("uniqueness"))
 Parameters
base – the logarithm base
 Returns

log10
()¶ Computes the logarithm base 10 of this expression, which must resolve to a numeric value.
Examples:
import math import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 view = dataset.match(F("uniqueness").log10() >= math.log10(0.5)) print(view.bounds("uniqueness"))
 Returns

lower
()¶ Converts this expression, which must resolve to a string, to lowercase.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Converts all tags to lowercase transform_tag = F().lower() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Returns

lstrip
(chars=None)¶ Removes whitespace characters from the beginning of this expression, which must resolve to a string.
If
chars
is provided, those characters are removed instead of whitespace.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewExpression as E from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Adds and then strips whitespace from the beginning of each tag transform_tag = E(" ").concat(F()).lstrip() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
chars (None) – an optional string or
ViewExpression
resolving to a string expression specifying characters to remove Returns

map
(expr)¶ Applies the given expression to the elements of this expression, which must resolve to an array.
The output will be an array with the applied results.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Only include predictions with `confidence` of at least 0.9 view = dataset.set_field( "predictions.detections", F("detections").map(F().set_field("area", bbox_area)) ) print(view.bounds("predictions.detections.area"))
 Parameters
expr – a
ViewExpression
 Returns

map_values
(mapping)¶ Replaces this expression with the corresponding value in the provided mapping dict, if it is present as a key.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F ANIMALS = [ "bear", "bird", "cat", "cow", "dog", "elephant", "giraffe", "horse", "sheep", "zebra" ] dataset = foz.load_zoo_dataset("quickstart") # # Replace the `label` of all animal objects in the `predictions` # field with "animal" # mapping = {a: "animal" for a in ANIMALS} view = dataset.set_field( "predictions.detections", F("detections").map( F().set_field("label", F("label").map_values(mapping)) ) ) print(view.count_values("predictions.detections.label"))
 Parameters
mapping – a dict mapping keys to replacement values
 Returns

matches_str
(str_or_strs, case_sensitive=True)¶ Determines whether this expression, which must resolve to a string, exactly matches the given string or string(s).
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains predictions whose `label` is "cat" or "dog", case # insensitive view = dataset.map_labels( "predictions", {"cat": "CAT", "dog": "DOG"} ).filter_labels( "predictions", F("label").matches_str(("cat", "dog"), case_sensitive=False) ) print(view.distinct("predictions.detections.label"))
 Parameters
str_or_strs – a string or iterable of strings
case_sensitive (True) – whether to perform a case sensitive match
 Returns

max
(value=None)¶ Returns the maximum value of either this expression, which must resolve to an array, or the maximum of this expression and the given value.
Missing or
None
values are ignored.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Adds a `max_area` property to the `predictions` field that # records the maximum prediction area in that sample view = dataset.set_field( "predictions.max_area", F("detections").map(bbox_area).max() ) print(view.bounds("predictions.max_area"))
 Parameters
value (None) – an optional value to compare to
 Returns

mean
()¶ Returns the average value in this expression, which must resolve to a numeric array.
Missing or
None
valued elements are ignored.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add a field to each `predictions` object that records the average # confidence of the predictions view = dataset.set_field( "predictions.conf_mean", F("detections").map(F("confidence")).mean() ) print(view.bounds("predictions.conf_mean"))
 Returns

millisecond
()¶ Returns the millisecond portion of this date expression (in UTC) as an integer between 0 and 999.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 0, 1000), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 0, 2000), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 0, 3000), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 0, 4000), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the millisecond portion of the dates in the dataset print(dataset.values(F("created_at").millisecond())) # Samples with even milliseconds view = dataset.match(F("created_at").millisecond() % 2 == 0) print(len(view))
 Returns

min
(value=None)¶ Returns the minimum value of either this expression, which must resolve to an array, or the minimum of this expression and the given value.
Missing or
None
values are ignored.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format bbox_area = F("bounding_box")[2] * F("bounding_box")[3] # Adds a `min_area` property to the `predictions` field that # records the minimum prediction area in that sample view = dataset.set_field( "predictions.min_area", F("detections").map(bbox_area).min() ) print(view.bounds("predictions.min_area"))
 Parameters
value (None) – an optional value to compare to
 Returns

minute
()¶ Returns the minute portion of this date expression (in UTC) as a number between 0 and 59.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the minute portion of the dates in the dataset print(dataset.values(F("created_at").minute())) # Samples with even minutes view = dataset.match(F("created_at").minute() % 2 == 0) print(len(view))
 Returns

month
()¶ Returns the month of this date expression (in UTC) as a number between 1 and 12.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 2, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 3, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 4, 1), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the months of the year for the dataset print(dataset.values(F("created_at").month())) # Samples from even months of the year view = dataset.match(F("created_at").month() % 2 == 0) print(len(view))
 Returns

pow
(power)¶ Raises this expression, which must resolve to a numeric value, to the given power,
self ** power
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format center_dist = ( (F("bounding_box")[0] + 0.5 * F("bounding_box")[2]  0.5).pow(2) + (F("bounding_box")[1] + 0.5 * F("bounding_box")[3]  0.5).pow(2) ).sqrt() # Only contains predictions whose bounding box center is a distance # of at most 0.02 from the center of the image view = dataset.select_fields("predictions").filter_labels( "predictions", center_dist < 0.02 ) session = fo.launch_app(view=view)
 Parameters
power – the power
 Returns

prepend
(value)¶ Prepends the given value to this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["b", "c"]), fo.Sample(filepath="image2.jpg", tags=["b", "c"]), ] ) # Adds the "a" tag to each sample view = dataset.set_field("tags", F("tags").prepend("a")) print(view.first().tags)
 Parameters
value – the value or
ViewExpression
 Returns

static
rand
()¶ Returns an expression that generates a uniform random float in
[0, 1]
each time it is called.Warning
This expression will generate new values each time it is used, so you likely do not want to use it to construct dataset views, since such views would produce different outputs each time they are used.
A typical usage for this expression is in conjunction with
fiftyone.core.view.DatasetView.set_field()
andfiftyone.core.view.DatasetView.save()
to populate a randomized field on a dataset.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewExpression as E dataset = foz.load_zoo_dataset("quickstart").clone() # # Populate a new `rand` field with random numbers # dataset.add_sample_field("rand", fo.FloatField) dataset.set_field("rand", E.rand()).save("rand") print(dataset.bounds("rand")) # # Create a view that contains a different 10%% of the dataset each # time it is used # view = dataset.match(E.rand() < 0.1) print(view.first().id) print(view.first().id) # probably different!
 Returns

static
randn
()¶ Returns an expression that generates a sample from the standard Gaussian distribution each time it is called.
Warning
This expression will generate new values each time it is used, so you likely do not want to use it to construct dataset views, since such views would produce different outputs each time they are used.
A typical usage for this expression is in conjunction with
fiftyone.core.view.DatasetView.set_field()
andfiftyone.core.view.DatasetView.save()
to populate a randomized field on a dataset.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewExpression as E dataset = foz.load_zoo_dataset("quickstart").clone() # # Populate a new `randn` field with random numbers # dataset.add_sample_field("randn", fo.FloatField) dataset.set_field("randn", E.randn()).save("randn") print(dataset.bounds("randn")) # # Create a view that contains a different 50%% of the dataset each # time it is used # view = dataset.match(E.randn() < 0) print(view.first().id) print(view.first().id) # probably different!
 Returns

static
range
(start, stop=None)¶ Returns an array expression containing the sequence of integers from the specified start (inclusive) to stop (exclusive).
If
stop
is provided, returns[start, start + 1, ..., stop  1]
.If no
stop
is provided, returns[0, 1, ..., start  1]
.Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b", "c"]), fo.Sample(filepath="image2.jpg", tags=["y", "z"]), ] ) # Populates an `ints` field based on the number of `tags` dataset.add_sample_field("ints", fo.ListField) view = dataset.set_field("ints", F.range(F("tags").length())) print(view.first())
 Parameters
start – the starting value, or stopping value if no
stop
is providedstop (None) – the stopping value, if both input arguments are provided
 Returns

re_match
(regex, options=None)¶ Performs a regular expression pattern match on this expression, which must resolve to a string.
The output of the expression will be
True
if the pattern matches andFalse
otherwise.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # # Get samples whose images are JPEGs # view = dataset.match(F("filepath").re_match("\.jpg$")) print(view.count()) print(view.first().filepath) # # Get samples whose images are in the "/Users" directory # view = dataset.match(F("filepath").re_match("^/Users/")) print(view.count()) print(view.first().filepath)
 Parameters
 Returns

reduce
(expr, init_val=0)¶ Applies the given reduction to this expression, which must resolve to an array, and returns the single value computed.
The provided
expr
must include theVALUE
expression to properly define the reduction.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F from fiftyone.core.expressions import VALUE # # Compute the number of keypoints in each sample of a dataset # dataset = fo.Dataset() dataset.add_sample( fo.Sample( filepath="image.jpg", keypoints=fo.Keypoints( keypoints=[ fo.Keypoint(points=[(0, 0), (1, 1)]), fo.Keypoint(points=[(0, 0), (1, 0), (1, 1), (0, 1)]), ] ) ) ) view = dataset.set_field( "keypoints.count", F("$keypoints.keypoints").reduce(VALUE + F("points").length()), ) print(view.first().keypoints.count) # # Generate a `list,of,labels` for the `predictions` of each sample # dataset = foz.load_zoo_dataset("quickstart") join_labels = F("detections").reduce( VALUE.concat(",", F("label")), init_val="" ).lstrip(",") view = dataset.set_field("predictions.labels", join_labels) print(view.first().predictions.labels)
 Parameters
expr – a
ViewExpression
defining the reduction expression to apply. Must contain theVALUE
expressioninit_val (0) – an initial value for the reduction
 Returns

replace
(old, new)¶ Replaces all occurances of
old
withnew
in this expression, which must resolve to a string.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Replaces "val" with "VAL" in each tag transform_tag = F().replace("val", "VAL") view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
old – a string or
ViewExpression
resolving to a string expression specifying the substring to replacenew – a string or
ViewExpression
resolving to a string expression specifying the replacement value
 Returns

reverse
()¶ Reverses the order of the elements in the expression, which must resolve to an array.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") first_obj = F("predictions.detections")[0] last_obj = F("predictions.detections").reverse()[0] # Only contains samples whose first and last prediction have the # same label view = dataset.match( first_obj.apply(F("label")) == last_obj.apply(F("label")) ) print(dataset.count()) print(view.count())
 Returns

round
(place=0)¶ Rounds this expression, which must resolve to a numeric value, at the given decimal place.
Positive values of
place
will round toplace
decimal places:place=2: 1234.5678 > 1234.57
Negative values of
place
will roundplace
digits left of the decimal:place=1: 1234.5678 > 1230
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match((2 * F("uniqueness")).round() == 1) print(view.bounds("uniqueness"))
 Parameters
place (0) – the decimal place at which to round. Must be an integer in range
(20, 100)
 Returns

rsplit
(delimiter, maxsplit=None)¶ Splits this expression, which must resolve to a string, by the given delimiter.
If the number of chunks exceeds
maxsplit
, splits are only performed on the lastmaxsplit
occurances of the delimiter.The result is a string array that contains the chunks with the delimiter removed. If the delimiter is not found, this full string is returned as a single element array.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add "okgo" to the first tag and then split once on "" from the # right to create two tags for each sample view = dataset.set_field( "tags", F("tags")[0].concat("okgo").rsplit("", 1) ) print(view.first().tags)
 Parameters
delimiter – the delimiter string or
ViewExpression
resolving to a string expressionmaxsplit (None) – a maximum number of splits to perform, from the right
 Returns

rstrip
(chars=None)¶ Removes whitespace characters from the end of this expression, which must resolve to a string.
If
chars
is provided, those characters are removed instead of whitespace.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Adds and then strips whitespace from the end of each tag transform_tag = F().concat(" ").rstrip() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
chars (None) – an optional string or
ViewExpression
resolving to a string expression specifying characters to remove Returns

second
()¶ Returns the second portion of this date expression (in UTC) as a number between 0 and 59.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 2), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 3), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1, 0, 0, 4), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the second portion of the dates in the dataset print(dataset.values(F("created_at").second())) # Samples with even seconds view = dataset.match(F("created_at").second() % 2 == 0) print(len(view))
 Returns

set_equals
(*args)¶ Checks whether this expression, which must resolve to an array, contains the same distinct values as each of the given array(s) or array expression(s).
The arrays are treated as sets, so all duplicates are ignored.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b", "a", "b"], other_tags=["a", "b", "b"], ) ] ) print(dataset.values(F("tags").set_equals(F("other_tags")))) # [True]
 Parameters
*args – one or more arrays or
ViewExpression
instances that resolve to array expressions Returns

set_field
(field, value_or_expr, relative=True)¶ Sets the specified field or embedded field of this expression, which must resolve to a document, to the given value or expression.
By default, the provided expression is computed by applying it to this expression via
self.apply(value_or_expr)
.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # # Replaces the `label` attritubes of the objects in the # `predictions` field according to the following rule: # # If the `label` starts with `b`, replace it with `b`. Otherwise, # replace it with "other" # view = dataset.set_field( "predictions.detections", F("detections").map( F().set_field( "label", F("label").re_match("^b").if_else("b", "other"), ) ) ) print(view.count_values("predictions.detections.label"))
 Parameters
field – the “field” or “embedded.field.name” to set
value_or_expr – a literal value or
ViewExpression
defining the field to setrelative (True) – whether to compute
value_or_expr
by applying it to this expression (True), or to use it untouched (False)
 Returns

sin
()¶ Computes the sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `sin()` view = dataset.match(F("uniqueness").sin() >= np.sin(0.5)) print(view.bounds("uniqueness"))
 Returns

sinh
()¶ Computes the hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `sinh()` view = dataset.match(F("uniqueness").sinh() >= np.sinh(0.5)) print(view.bounds("uniqueness"))
 Returns

sort
(key=None, reverse=False)¶ Sorts this expression, which must resolve to an array.
If no
key
is provided, this array must contain elements whose BSON representation can be sorted by JavaScript’s.sort()
method.If a
key
is provided, the array must contain documents, which are sorted bykey
, which must be a field or embedded field.Examples:
# # Sort the tags of each sample in a dataset # import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="im1.jpg", tags=["z", "f", "p", "a"]), fo.Sample(filepath="im2.jpg", tags=["y", "q", "h", "d"]), fo.Sample(filepath="im3.jpg", tags=["w", "c", "v", "l"]), ] ) # Sort the `tags` of each sample view = dataset.set_field("tags", F("tags").sort()) print(view.first().tags) # # Sort the predictions in each sample of a dataset by `confidence` # import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") view = dataset.set_field( "predictions.detections", F("detections").sort(key="confidence", reverse=True) ) sample = view.first() print(sample.predictions.detections[0].confidence) print(sample.predictions.detections[1].confidence)
 Parameters
key (None) – an optional field or
embedded.field.name
to sort byreverse (False) – whether to sort in descending order
 Returns

split
(delimiter, maxsplit=None)¶ Splits this expression, which must resolve to a string, by the given delimiter.
The result is a string array that contains the chunks with the delimiter removed. If the delimiter is not found, this full string is returned as a single element array.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add "good" to the first tag and then split on "" to create two # tags for each sample view = dataset.set_field( "tags", F("tags")[0].concat("good").split("") ) print(view.first().tags)
 Parameters
delimiter – the delimiter string or
ViewExpression
resolving to a string expressionmaxsplit (None) – a maximum number of splits to perform, from the left
 Returns

sqrt
()¶ Computes the square root of this expression, which must resolve to a numeric value.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Bboxes are in [topleftx, toplefty, width, height] format center_dist = ( (F("bounding_box")[0] + 0.5 * F("bounding_box")[2]  0.5) ** 2 + (F("bounding_box")[1] + 0.5 * F("bounding_box")[3]  0.5) ** 2 ).sqrt() # Only contains predictions whose bounding box center is a distance # of at most 0.02 from the center of the image view = dataset.select_fields("predictions").filter_labels( "predictions", center_dist < 0.02 ) session = fo.launch_app(view=view)
 Returns

starts_with
(str_or_strs, case_sensitive=True)¶ Determines whether this expression, which must resolve to a string, starts with the given string or string(s).
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose images are in "/Users" or "/home" directories view = dataset.match(F("filepath").starts_with(("/Users", "/home")) print(view.count()) print(view.first().filepath)
 Parameters
str_or_strs – a string or iterable of strings
case_sensitive (True) – whether to perform a case sensitive match
 Returns

std
(sample=False)¶ Returns the standard deviation of the values in this expression, which must resolve to a numeric array.
Missing or
None
valued elements are ignored.By default, the population standard deviation is returned. If you wish to compute the sample standard deviation instead, set
sample=True
.See https://en.wikipedia.org/wiki/Standard_deviation#Estimation for more information on population (biased) vs sample (unbiased) standard deviation.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add a field to each `predictions` object that records the # standard deviation of the confidences view = dataset.set_field( "predictions.conf_std", F("detections").map(F("confidence")).std() ) print(view.bounds("predictions.conf_std"))
 Parameters
sample (False) – whether to compute the sample standard deviation rather than the population standard deviation
 Returns

strip
(chars=None)¶ Removes whitespace characters from the beginning and end of this expression, which must resolve to a string.
If
chars
is provided, those characters are removed instead of whitespace.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewExpression as E from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Adds and then strips whitespace from each tag transform_tag = E(" ").concat(F(), " ").rstrip() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
chars (None) – an optional string or
ViewExpression
resolving to a string expression specifying characters to remove Returns

strlen
()¶ Computes the length of this expression, which must resolve to a string.
If this expression’s value is null or missing, zero is returned.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Records the length of each predicted object's `label` label_len = F().set_field("label_len", F("label").strlen()) view = dataset.set_field( "predictions.detections", F("detections").map(label_len), ) print(view.bounds("predictions.detections.label_len"))
 Returns

substr
(start=None, end=None, count=None)¶ Extracts the specified substring from this expression, which must resolve to a string.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Truncate the `label` of each prediction to 3 characters truncate_label = F().set_field("label", F("label").substr(count=3)) view = dataset.set_field( "predictions.detections", F("detections").map(truncate_label), ) print(view.distinct("predictions.detections.label"))
 Parameters
start (None) – the starting index of the substring. If negative, specifies an offset from the end of the string
end (None) – the ending index of the substring. If negative, specifies an offset from the end of the string
count (None) – the substring length to extract. If
None
, the rest of the string is returned
 Returns

sum
()¶ Returns the sum of the values in this expression, which must resolve to a numeric array.
Missing, nonnumeric, or
None
valued elements are ignored.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Add a field to each `predictions` object that records the total # confidence of the predictions view = dataset.set_field( "predictions.total_conf", F("detections").map(F("confidence")).sum() ) print(view.bounds("predictions.total_conf"))
 Returns

switch
(mapping, default=None)¶ Applies a switch statement to this expression, which effectively computes the given pseudocode:
for key, value in mapping.items(): if self.apply(key): return value if default is not None: return default
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Round `uniqueness` values to either 0.25 or 0.75 view = dataset.set_field( "uniqueness", F("uniqueness").switch( { (0.0 < F()) & (F() <= 0.5): 0.25, (0.5 < F()) & (F() <= 1.0): 0.75, }, ) ) print(view.count_values("uniqueness"))
 Parameters
mapping – a dict mapping boolean
ViewExpression
keys to literal orViewExpression
valuesdefault (None) – an optional literal or
ViewExpression
to return if none of the switch branches are taken
 Returns

tan
()¶ Computes the tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `tan()` view = dataset.match(F("uniqueness").tan() >= np.tan(0.5)) print(view.bounds("uniqueness"))
 Returns

tanh
()¶ Computes the hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `tanh()` view = dataset.match(F("uniqueness").tanh() >= np.tanh(0.5)) print(view.bounds("uniqueness"))
 Returns

to_bool
()¶ Converts the expression to a boolean value.
See this page for conversion rules.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart").clone() # Adds a `uniqueness_bool` field that is False when # `uniqueness < 0.5` and True when `uniqueness >= 0.5` dataset.add_sample_field("uniqueness_bool", fo.BooleanField) view = dataset.set_field( "uniqueness_bool", (2.0 * F("uniqueness")).floor().to_bool() ) print(view.count_values("uniqueness_bool"))
 Returns

to_date
()¶ Converts the expression to a date value.
See this page for conversion rules.
Examples:
from datetime import datetime import pytz import fiftyone as fo from fiftyone import ViewField as F now = datetime.utcnow().replace(tzinfo=pytz.utc) sample = fo.Sample( filepath="image.png", date_ms=1000 * now.timestamp(), date_str=now.isoformat(), ) dataset = fo.Dataset() dataset.add_sample(sample) # Convert string/millisecond representations into datetimes dataset.add_sample_field("date1", fo.DateTimeField) dataset.add_sample_field("date2", fo.DateTimeField) ( dataset .set_field("date1", F("date_ms").to_date()) .set_field("date2", F("date_str").to_date()) .save() ) print(dataset.first())
 Returns

to_double
()¶ Converts the expression to a double precision value.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart").clone() # Adds a `uniqueness_float` field that is 0.0 when # `uniqueness < 0.5` and 1.0 when `uniqueness >= 0.5` dataset.add_sample_field("uniqueness_float", fo.FloatField) view = dataset.set_field( "uniqueness_float", (F("uniqueness") >= 0.5).to_double() ) print(view.count_values("uniqueness_float"))
See this page for conversion rules.
 Returns

to_int
()¶ Converts the expression to an integer value.
See this page for conversion rules.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart").clone() # Adds a `uniqueness_int` field that contains the value of the # first decimal point of the `uniqueness` field dataset.add_sample_field("uniqueness_int", fo.IntField) view = dataset.set_field( "uniqueness_int", (10.0 * F("uniqueness")).floor().to_int() ) print(view.count_values("uniqueness_int"))
 Returns

to_string
()¶ Converts the expression to a string value.
See this page for conversion rules.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart").clone() # Adds a `uniqueness_str` field that is "true" when # `uniqueness >= 0.5` and "false" when `uniqueness < 0.5` dataset.add_sample_field("uniqueness_str", fo.StringField) view = dataset.set_field( "uniqueness_str", (F("uniqueness") >= 0.5).to_string() ) print(view.count_values("uniqueness_str"))
 Returns

trunc
(place=0)¶ Truncates this expression, which must resolve to a numeric value, at the specified decimal place.
Positive values of
place
will truncate toplace
decimal places:place=2: 1234.5678 > 1234.56
Negative values of
place
will replaceplace
digits left of the decimal with zero:place=1: 1234.5678 > 1230
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") dataset.compute_metadata() # Only contains samples whose height is in [500, 600) pixels view = dataset.match(F("metadata.height").trunc(2) == 500) print(view.bounds("metadata.height"))
 Parameters
place (0) – the decimal place at which to truncate
 Returns

type
()¶ Returns the type string of this expression.
See this page for more details.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.75 to None view = dataset.set_field( "uniqueness", (F("uniqueness") > 0.75).if_else(F("uniqueness"), None) ) # Create a view that only contains samples with nonNone uniqueness unique_only_view = view.match(F("uniqueness").type() != "null") print(len(unique_only_view))
 Returns

union
(*args)¶ Computes the set union of this expression, which must resolve to an array, and the given array(s) or array expression(s).
The arrays are treated as sets, so all duplicates are removed.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b"], other_tags=["a", "c"] ) ] ) print(dataset.values(F("tags").union(F("other_tags")))) # [['a', 'b', 'c']]
 Parameters
*args – one or more arrays or
ViewExpression
instances that resolve to array expressions Returns

unique
()¶ Returns an array containing the unique values in this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b", "a", "b"], ) ] ) print(dataset.values(F("tags").unique())) # [['a', 'b']]
 Returns

upper
()¶ Converts this expression, which must resolve to a string, to uppercase.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Converts all tags to uppercase transform_tag = F().upper() view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Returns

week
()¶ Returns the week of the year of this date expression (in UTC) as a number between 0 and 53.
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 2, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 3, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 4, 1), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the weeks of the year for the dataset print(dataset.values(F("created_at").week())) # Samples with even months of the week view = dataset.match(F("created_at").week() % 2 == 0) print(len(view))
 Returns

year
()¶ Returns the year of this date expression (in UTC).
Examples:
from datetime import datetime import fiftyone as fo from fiftyone import ViewField as F samples = [ fo.Sample( filepath="image1.jpg", created_at=datetime(1970, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1971, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1972, 1, 1), ), fo.Sample( filepath="image1.jpg", created_at=datetime(1973, 1, 1), ), ] dataset = fo.Dataset() dataset.add_samples(samples) # Get the years for the dataset print(dataset.values(F("created_at").year())) # Samples from even years view = dataset.match(F("created_at").year() % 2 == 0) print(len(view))
 Returns

static
zip
(*args, use_longest=False, defaults=None)¶ Zips the given expressions, which must resolve to arrays, into an array whose ith element is an array containing the ith element from each input array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="image1.jpg", tags=["a", "b", "c"], ints=[1, 2, 3, 4, 5], ), fo.Sample( filepath="image2.jpg", tags=["y", "z"], ints=[25, 26, 27, 28], ), ] ) dataset.add_sample_field("tags_ints", fo.ListField) # Populates an `tags_ints` field with the zipped `tags` and `ints` view = dataset.set_field("tags_ints", F.zip(F("tags"), F("ints"))) print(view.first()) # Same as above but use the longest array to determine output size view = dataset.set_field( "tags_ints", F.zip(F("tags"), F("ints"), use_longest=True, defaults=("", 0)) ) print(view.first())
 Parameters
*args – one or more arrays or
ViewExpression
instances resolving to arraysuse_longest (False) – whether to use the longest array to determine the number of elements in the output array. By default, the length of the shortest array is used
defaults (None) – an optional array of default values of same length as
*args
to use whenuse_longest == True
and the input arrays are of different lengths. If no defaults are provided anduse_longest == True
, then missing values are set toNone
 Returns


class
fiftyone.core.expressions.
ObjectId
(oid)¶ Bases:
fiftyone.core.expressions.ViewExpression
A
ViewExpression
that refers to an ObjectId of a document.The typical use case for this class is writing an expression that involves checking if the ID of a document matches a particular known ID.
Example:
from fiftyone import ViewField as F from fiftyone.core.expressions import ObjectId # Check if the ID of the document matches the given ID expr = F("_id") == ObjectId("5f452489ef00e6374aad384a")
 Parameters
oid – the object ID string
Methods:
abs
()Computes the absolute value of this expression, which must resolve to a numeric value.
all
(exprs)Checks whether all of the given expressions evaluate to True.
any
(exprs)Checks whether any of the given expressions evaluate to True.
append
(value)Appends the given value to this expression, which must resolve to an array.
apply
(expr)Applies the given expression to this expression.
arccos
()Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians.
arccosh
()Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
arcsin
()Computes the inverse sine of this expression, which must resolve to a numeric value, in radians.
arcsinh
()Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
arctan
()Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians.
arctanh
()Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
cases
(mapping[, default])Applies a case statement to this expression, which effectively computes the following pseudocode.
ceil
()Computes the ceiling of this expression, which must resolve to a numeric value.
concat
(*args)Concatenates the given string(s) to this expression, which must resolve to a string.
contains
(values[, all])Checks whether this expression, which must resolve to an array, contains any of the given values.
contains_str
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, contains the given string or string(s).
cos
()Computes the cosine of this expression, which must resolve to a numeric value, in radians.
cosh
()Computes the hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
Returns the day of the month of this date expression (in UTC) as a number between 1 and 31.
Returns the day of the week of this date expression (in UTC) as a number between 1 (Sunday) and 7 (Saturday).
Returns the day of the year of this date expression (in UTC) as a number between 1 and 366.
difference
(values)Computes the set difference of this expression, which must resolve to an array, and the given array or array expression.
ends_with
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, ends with the given string or string(s).
enumerate
(array[, start])Returns an array of
[index, element]
pairs enumerating the elements of the given expression, which must resolve to an array.exists
([bool])Determines whether this expression, which must resolve to a field, exists and is not None.
exp
()Raises Euler’s number to this expression, which must resolve to a numeric value.
extend
(*args)Concatenates the given array(s) or array expression(s) to this expression, which must resolve to an array.
filter
(expr)Applies the given filter to the elements of this expression, which must resolve to an array.
floor
()Computes the floor of this expression, which must resolve to a numeric value.
hour
()Returns the hour portion of this date expression (in UTC) as a number between 0 and 23.
if_else
(true_expr, false_expr)Returns either
true_expr
orfalse_expr
depending on the value of this expression, which must resolve to a boolean.insert
(index, value)Inserts the value before the given index in this expression, which must resolve to an array.
intersection
(*args)Computes the set intersection of this expression, which must resolve to an array, and the given array(s) or array expression(s).
is_array
()Determines whether this expression is an array.
is_in
(values)Creates an expression that returns a boolean indicating whether
self in values
.Determines whether this expression refers to a missing field.
is_null
()Determines whether this expression is null.
Determines whether this expression is a number.
Determines whether this expression is a string.
is_subset
(values)Checks whether this expression’s contents, which must resolve to an array, are a subset of the given array or array expression’s contents.
join
(delimiter)Joins the elements of this expression, which must resolve to a string array, by the given delimiter.
length
()Computes the length of this expression, which must resolve to an array.
let_in
(expr)Returns an equivalent expression where this expression is defined as a variable that is used wherever necessary in the given expression.
literal
(value)Returns an expression representing the given value without parsing.
ln
()Computes the natural logarithm of this expression, which must resolve to a numeric value.
log
(base)Computes the logarithm base
base
of this expression, which must resolve to a numeric value.log10
()Computes the logarithm base 10 of this expression, which must resolve to a numeric value.
lower
()Converts this expression, which must resolve to a string, to lowercase.
lstrip
([chars])Removes whitespace characters from the beginning of this expression, which must resolve to a string.
map
(expr)Applies the given expression to the elements of this expression, which must resolve to an array.
map_values
(mapping)Replaces this expression with the corresponding value in the provided mapping dict, if it is present as a key.
matches_str
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, exactly matches the given string or string(s).
max
([value])Returns the maximum value of either this expression, which must resolve to an array, or the maximum of this expression and the given value.
mean
()Returns the average value in this expression, which must resolve to a numeric array.
Returns the millisecond portion of this date expression (in UTC) as an integer between 0 and 999.
min
([value])Returns the minimum value of either this expression, which must resolve to an array, or the minimum of this expression and the given value.
minute
()Returns the minute portion of this date expression (in UTC) as a number between 0 and 59.
month
()Returns the month of this date expression (in UTC) as a number between 1 and 12.
pow
(power)Raises this expression, which must resolve to a numeric value, to the given power,
self ** power
.prepend
(value)Prepends the given value to this expression, which must resolve to an array.
rand
()Returns an expression that generates a uniform random float in
[0, 1]
each time it is called.randn
()Returns an expression that generates a sample from the standard Gaussian distribution each time it is called.
range
(start[, stop])Returns an array expression containing the sequence of integers from the specified start (inclusive) to stop (exclusive).
re_match
(regex[, options])Performs a regular expression pattern match on this expression, which must resolve to a string.
reduce
(expr[, init_val])Applies the given reduction to this expression, which must resolve to an array, and returns the single value computed.
replace
(old, new)Replaces all occurances of
old
withnew
in this expression, which must resolve to a string.reverse
()Reverses the order of the elements in the expression, which must resolve to an array.
round
([place])Rounds this expression, which must resolve to a numeric value, at the given decimal place.
rsplit
(delimiter[, maxsplit])Splits this expression, which must resolve to a string, by the given delimiter.
rstrip
([chars])Removes whitespace characters from the end of this expression, which must resolve to a string.
second
()Returns the second portion of this date expression (in UTC) as a number between 0 and 59.
set_equals
(*args)Checks whether this expression, which must resolve to an array, contains the same distinct values as each of the given array(s) or array expression(s).
set_field
(field, value_or_expr[, relative])Sets the specified field or embedded field of this expression, which must resolve to a document, to the given value or expression.
sin
()Computes the sine of this expression, which must resolve to a numeric value, in radians.
sinh
()Computes the hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
sort
([key, reverse])Sorts this expression, which must resolve to an array.
split
(delimiter[, maxsplit])Splits this expression, which must resolve to a string, by the given delimiter.
sqrt
()Computes the square root of this expression, which must resolve to a numeric value.
starts_with
(str_or_strs[, case_sensitive])Determines whether this expression, which must resolve to a string, starts with the given string or string(s).
std
([sample])Returns the standard deviation of the values in this expression, which must resolve to a numeric array.
strip
([chars])Removes whitespace characters from the beginning and end of this expression, which must resolve to a string.
strlen
()Computes the length of this expression, which must resolve to a string.
substr
([start, end, count])Extracts the specified substring from this expression, which must resolve to a string.
sum
()Returns the sum of the values in this expression, which must resolve to a numeric array.
switch
(mapping[, default])Applies a switch statement to this expression, which effectively computes the given pseudocode.
tan
()Computes the tangent of this expression, which must resolve to a numeric value, in radians.
tanh
()Computes the hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
to_bool
()Converts the expression to a boolean value.
to_date
()Converts the expression to a date value.
Converts the expression to a double precision value.
to_int
()Converts the expression to an integer value.
to_mongo
([prefix])Returns a MongoDB representation of the ObjectId.
Converts the expression to a string value.
trunc
([place])Truncates this expression, which must resolve to a numeric value, at the specified decimal place.
type
()Returns the type string of this expression.
union
(*args)Computes the set union of this expression, which must resolve to an array, and the given array(s) or array expression(s).
unique
()Returns an array containing the unique values in this expression, which must resolve to an array.
upper
()Converts this expression, which must resolve to a string, to uppercase.
week
()Returns the week of the year of this date expression (in UTC) as a number between 0 and 53.
year
()Returns the year of this date expression (in UTC).
zip
(*args[, use_longest, defaults])Zips the given expressions, which must resolve to arrays, into an array whose ith element is an array containing the ith element from each input array.
Attributes:
Whether this expression’s prefix is frozen.

to_mongo
(prefix=None)¶ Returns a MongoDB representation of the ObjectId.
 Parameters
prefix (None) – unused
 Returns
a MongoDB expression

abs
()¶ Computes the absolute value of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.25, 0.75] view = dataset.match((F("uniqueness")  0.5).abs() < 0.25) print(view.bounds("uniqueness"))
 Returns

static
all
(exprs)¶ Checks whether all of the given expressions evaluate to True.
If no expressions are provided, returns True.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Create a view that only contains predictions that are "cat" and # highly confident is_cat = F("label") == "cat" is_confident = F("confidence") > 0.95 view = dataset.filter_labels( "predictions", F.all([is_cat, is_confident]) ) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
exprs – a
ViewExpression
or iterable ofViewExpression
instances Returns

static
any
(exprs)¶ Checks whether any of the given expressions evaluate to True.
If no expressions are provided, returns False.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Create a view that only contains predictions that are "cat" or # highly confident is_cat = F("label") == "cat" is_confident = F("confidence") > 0.95 view = dataset.filter_labels( "predictions", F.any([is_cat, is_confident]) ) print(dataset.count("predictions.detections")) print(view.count("predictions.detections"))
 Parameters
exprs – a
ViewExpression
or iterable ofViewExpression
instances Returns

append
(value)¶ Appends the given value to this expression, which must resolve to an array.
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample(filepath="image1.jpg", tags=["a", "b"]), fo.Sample(filepath="image2.jpg", tags=["a", "b"]), ] ) # Appends the "c" tag to each sample view = dataset.set_field("tags", F("tags").append("c")) print(view.first().tags)
 Parameters
value – the value or
ViewExpression
 Returns

apply
(expr)¶ Applies the given expression to this expression.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples with `uniqueness` in [0.25, 0.75] view = dataset.match( F("uniqueness").apply((F() > 0.25) & (F() < 0.75)) ) print(view.bounds("uniqueness"))
 Parameters
expr – a
ViewExpression
 Returns

arccos
()¶ Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arccos()` view = dataset.match(F("uniqueness").arccos() <= np.arccos(0.5)) print(view.bounds("uniqueness"))
 Returns

arccosh
()¶ Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arccosh()` view = dataset.match((1 + F("uniqueness")).arccosh() >= np.arccosh(1.5)) print(view.bounds("uniqueness"))
 Returns

arcsin
()¶ Computes the inverse sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arcsin()` view = dataset.match(F("uniqueness").arcsin() >= np.arcsin(0.5)) print(view.bounds("uniqueness"))
 Returns

arcsinh
()¶ Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arcsinh()` view = dataset.match(F("uniqueness").arcsinh() >= np.arcsinh(0.5)) print(view.bounds("uniqueness"))
 Returns

arctan
()¶ Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arctan()` view = dataset.match(F("uniqueness").arctan() >= np.arctan(0.5)) print(view.bounds("uniqueness"))
 Returns

arctanh
()¶ Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians.
Examples:
import numpy as np import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Get samples whose `uniqueness` value is >= 0.5 using `arctanh()` view = dataset.match(F("uniqueness").arctanh() >= np.arctanh(0.5)) print(view.bounds("uniqueness"))
 Returns

cases
(mapping, default=None)¶ Applies a case statement to this expression, which effectively computes the following pseudocode:
for key, value in mapping.items(): if self == key: return value if default is not None: return default
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Set `uniqueness` values below 0.75 to None view = dataset.set_field( "uniqueness", (F("uniqueness") > 0.75).if_else(F("uniqueness"), None) ) # Map numeric `uniqueness` values to 1 and null values to 0 cases_view = view.set_field( "uniqueness", F("uniqueness").type().cases({"double": 1, "null": 0}), ) print(cases_view.count_values("uniqueness"))
 Parameters
mapping – a dict mapping literals or
ViewExpression
keys to literal orViewExpression
valuesdefault (None) – an optional literal or
ViewExpression
to return if none of the switch branches are taken
 Returns

ceil
()¶ Computes the ceiling of this expression, which must resolve to a numeric value.
Examples:
import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Only contains samples with `uniqueness` in [0.5, 1] view = dataset.match((F("uniqueness") + 0.5).ceil() == 2) print(view.bounds("uniqueness"))
 Returns

concat
(*args)¶ Concatenates the given string(s) to this expression, which must resolve to a string.
Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") # Appends "tag" to all tags transform_tag = F().concat("tag") view = dataset.set_field("tags", F("tags").map(transform_tag)) print(dataset.distinct("tags")) print(view.distinct("tags"))
 Parameters
*args – one or more strings or string
ViewExpression
instancesbefore (False) – whether to position
args
before this string in the output string
 Returns

contains
(values, all=False)¶ Checks whether this expression, which must resolve to an array, contains any of the given values.
Pass
all=True
to require that this expression contains all of the given values.Examples:
import fiftyone as fo import fiftyone.zoo as foz from fiftyone import ViewField as F dataset = foz.load_zoo_dataset("quickstart") print(dataset.count()) # Only contains samples with a "cat" prediction view = dataset.match( F("predictions.detections.label").contains("cat") ) print(view.count()) # Only contains samples with "cat" or "dog" predictions view = dataset.match( F(