# fiftyone.core.expressions
Expressions for [`fiftyone.core.stages.ViewStage`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage) definitions.
Copyright 2017-2026, Voxel51, Inc.
[voxel51.com](https://voxel51.com/)
**Functions:**
| [`to_mongo`](#fiftyone.core.expressions.to_mongo)(expr[, prefix]) | Converts an expression to its MongoDB representation. |
|-------------------------------------------------------------------------|----------------------------------------------------------------------|
| [`is_frames_expr`](#fiftyone.core.expressions.is_frames_expr)(expr) | Determines whether the given expression involves a `"frames"` field. |
| [`get_group_slices`](#fiftyone.core.expressions.get_group_slices)(expr) | Extracts the group slices from the given expression, if any. |
**Classes:**
| [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)(expr) | An expression defining a possibly-complex manipulation of a document. |
|-----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ViewField`](#fiftyone.core.expressions.ViewField)([name]) | A [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) that refers to a field or embedded field of a document. |
| [`ObjectId`](#fiftyone.core.expressions.ObjectId)(oid) | A [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) that refers to an [ObjectId](https://docs.mongodb.com/manual/reference/method/ObjectId) of a document. |
**Data:**
| [`VALUE`](#fiftyone.core.expressions.VALUE) | A [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) that refers to the current `$$value` in a MongoDB reduction expression. |
|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
### fiftyone.core.expressions.to_mongo(expr, prefix=None)
Converts an expression to its MongoDB representation.
* **Parameters:**
* **expr** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or an already serialized
[MongoDB expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
* **prefix** (*None*) – an optional prefix to prepend to all [`ViewField`](#fiftyone.core.expressions.ViewField)
instances in the expression
* **Returns:**
a MongoDB expression
### fiftyone.core.expressions.is_frames_expr(expr)
Determines whether the given expression involves a `"frames"` field.
* **Parameters:**
**expr** –
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or an already serialized
[MongoDB expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
* **Returns:**
True/False
### fiftyone.core.expressions.get_group_slices(expr)
Extracts the group slices from the given expression, if any.
* **Parameters:**
**expr** –
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or an already serialized
[MongoDB expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
* **Returns:**
a (possibly-empty) list of group slices
### *class* fiftyone.core.expressions.ViewExpression(expr)
Bases: `object`
An expression defining a possibly-complex 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`](fiftyone.core.stages.md#fiftyone.core.stages.ViewStage).
Typically, [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) instances are built by creating one or
more [`ViewField`](#fiftyone.core.expressions.ViewField) instances and then defining the desired operation
by recursively invoking methods on these objects:
```default
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 [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression) directly, typically when you need to write an
expression that begins with a literal Python value:
```default
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](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
for more details about the underlying expression language that this class
encapsulates.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_ge_\_(other)
Determines whether this expression is greater than or equal to the
given value or expression, `self >= other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_gt_\_(other)
Determines whether this expression is greater than the given value
or expression, `self >= other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_le_\_(other)
Determines whether this expression is less than or equal to the
given value or expression, `self <= other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **other** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or a python primitive understood
by MongoDB
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_lt_\_(other)
Determines whether this expression is less than the given value or
expression, `self <= other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_ne_\_(other)
Determines whether this expression is not equal to the given value
or expression, `self != other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_and_\_(other)
Computes the logical AND of this expression and the given value or
expression, `self & other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_invert_\_()
Inverts this expression, `~self`.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_or_\_(other)
Computes the logical OR of this expression and the given value or
expression, `self | other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_abs_\_()
Computes the absolute value of this expression, which must resolve
to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_add_\_(other)
Adds the given value to this expression, which must resolve to a
numeric value, `self + other`.
Examples:
```default
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_ceil_\_()
Computes the ceiling of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_floor_\_()
Computes the floor of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_round_\_(place=0)
Rounds this expression, which must resolve to a numeric value, at
the given decimal place.
Positive values of `place` will round to `place` decimal
places:
```default
place=2: 1234.5678 --> 1234.57
```
Negative values of `place` will round digits left of the decimal:
```default
place=-2: 1234.5678 --> 1200
```
* **Parameters:**
**place** (*0*) – the decimal place at which to round. Must be an
integer in range `(-20, 100)`
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_mod_\_(other)
Computes the modulus of this expression, which must resolve to a
numeric value, `self % other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_mul_\_(other)
Computes the product of the given value and this expression, which
must resolve to a numeric value, `self * other`.
Examples:
```default
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_pow_\_(power, modulo=None)
Raises this expression, which must resolve to a numeric value, to
the given power, `self ** power`.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_sub_\_(other)
Subtracts the given value from this expression, which must resolve
to a numeric value, `self - other`.
Examples:
```default
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 [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_truediv_\_(other)
Divides this expression, which must resolve to a numeric value, by
the given value, `self / other`.
Examples:
```default
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 [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_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 non-unit step:
```default
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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
* **Parameters:**
**expr** – the MongoDB expression
**Attributes:**
| [`is_frozen`](#fiftyone.core.expressions.ViewExpression.is_frozen) | Whether this expression's prefix is frozen. |
|----------------------------------------------------------------------|-----------------------------------------------|
**Methods:**
| [`to_mongo`](#fiftyone.core.expressions.ViewExpression.to_mongo)([prefix]) | Returns a MongoDB representation of the expression. |
|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`exists`](#fiftyone.core.expressions.ViewExpression.exists)([bool]) | Determines whether this expression, which must resolve to a field, exists and is not None. |
| [`abs`](#fiftyone.core.expressions.ViewExpression.abs)() | Computes the absolute value of this expression, which must resolve to a numeric value. |
| [`floor`](#fiftyone.core.expressions.ViewExpression.floor)() | Computes the floor of this expression, which must resolve to a numeric value. |
| [`ceil`](#fiftyone.core.expressions.ViewExpression.ceil)() | Computes the ceiling of this expression, which must resolve to a numeric value. |
| [`round`](#fiftyone.core.expressions.ViewExpression.round)([place]) | Rounds this expression, which must resolve to a numeric value, at the given decimal place. |
| [`trunc`](#fiftyone.core.expressions.ViewExpression.trunc)([place]) | Truncates this expression, which must resolve to a numeric value, at the specified decimal place. |
| [`exp`](#fiftyone.core.expressions.ViewExpression.exp)() | Raises Euler's number to this expression, which must resolve to a numeric value. |
| [`ln`](#fiftyone.core.expressions.ViewExpression.ln)() | Computes the natural logarithm of this expression, which must resolve to a numeric value. |
| [`log`](#fiftyone.core.expressions.ViewExpression.log)(base) | Computes the logarithm base `base` of this expression, which must resolve to a numeric value. |
| [`log10`](#fiftyone.core.expressions.ViewExpression.log10)() | Computes the logarithm base 10 of this expression, which must resolve to a numeric value. |
| [`pow`](#fiftyone.core.expressions.ViewExpression.pow)(power) | Raises this expression, which must resolve to a numeric value, to the given power, `self ** power`. |
| [`sqrt`](#fiftyone.core.expressions.ViewExpression.sqrt)() | Computes the square root of this expression, which must resolve to a numeric value. |
| [`cos`](#fiftyone.core.expressions.ViewExpression.cos)() | Computes the cosine of this expression, which must resolve to a numeric value, in radians. |
| [`cosh`](#fiftyone.core.expressions.ViewExpression.cosh)() | Computes the hyperbolic cosine of this expression, which must resolve to a numeric value, in radians. |
| [`sin`](#fiftyone.core.expressions.ViewExpression.sin)() | Computes the sine of this expression, which must resolve to a numeric value, in radians. |
| [`sinh`](#fiftyone.core.expressions.ViewExpression.sinh)() | Computes the hyperbolic sine of this expression, which must resolve to a numeric value, in radians. |
| [`tan`](#fiftyone.core.expressions.ViewExpression.tan)() | Computes the tangent of this expression, which must resolve to a numeric value, in radians. |
| [`tanh`](#fiftyone.core.expressions.ViewExpression.tanh)() | Computes the hyperbolic tangent of this expression, which must resolve to a numeric value, in radians. |
| [`arccos`](#fiftyone.core.expressions.ViewExpression.arccos)() | Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians. |
| [`arccosh`](#fiftyone.core.expressions.ViewExpression.arccosh)() | Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians. |
| [`arcsin`](#fiftyone.core.expressions.ViewExpression.arcsin)() | Computes the inverse sine of this expression, which must resolve to a numeric value, in radians. |
| [`arcsinh`](#fiftyone.core.expressions.ViewExpression.arcsinh)() | Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians. |
| [`arctan`](#fiftyone.core.expressions.ViewExpression.arctan)() | Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians. |
| [`arctanh`](#fiftyone.core.expressions.ViewExpression.arctanh)() | Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians. |
| [`type`](#fiftyone.core.expressions.ViewExpression.type)() | Returns the type string of this expression. |
| [`is_null`](#fiftyone.core.expressions.ViewExpression.is_null)() | Determines whether this expression is null. |
| [`is_number`](#fiftyone.core.expressions.ViewExpression.is_number)() | Determines whether this expression is a number. |
| [`is_string`](#fiftyone.core.expressions.ViewExpression.is_string)() | Determines whether this expression is a string. |
| [`is_array`](#fiftyone.core.expressions.ViewExpression.is_array)() | Determines whether this expression is an array. |
| [`is_missing`](#fiftyone.core.expressions.ViewExpression.is_missing)() | Determines whether this expression refers to a missing field. |
| [`is_in`](#fiftyone.core.expressions.ViewExpression.is_in)(values) | Creates an expression that returns a boolean indicating whether `self in values`. |
| [`to_bool`](#fiftyone.core.expressions.ViewExpression.to_bool)() | Converts the expression to a boolean value. |
| [`to_int`](#fiftyone.core.expressions.ViewExpression.to_int)() | Converts the expression to an integer value. |
| [`to_double`](#fiftyone.core.expressions.ViewExpression.to_double)() | Converts the expression to a double precision value. |
| [`to_string`](#fiftyone.core.expressions.ViewExpression.to_string)() | Converts the expression to a string value. |
| [`to_date`](#fiftyone.core.expressions.ViewExpression.to_date)() | Converts the expression to a date value. |
| [`apply`](#fiftyone.core.expressions.ViewExpression.apply)(expr) | Applies the given expression to this expression. |
| [`if_else`](#fiftyone.core.expressions.ViewExpression.if_else)(true_expr, false_expr) | Returns either `true_expr` or `false_expr` depending on the value of this expression, which must resolve to a boolean. |
| [`if_null`](#fiftyone.core.expressions.ViewExpression.if_null)(false_expr) | Returns either this expression or `false_expr` if this expression is null. |
| [`cases`](#fiftyone.core.expressions.ViewExpression.cases)(mapping[, default]) | Applies a case statement to this expression, which effectively computes the following pseudocode. |
| [`switch`](#fiftyone.core.expressions.ViewExpression.switch)(mapping[, default]) | Applies a switch statement to this expression, which effectively computes the given pseudocode. |
| [`map_values`](#fiftyone.core.expressions.ViewExpression.map_values)(mapping) | Replaces this expression with the corresponding value in the provided mapping dict, if it is present as a key. |
| [`set_field`](#fiftyone.core.expressions.ViewExpression.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. |
| [`let_in`](#fiftyone.core.expressions.ViewExpression.let_in)(expr) | Returns an equivalent expression where this expression is defined as a variable that is used wherever necessary in the given expression. |
| [`min`](#fiftyone.core.expressions.ViewExpression.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. |
| [`max`](#fiftyone.core.expressions.ViewExpression.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. |
| [`length`](#fiftyone.core.expressions.ViewExpression.length)() | Computes the length of this expression, which must resolve to an array. |
| [`contains`](#fiftyone.core.expressions.ViewExpression.contains)(values[, all]) | Checks whether this expression, which must resolve to an array, contains any of the given values. |
| [`is_subset`](#fiftyone.core.expressions.ViewExpression.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. |
| [`set_equals`](#fiftyone.core.expressions.ViewExpression.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). |
| [`unique`](#fiftyone.core.expressions.ViewExpression.unique)() | Returns an array containing the unique values in this expression, which must resolve to an array. |
| [`union`](#fiftyone.core.expressions.ViewExpression.union)(\*args) | Computes the set union of this expression, which must resolve to an array, and the given array(s) or array expression(s). |
| [`intersection`](#fiftyone.core.expressions.ViewExpression.intersection)(\*args) | Computes the set intersection of this expression, which must resolve to an array, and the given array(s) or array expression(s). |
| [`difference`](#fiftyone.core.expressions.ViewExpression.difference)(values) | Computes the set difference of this expression, which must resolve to an array, and the given array or array expression. |
| [`reverse`](#fiftyone.core.expressions.ViewExpression.reverse)() | Reverses the order of the elements in the expression, which must resolve to an array. |
| [`sort`](#fiftyone.core.expressions.ViewExpression.sort)([key, numeric, reverse]) | Sorts this expression, which must resolve to an array. |
| [`filter`](#fiftyone.core.expressions.ViewExpression.filter)(expr) | Applies the given filter to the elements of this expression, which must resolve to an array. |
| [`map`](#fiftyone.core.expressions.ViewExpression.map)(expr) | Applies the given expression to the elements of this expression, which must resolve to an array. |
| [`reduce`](#fiftyone.core.expressions.ViewExpression.reduce)(expr[, init_val]) | Applies the given reduction to this expression, which must resolve to an array, and returns the single value computed. |
| [`prepend`](#fiftyone.core.expressions.ViewExpression.prepend)(value) | Prepends the given value to this expression, which must resolve to an array. |
| [`append`](#fiftyone.core.expressions.ViewExpression.append)(value) | Appends the given value to this expression, which must resolve to an array. |
| [`insert`](#fiftyone.core.expressions.ViewExpression.insert)(index, value) | Inserts the value before the given index in this expression, which must resolve to an array. |
| [`extend`](#fiftyone.core.expressions.ViewExpression.extend)(\*args) | Concatenates the given array(s) or array expression(s) to this expression, which must resolve to an array. |
| [`sum`](#fiftyone.core.expressions.ViewExpression.sum)() | Returns the sum of the values in this expression, which must resolve to a numeric array. |
| [`mean`](#fiftyone.core.expressions.ViewExpression.mean)() | Returns the average value in this expression, which must resolve to a numeric array. |
| [`std`](#fiftyone.core.expressions.ViewExpression.std)([sample]) | Returns the standard deviation of the values in this expression, which must resolve to a numeric array. |
| [`join`](#fiftyone.core.expressions.ViewExpression.join)(delimiter) | Joins the elements of this expression, which must resolve to a string array, by the given delimiter. |
| [`substr`](#fiftyone.core.expressions.ViewExpression.substr)([start, end, count]) | Extracts the specified substring from this expression, which must resolve to a string. |
| [`strlen`](#fiftyone.core.expressions.ViewExpression.strlen)() | Computes the length of this expression, which must resolve to a string. |
| [`lower`](#fiftyone.core.expressions.ViewExpression.lower)() | Converts this expression, which must resolve to a string, to lowercase. |
| [`upper`](#fiftyone.core.expressions.ViewExpression.upper)() | Converts this expression, which must resolve to a string, to uppercase. |
| [`concat`](#fiftyone.core.expressions.ViewExpression.concat)(\*args) | Concatenates the given string(s) to this expression, which must resolve to a string. |
| [`strip`](#fiftyone.core.expressions.ViewExpression.strip)([chars]) | Removes whitespace characters from the beginning and end of this expression, which must resolve to a string. |
| [`lstrip`](#fiftyone.core.expressions.ViewExpression.lstrip)([chars]) | Removes whitespace characters from the beginning of this expression, which must resolve to a string. |
| [`rstrip`](#fiftyone.core.expressions.ViewExpression.rstrip)([chars]) | Removes whitespace characters from the end of this expression, which must resolve to a string. |
| [`replace`](#fiftyone.core.expressions.ViewExpression.replace)(old, new) | Replaces all occurrences of `old` with `new` in this expression, which must resolve to a string. |
| [`re_match`](#fiftyone.core.expressions.ViewExpression.re_match)(regex[, options]) | Performs a regular expression pattern match on this expression, which must resolve to a string. |
| [`starts_with`](#fiftyone.core.expressions.ViewExpression.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). |
| [`ends_with`](#fiftyone.core.expressions.ViewExpression.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). |
| [`contains_str`](#fiftyone.core.expressions.ViewExpression.contains_str)(str_or_strs[, case_sensitive]) | Determines whether this expression, which must resolve to a string, contains the given string or string(s). |
| [`matches_str`](#fiftyone.core.expressions.ViewExpression.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). |
| [`split`](#fiftyone.core.expressions.ViewExpression.split)(delimiter[, maxsplit]) | Splits this expression, which must resolve to a string, by the given delimiter. |
| [`rsplit`](#fiftyone.core.expressions.ViewExpression.rsplit)(delimiter[, maxsplit]) | Splits this expression, which must resolve to a string, by the given delimiter. |
| [`millisecond`](#fiftyone.core.expressions.ViewExpression.millisecond)() | Returns the millisecond portion of this date expression (in UTC) as an integer between 0 and 999. |
| [`second`](#fiftyone.core.expressions.ViewExpression.second)() | Returns the second portion of this date expression (in UTC) as a number between 0 and 59. |
| [`minute`](#fiftyone.core.expressions.ViewExpression.minute)() | Returns the minute portion of this date expression (in UTC) as a number between 0 and 59. |
| [`hour`](#fiftyone.core.expressions.ViewExpression.hour)() | Returns the hour portion of this date expression (in UTC) as a number between 0 and 23. |
| [`day_of_week`](#fiftyone.core.expressions.ViewExpression.day_of_week)() | Returns the day of the week of this date expression (in UTC) as a number between 1 (Sunday) and 7 (Saturday). |
| [`day_of_month`](#fiftyone.core.expressions.ViewExpression.day_of_month)() | Returns the day of the month of this date expression (in UTC) as a number between 1 and 31. |
| [`day_of_year`](#fiftyone.core.expressions.ViewExpression.day_of_year)() | Returns the day of the year of this date expression (in UTC) as a number between 1 and 366. |
| [`week`](#fiftyone.core.expressions.ViewExpression.week)() | Returns the week of the year of this date expression (in UTC) as a number between 0 and 53. |
| [`month`](#fiftyone.core.expressions.ViewExpression.month)() | Returns the month of this date expression (in UTC) as a number between 1 and 12. |
| [`year`](#fiftyone.core.expressions.ViewExpression.year)() | Returns the year of this date expression (in UTC). |
| [`literal`](#fiftyone.core.expressions.ViewExpression.literal)(value) | Returns an expression representing the given value without parsing. |
| [`rand`](#fiftyone.core.expressions.ViewExpression.rand)() | Returns an expression that generates a uniform random float in `[0, 1]` each time it is called. |
| [`randn`](#fiftyone.core.expressions.ViewExpression.randn)() | Returns an expression that generates a sample from the standard Gaussian distribution each time it is called. |
| [`any`](#fiftyone.core.expressions.ViewExpression.any)(exprs) | Checks whether any of the given expressions evaluate to True. |
| [`all`](#fiftyone.core.expressions.ViewExpression.all)(exprs) | Checks whether all of the given expressions evaluate to True. |
| [`range`](#fiftyone.core.expressions.ViewExpression.range)(start[, stop]) | Returns an array expression containing the sequence of integers from the specified start (inclusive) to stop (exclusive). |
| [`enumerate`](#fiftyone.core.expressions.ViewExpression.enumerate)(array[, start]) | Returns an array of `[index, element]` pairs enumerating the elements of the given expression, which must resolve to an array. |
| [`zip`](#fiftyone.core.expressions.ViewExpression.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. |
#### *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`](#fiftyone.core.expressions.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:
```default
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 non-existent (False)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### abs()
Computes the absolute value of this expression, which must resolve
to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### floor()
Computes the floor of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### ceil()
Computes the ceiling of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### round(place=0)
Rounds this expression, which must resolve to a numeric value, at
the given decimal place.
Positive values of `place` will round to `place` decimal
places:
```default
place=2: 1234.5678 --> 1234.57
```
Negative values of `place` will round `place` digits left of the
decimal:
```default
place=-1: 1234.5678 --> 1230
```
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### trunc(place=0)
Truncates this expression, which must resolve to a numeric value, at
the specified decimal place.
Positive values of `place` will truncate to `place` decimal
places:
```default
place=2: 1234.5678 --> 1234.56
```
Negative values of `place` will replace `place` digits left of the
decimal with zero:
```default
place=-1: 1234.5678 --> 1230
```
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### exp()
Raises Euler’s number to this expression, which must resolve to a
numeric value.
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### ln()
Computes the natural logarithm of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### log(base)
Computes the logarithm base `base` of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### log10()
Computes the logarithm base 10 of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### pow(power)
Raises this expression, which must resolve to a numeric value, to
the given power, `self ** power`.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sqrt()
Computes the square root of this expression, which must resolve to a
numeric value.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cos()
Computes the cosine of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cosh()
Computes the hyperbolic cosine of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sin()
Computes the sine of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sinh()
Computes the hyperbolic sine of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### tan()
Computes the tangent of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### tanh()
Computes the hyperbolic tangent of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arccos()
Computes the inverse cosine of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arccosh()
Computes the inverse hyperbolic cosine of this expression, which
must resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arcsin()
Computes the inverse sine of this expression, which must resolve to
a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arcsinh()
Computes the inverse hyperbolic sine of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arctan()
Computes the inverse tangent of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arctanh()
Computes the inverse hyperbolic tangent of this expression, which
must resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### type()
Returns the type string of this expression.
See [this page](https://docs.mongodb.com/manual/reference/operator/aggregation/type)
for more details.
Examples:
```default
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 non-None uniqueness
unique_only_view = view.match(F("uniqueness").type() != "null")
print(len(unique_only_view))
```
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_null()
Determines whether this expression is null.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_number()
Determines whether this expression is a number.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_string()
Determines whether this expression is a string.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_array()
Determines whether this expression is an array.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_missing()
Determines whether this expression refers to a missing field.
Examples:
```default
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 non-existent field on all samples
view = dataset.match(F("foobar").is_missing())
print(len(view) == len(dataset))
```
* **Returns:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_in(values)
Creates an expression that returns a boolean indicating whether
`self in values`.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_bool()
Converts the expression to a boolean value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toBool)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_int()
Converts the expression to an integer value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toInt)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_double()
Converts the expression to a double precision value.
Examples:
```default
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](https://docs.mongodb.com/manual/reference/operator/aggregation/toDouble)
for conversion rules.
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_string()
Converts the expression to a string value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toString)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_date()
Converts the expression to a date value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toDate)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### apply(expr)
Applies the given expression to this expression.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### if_else(true_expr, false_expr)
Returns either `true_expr` or `false_expr` depending on the
value of this expression, which must resolve to a boolean.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **false_expr** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### if_null(false_expr)
Returns either this expression or `false_expr` if this expression is null.
This is a shortcut for `self.is_null().if_else(false_expr, self)` and is useful
for replacing null values in a field with a default value.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Set `gt.detection.label` field to "unknown" if it does not exist
view = dataset.set_field(
"gt.detection.label",
F("gt.detection.label").if_null("unknown")
)
```
* **Parameters:**
**false_expr** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cases(mapping, default=None)
Applies a case statement to this expression, which effectively
computes the following pseudocode:
```default
for key, value in mapping.items():
if self == key:
return value
if default is not None:
return default
```
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) keys to
literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) values
* **default** (*None*) – an optional literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) to
return if none of the switch branches are taken
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### switch(mapping, default=None)
Applies a switch statement to this expression, which effectively
computes the given pseudocode:
```default
for key, value in mapping.items():
if self.apply(key):
return value
if default is not None:
return default
```
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) keys to
literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) values
* **default** (*None*) – an optional literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) to
return if none of the switch branches are taken
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### map_values(mapping)
Replaces this expression with the corresponding value in the
provided mapping dict, if it is present as a key.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Replaces the `label` attributes 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`](#fiftyone.core.expressions.ViewExpression) defining
the field to set
* **relative** (*True*) – whether to compute `value_or_expr` by applying
it to this expression (True), or to use it untouched (False)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 a [`ViewField`](#fiftyone.core.expressions.ViewField), no
variable is defined and `expr` is directly returned.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
that resolves to an array of values
* **all** (*False*) – whether this expression must contain all (True) or
any (False) of the given values
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that
resolves to an array
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### unique()
Returns an array containing the unique values in this expression,
which must resolve to an array.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that
resolves to an array
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### reverse()
Reverses the order of the elements in the expression, which must
resolve to an array.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sort(key=None, numeric=False, 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 by `key`, which must be a field or embedded field.
Examples:
```default
#
# 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", numeric=True, 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 by
* **numeric** (*False*) – whether the array contains numeric values. By
default, the values will be sorted alphabetically by their
string representations
* **reverse** (*False*) – whether to sort in descending order
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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` returns `True`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) that returns a boolean
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 the [`VALUE`](#fiftyone.core.expressions.VALUE) expression to
properly define the reduction.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) defining the reduction expression
to apply. Must contain the [`VALUE`](#fiftyone.core.expressions.VALUE) expression
* **init_val** (*0*) – an initial value for the reduction
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### prepend(value)
Prepends the given value to this expression, which must resolve to
an array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### append(value)
Appends the given value to this expression, which must resolve to an
array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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.
If `index >= self.length()`, the value is appended to this array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### extend(\*args)
Concatenates the given array(s) or array expression(s) to this
expression, which must resolve to an array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sum()
Returns the sum of the values in this expression, which must resolve
to a numeric array.
Missing, non-numeric, or `None`-valued elements are ignored.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### mean()
Returns the average value in this expression, which must resolve to
a numeric array.
Missing or `None`-valued elements are ignored.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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](https://en.wikipedia.org/wiki/Standard_deviation#Estimation) for
more information on population (biased) vs sample (unbiased) standard
deviation.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### join(delimiter)
Joins the elements of this expression, which must resolve to a
string array, by the given delimiter.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### substr(start=None, end=None, count=None)
Extracts the specified substring from this expression, which must
resolve to a string.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### lower()
Converts this expression, which must resolve to a string, to
lowercase.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### upper()
Converts this expression, which must resolve to a string, to
uppercase.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### concat(\*args)
Concatenates the given string(s) to this expression, which must
resolve to a string.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
instances
* **before** (*False*) – whether to position `args` before this string in
the output string
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### replace(old, new)
Replaces all occurrences of `old` with `new` in this expression,
which must resolve to a string.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) resolving to a string
expression specifying the substring to replace
* **new** – a string or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) resolving to a string
expression specifying the replacement value
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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
and `False` otherwise.
Examples:
```default
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:**
* **regex** – the regular expression to apply. Must be a Perl Compatible
Regular Expression (PCRE). See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/regexMatch/#regexmatch-regex)
for details
* **options** (*None*) – an optional string of regex options to apply. See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/regexMatch/#regexmatch-options)
for the available options
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression
* **maxsplit** (*None*) – a maximum number of splits to perform, from the
left
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 last `maxsplit` occurrences 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Add "-ok-go" 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("-ok-go").rsplit("-", 1)
)
print(view.first().tags)
```
* **Parameters:**
* **delimiter** – the delimiter string or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression
* **maxsplit** (*None*) – a maximum number of splits to perform, from the
right
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### millisecond()
Returns the millisecond portion of this date expression (in UTC) as
an integer between 0 and 999.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### second()
Returns the second portion of this date expression (in UTC) as a
number between 0 and 59.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### minute()
Returns the minute portion of this date expression (in UTC) as a
number between 0 and 59.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### hour()
Returns the hour portion of this date expression (in UTC) as a
number between 0 and 23.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### day_of_month()
Returns the day of the month of this date expression (in UTC) as a
number between 1 and 31.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### day_of_year()
Returns the day of the year of this date expression (in UTC) as a
number between 1 and 366.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### week()
Returns the week of the year of this date expression (in UTC) as a
number between 0 and 53.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### month()
Returns the month of this date expression (in UTC) as a number
between 1 and 12.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### year()
Returns the year of this date expression (in UTC).
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* literal(value)
Returns an expression representing the given value without parsing.
See [this page](https://docs.mongodb.com/manual/reference/operator/aggregation/literal)
for more information on when this method is required.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.set_field) and
[`fiftyone.core.view.DatasetView.save()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.save) to populate a
randomized field on a dataset.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.set_field) and
[`fiftyone.core.view.DatasetView.save()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.save) to populate a
randomized field on a dataset.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* any(exprs)
Checks whether any of the given expressions evaluate to True.
If no expressions are provided, returns False.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or iterable of
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression) instances
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* all(exprs)
Checks whether all of the given expressions evaluate to True.
If no expressions are provided, returns True.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or iterable of
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression) instances
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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
provided
* **stop** (*None*) – the stopping value, if both input arguments are
provided
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that resolves to an array
* **start** (*0*) – the starting enumeration index to use
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances
resolving to arrays
* **use_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 when `use_longest == True` and the input
arrays are of different lengths. If no defaults are provided
and `use_longest == True`, then missing values are set to
`None`
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
### *class* fiftyone.core.expressions.ViewField(name=None)
Bases: [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
A [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) that refers to a field or embedded field of a
document.
You can use
[dot notation](https://docs.mongodb.com/manual/core/document/#dot-notation)
to refer to subfields of embedded objects within fields.
When you create a [`ViewField`](#fiftyone.core.expressions.ViewField) using a string field like
`ViewField("embedded.field.name")`, the meaning of this field is
interpreted relative to the context in which the [`ViewField`](#fiftyone.core.expressions.ViewField) object
is used. For example, when passed to the [`ViewExpression.map()`](#fiftyone.core.expressions.ViewExpression.map) method,
this object will refer to the `embedded.field.name` object of the array
element being processed.
In other cases, you may wish to create a [`ViewField`](#fiftyone.core.expressions.ViewField) that always
refers to the root document. You can do this by prepending `"$"` to the
name of the field, as in `ViewField("$embedded.field.name")`.
Examples:
```default
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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_ge_\_(other)
Determines whether this expression is greater than or equal to the
given value or expression, `self >= other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_gt_\_(other)
Determines whether this expression is greater than the given value
or expression, `self >= other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_le_\_(other)
Determines whether this expression is less than or equal to the
given value or expression, `self <= other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **other** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or a python primitive understood
by MongoDB
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_lt_\_(other)
Determines whether this expression is less than the given value or
expression, `self <= other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_ne_\_(other)
Determines whether this expression is not equal to the given value
or expression, `self != other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_and_\_(other)
Computes the logical AND of this expression and the given value or
expression, `self & other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_invert_\_()
Inverts this expression, `~self`.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_or_\_(other)
Computes the logical OR of this expression and the given value or
expression, `self | other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_abs_\_()
Computes the absolute value of this expression, which must resolve
to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_add_\_(other)
Adds the given value to this expression, which must resolve to a
numeric value, `self + other`.
Examples:
```default
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_ceil_\_()
Computes the ceiling of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_floor_\_()
Computes the floor of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_round_\_(place=0)
Rounds this expression, which must resolve to a numeric value, at
the given decimal place.
Positive values of `place` will round to `place` decimal
places:
```default
place=2: 1234.5678 --> 1234.57
```
Negative values of `place` will round digits left of the decimal:
```default
place=-2: 1234.5678 --> 1200
```
* **Parameters:**
**place** (*0*) – the decimal place at which to round. Must be an
integer in range `(-20, 100)`
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_mod_\_(other)
Computes the modulus of this expression, which must resolve to a
numeric value, `self % other`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_mul_\_(other)
Computes the product of the given value and this expression, which
must resolve to a numeric value, `self * other`.
Examples:
```default
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_pow_\_(power, modulo=None)
Raises this expression, which must resolve to a numeric value, to
the given power, `self ** power`.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_sub_\_(other)
Subtracts the given value from this expression, which must resolve
to a numeric value, `self - other`.
Examples:
```default
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 [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_truediv_\_(other)
Divides this expression, which must resolve to a numeric value, by
the given value, `self / other`.
Examples:
```default
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 [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### \_\_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 non-unit step:
```default
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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
* **Parameters:**
**name** (*None*) – the name of the field, with an optional “$” prepended if
you wish to freeze this field to the root document
**Methods:**
| [`to_mongo`](#fiftyone.core.expressions.ViewField.to_mongo)([prefix]) | Returns a MongoDB representation of the field. |
|----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`abs`](#fiftyone.core.expressions.ViewField.abs)() | Computes the absolute value of this expression, which must resolve to a numeric value. |
| [`all`](#fiftyone.core.expressions.ViewField.all)(exprs) | Checks whether all of the given expressions evaluate to True. |
| [`any`](#fiftyone.core.expressions.ViewField.any)(exprs) | Checks whether any of the given expressions evaluate to True. |
| [`append`](#fiftyone.core.expressions.ViewField.append)(value) | Appends the given value to this expression, which must resolve to an array. |
| [`apply`](#fiftyone.core.expressions.ViewField.apply)(expr) | Applies the given expression to this expression. |
| [`arccos`](#fiftyone.core.expressions.ViewField.arccos)() | Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians. |
| [`arccosh`](#fiftyone.core.expressions.ViewField.arccosh)() | Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians. |
| [`arcsin`](#fiftyone.core.expressions.ViewField.arcsin)() | Computes the inverse sine of this expression, which must resolve to a numeric value, in radians. |
| [`arcsinh`](#fiftyone.core.expressions.ViewField.arcsinh)() | Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians. |
| [`arctan`](#fiftyone.core.expressions.ViewField.arctan)() | Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians. |
| [`arctanh`](#fiftyone.core.expressions.ViewField.arctanh)() | Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians. |
| [`cases`](#fiftyone.core.expressions.ViewField.cases)(mapping[, default]) | Applies a case statement to this expression, which effectively computes the following pseudocode. |
| [`ceil`](#fiftyone.core.expressions.ViewField.ceil)() | Computes the ceiling of this expression, which must resolve to a numeric value. |
| [`concat`](#fiftyone.core.expressions.ViewField.concat)(\*args) | Concatenates the given string(s) to this expression, which must resolve to a string. |
| [`contains`](#fiftyone.core.expressions.ViewField.contains)(values[, all]) | Checks whether this expression, which must resolve to an array, contains any of the given values. |
| [`contains_str`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.cos)() | Computes the cosine of this expression, which must resolve to a numeric value, in radians. |
| [`cosh`](#fiftyone.core.expressions.ViewField.cosh)() | Computes the hyperbolic cosine of this expression, which must resolve to a numeric value, in radians. |
| [`day_of_month`](#fiftyone.core.expressions.ViewField.day_of_month)() | Returns the day of the month of this date expression (in UTC) as a number between 1 and 31. |
| [`day_of_week`](#fiftyone.core.expressions.ViewField.day_of_week)() | Returns the day of the week of this date expression (in UTC) as a number between 1 (Sunday) and 7 (Saturday). |
| [`day_of_year`](#fiftyone.core.expressions.ViewField.day_of_year)() | Returns the day of the year of this date expression (in UTC) as a number between 1 and 366. |
| [`difference`](#fiftyone.core.expressions.ViewField.difference)(values) | Computes the set difference of this expression, which must resolve to an array, and the given array or array expression. |
| [`ends_with`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.enumerate)(array[, start]) | Returns an array of `[index, element]` pairs enumerating the elements of the given expression, which must resolve to an array. |
| [`exists`](#fiftyone.core.expressions.ViewField.exists)([bool]) | Determines whether this expression, which must resolve to a field, exists and is not None. |
| [`exp`](#fiftyone.core.expressions.ViewField.exp)() | Raises Euler's number to this expression, which must resolve to a numeric value. |
| [`extend`](#fiftyone.core.expressions.ViewField.extend)(\*args) | Concatenates the given array(s) or array expression(s) to this expression, which must resolve to an array. |
| [`filter`](#fiftyone.core.expressions.ViewField.filter)(expr) | Applies the given filter to the elements of this expression, which must resolve to an array. |
| [`floor`](#fiftyone.core.expressions.ViewField.floor)() | Computes the floor of this expression, which must resolve to a numeric value. |
| [`hour`](#fiftyone.core.expressions.ViewField.hour)() | Returns the hour portion of this date expression (in UTC) as a number between 0 and 23. |
| [`if_else`](#fiftyone.core.expressions.ViewField.if_else)(true_expr, false_expr) | Returns either `true_expr` or `false_expr` depending on the value of this expression, which must resolve to a boolean. |
| [`if_null`](#fiftyone.core.expressions.ViewField.if_null)(false_expr) | Returns either this expression or `false_expr` if this expression is null. |
| [`insert`](#fiftyone.core.expressions.ViewField.insert)(index, value) | Inserts the value before the given index in this expression, which must resolve to an array. |
| [`intersection`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.is_array)() | Determines whether this expression is an array. |
| [`is_in`](#fiftyone.core.expressions.ViewField.is_in)(values) | Creates an expression that returns a boolean indicating whether `self in values`. |
| [`is_missing`](#fiftyone.core.expressions.ViewField.is_missing)() | Determines whether this expression refers to a missing field. |
| [`is_null`](#fiftyone.core.expressions.ViewField.is_null)() | Determines whether this expression is null. |
| [`is_number`](#fiftyone.core.expressions.ViewField.is_number)() | Determines whether this expression is a number. |
| [`is_string`](#fiftyone.core.expressions.ViewField.is_string)() | Determines whether this expression is a string. |
| [`is_subset`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.join)(delimiter) | Joins the elements of this expression, which must resolve to a string array, by the given delimiter. |
| [`length`](#fiftyone.core.expressions.ViewField.length)() | Computes the length of this expression, which must resolve to an array. |
| [`let_in`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.literal)(value) | Returns an expression representing the given value without parsing. |
| [`ln`](#fiftyone.core.expressions.ViewField.ln)() | Computes the natural logarithm of this expression, which must resolve to a numeric value. |
| [`log`](#fiftyone.core.expressions.ViewField.log)(base) | Computes the logarithm base `base` of this expression, which must resolve to a numeric value. |
| [`log10`](#fiftyone.core.expressions.ViewField.log10)() | Computes the logarithm base 10 of this expression, which must resolve to a numeric value. |
| [`lower`](#fiftyone.core.expressions.ViewField.lower)() | Converts this expression, which must resolve to a string, to lowercase. |
| [`lstrip`](#fiftyone.core.expressions.ViewField.lstrip)([chars]) | Removes whitespace characters from the beginning of this expression, which must resolve to a string. |
| [`map`](#fiftyone.core.expressions.ViewField.map)(expr) | Applies the given expression to the elements of this expression, which must resolve to an array. |
| [`map_values`](#fiftyone.core.expressions.ViewField.map_values)(mapping) | Replaces this expression with the corresponding value in the provided mapping dict, if it is present as a key. |
| [`matches_str`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.mean)() | Returns the average value in this expression, which must resolve to a numeric array. |
| [`millisecond`](#fiftyone.core.expressions.ViewField.millisecond)() | Returns the millisecond portion of this date expression (in UTC) as an integer between 0 and 999. |
| [`min`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.minute)() | Returns the minute portion of this date expression (in UTC) as a number between 0 and 59. |
| [`month`](#fiftyone.core.expressions.ViewField.month)() | Returns the month of this date expression (in UTC) as a number between 1 and 12. |
| [`pow`](#fiftyone.core.expressions.ViewField.pow)(power) | Raises this expression, which must resolve to a numeric value, to the given power, `self ** power`. |
| [`prepend`](#fiftyone.core.expressions.ViewField.prepend)(value) | Prepends the given value to this expression, which must resolve to an array. |
| [`rand`](#fiftyone.core.expressions.ViewField.rand)() | Returns an expression that generates a uniform random float in `[0, 1]` each time it is called. |
| [`randn`](#fiftyone.core.expressions.ViewField.randn)() | Returns an expression that generates a sample from the standard Gaussian distribution each time it is called. |
| [`range`](#fiftyone.core.expressions.ViewField.range)(start[, stop]) | Returns an array expression containing the sequence of integers from the specified start (inclusive) to stop (exclusive). |
| [`re_match`](#fiftyone.core.expressions.ViewField.re_match)(regex[, options]) | Performs a regular expression pattern match on this expression, which must resolve to a string. |
| [`reduce`](#fiftyone.core.expressions.ViewField.reduce)(expr[, init_val]) | Applies the given reduction to this expression, which must resolve to an array, and returns the single value computed. |
| [`replace`](#fiftyone.core.expressions.ViewField.replace)(old, new) | Replaces all occurrences of `old` with `new` in this expression, which must resolve to a string. |
| [`reverse`](#fiftyone.core.expressions.ViewField.reverse)() | Reverses the order of the elements in the expression, which must resolve to an array. |
| [`round`](#fiftyone.core.expressions.ViewField.round)([place]) | Rounds this expression, which must resolve to a numeric value, at the given decimal place. |
| [`rsplit`](#fiftyone.core.expressions.ViewField.rsplit)(delimiter[, maxsplit]) | Splits this expression, which must resolve to a string, by the given delimiter. |
| [`rstrip`](#fiftyone.core.expressions.ViewField.rstrip)([chars]) | Removes whitespace characters from the end of this expression, which must resolve to a string. |
| [`second`](#fiftyone.core.expressions.ViewField.second)() | Returns the second portion of this date expression (in UTC) as a number between 0 and 59. |
| [`set_equals`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.sin)() | Computes the sine of this expression, which must resolve to a numeric value, in radians. |
| [`sinh`](#fiftyone.core.expressions.ViewField.sinh)() | Computes the hyperbolic sine of this expression, which must resolve to a numeric value, in radians. |
| [`sort`](#fiftyone.core.expressions.ViewField.sort)([key, numeric, reverse]) | Sorts this expression, which must resolve to an array. |
| [`split`](#fiftyone.core.expressions.ViewField.split)(delimiter[, maxsplit]) | Splits this expression, which must resolve to a string, by the given delimiter. |
| [`sqrt`](#fiftyone.core.expressions.ViewField.sqrt)() | Computes the square root of this expression, which must resolve to a numeric value. |
| [`starts_with`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.std)([sample]) | Returns the standard deviation of the values in this expression, which must resolve to a numeric array. |
| [`strip`](#fiftyone.core.expressions.ViewField.strip)([chars]) | Removes whitespace characters from the beginning and end of this expression, which must resolve to a string. |
| [`strlen`](#fiftyone.core.expressions.ViewField.strlen)() | Computes the length of this expression, which must resolve to a string. |
| [`substr`](#fiftyone.core.expressions.ViewField.substr)([start, end, count]) | Extracts the specified substring from this expression, which must resolve to a string. |
| [`sum`](#fiftyone.core.expressions.ViewField.sum)() | Returns the sum of the values in this expression, which must resolve to a numeric array. |
| [`switch`](#fiftyone.core.expressions.ViewField.switch)(mapping[, default]) | Applies a switch statement to this expression, which effectively computes the given pseudocode. |
| [`tan`](#fiftyone.core.expressions.ViewField.tan)() | Computes the tangent of this expression, which must resolve to a numeric value, in radians. |
| [`tanh`](#fiftyone.core.expressions.ViewField.tanh)() | Computes the hyperbolic tangent of this expression, which must resolve to a numeric value, in radians. |
| [`to_bool`](#fiftyone.core.expressions.ViewField.to_bool)() | Converts the expression to a boolean value. |
| [`to_date`](#fiftyone.core.expressions.ViewField.to_date)() | Converts the expression to a date value. |
| [`to_double`](#fiftyone.core.expressions.ViewField.to_double)() | Converts the expression to a double precision value. |
| [`to_int`](#fiftyone.core.expressions.ViewField.to_int)() | Converts the expression to an integer value. |
| [`to_string`](#fiftyone.core.expressions.ViewField.to_string)() | Converts the expression to a string value. |
| [`trunc`](#fiftyone.core.expressions.ViewField.trunc)([place]) | Truncates this expression, which must resolve to a numeric value, at the specified decimal place. |
| [`type`](#fiftyone.core.expressions.ViewField.type)() | Returns the type string of this expression. |
| [`union`](#fiftyone.core.expressions.ViewField.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`](#fiftyone.core.expressions.ViewField.unique)() | Returns an array containing the unique values in this expression, which must resolve to an array. |
| [`upper`](#fiftyone.core.expressions.ViewField.upper)() | Converts this expression, which must resolve to a string, to uppercase. |
| [`week`](#fiftyone.core.expressions.ViewField.week)() | Returns the week of the year of this date expression (in UTC) as a number between 0 and 53. |
| [`year`](#fiftyone.core.expressions.ViewField.year)() | Returns the year of this date expression (in UTC). |
| [`zip`](#fiftyone.core.expressions.ViewField.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:**
| [`is_frozen`](#fiftyone.core.expressions.ViewField.is_frozen) | 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* all(exprs)
Checks whether all of the given expressions evaluate to True.
If no expressions are provided, returns True.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or iterable of
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression) instances
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* any(exprs)
Checks whether any of the given expressions evaluate to True.
If no expressions are provided, returns False.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or iterable of
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression) instances
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### append(value)
Appends the given value to this expression, which must resolve to an
array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### apply(expr)
Applies the given expression to this expression.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arccos()
Computes the inverse cosine of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arccosh()
Computes the inverse hyperbolic cosine of this expression, which
must resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arcsin()
Computes the inverse sine of this expression, which must resolve to
a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arcsinh()
Computes the inverse hyperbolic sine of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arctan()
Computes the inverse tangent of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arctanh()
Computes the inverse hyperbolic tangent of this expression, which
must resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cases(mapping, default=None)
Applies a case statement to this expression, which effectively
computes the following pseudocode:
```default
for key, value in mapping.items():
if self == key:
return value
if default is not None:
return default
```
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) keys to
literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) values
* **default** (*None*) – an optional literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) to
return if none of the switch branches are taken
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### ceil()
Computes the ceiling of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### concat(\*args)
Concatenates the given string(s) to this expression, which must
resolve to a string.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
instances
* **before** (*False*) – whether to position `args` before this string in
the output string
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
that resolves to an array of values
* **all** (*False*) – whether this expression must contain all (True) or
any (False) of the given values
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cos()
Computes the cosine of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cosh()
Computes the hyperbolic cosine of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### day_of_month()
Returns the day of the month of this date expression (in UTC) as a
number between 1 and 31.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### day_of_year()
Returns the day of the year of this date expression (in UTC) as a
number between 1 and 366.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that
resolves to an array
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that resolves to an array
* **start** (*0*) – the starting enumeration index to use
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### exists(bool=True)
Determines whether this expression, which must resolve to a field,
exists and is not None.
Examples:
```default
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 non-existent (False)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### exp()
Raises Euler’s number to this expression, which must resolve to a
numeric value.
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### extend(\*args)
Concatenates the given array(s) or array expression(s) to this
expression, which must resolve to an array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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` returns `True`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) that returns a boolean
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### floor()
Computes the floor of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### hour()
Returns the hour portion of this date expression (in UTC) as a
number between 0 and 23.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### if_else(true_expr, false_expr)
Returns either `true_expr` or `false_expr` depending on the
value of this expression, which must resolve to a boolean.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **false_expr** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### if_null(false_expr)
Returns either this expression or `false_expr` if this expression is null.
This is a shortcut for `self.is_null().if_else(false_expr, self)` and is useful
for replacing null values in a field with a default value.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Set `gt.detection.label` field to "unknown" if it does not exist
view = dataset.set_field(
"gt.detection.label",
F("gt.detection.label").if_null("unknown")
)
```
* **Parameters:**
**false_expr** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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.
If `index >= self.length()`, the value is appended to this array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_array()
Determines whether this expression is an array.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_missing()
Determines whether this expression refers to a missing field.
Examples:
```default
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 non-existent field on all samples
view = dataset.match(F("foobar").is_missing())
print(len(view) == len(dataset))
```
* **Returns:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_null()
Determines whether this expression is null.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_number()
Determines whether this expression is a number.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_string()
Determines whether this expression is a string.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that
resolves to an array
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### join(delimiter)
Joins the elements of this expression, which must resolve to a
string array, by the given delimiter.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 a [`ViewField`](#fiftyone.core.expressions.ViewField), no
variable is defined and `expr` is directly returned.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* literal(value)
Returns an expression representing the given value without parsing.
See [this page](https://docs.mongodb.com/manual/reference/operator/aggregation/literal)
for more information on when this method is required.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### ln()
Computes the natural logarithm of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### log(base)
Computes the logarithm base `base` of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### log10()
Computes the logarithm base 10 of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### lower()
Converts this expression, which must resolve to a string, to
lowercase.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### map_values(mapping)
Replaces this expression with the corresponding value in the
provided mapping dict, if it is present as a key.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### mean()
Returns the average value in this expression, which must resolve to
a numeric array.
Missing or `None`-valued elements are ignored.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### millisecond()
Returns the millisecond portion of this date expression (in UTC) as
an integer between 0 and 999.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### minute()
Returns the minute portion of this date expression (in UTC) as a
number between 0 and 59.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### month()
Returns the month of this date expression (in UTC) as a number
between 1 and 12.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### pow(power)
Raises this expression, which must resolve to a numeric value, to
the given power, `self ** power`.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### prepend(value)
Prepends the given value to this expression, which must resolve to
an array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.set_field) and
[`fiftyone.core.view.DatasetView.save()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.save) to populate a
randomized field on a dataset.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.set_field) and
[`fiftyone.core.view.DatasetView.save()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.save) to populate a
randomized field on a dataset.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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
provided
* **stop** (*None*) – the stopping value, if both input arguments are
provided
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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
and `False` otherwise.
Examples:
```default
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:**
* **regex** – the regular expression to apply. Must be a Perl Compatible
Regular Expression (PCRE). See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/regexMatch/#regexmatch-regex)
for details
* **options** (*None*) – an optional string of regex options to apply. See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/regexMatch/#regexmatch-options)
for the available options
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 the [`VALUE`](#fiftyone.core.expressions.VALUE) expression to
properly define the reduction.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) defining the reduction expression
to apply. Must contain the [`VALUE`](#fiftyone.core.expressions.VALUE) expression
* **init_val** (*0*) – an initial value for the reduction
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### replace(old, new)
Replaces all occurrences of `old` with `new` in this expression,
which must resolve to a string.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) resolving to a string
expression specifying the substring to replace
* **new** – a string or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) resolving to a string
expression specifying the replacement value
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### reverse()
Reverses the order of the elements in the expression, which must
resolve to an array.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### round(place=0)
Rounds this expression, which must resolve to a numeric value, at
the given decimal place.
Positive values of `place` will round to `place` decimal
places:
```default
place=2: 1234.5678 --> 1234.57
```
Negative values of `place` will round `place` digits left of the
decimal:
```default
place=-1: 1234.5678 --> 1230
```
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 last `maxsplit` occurrences 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Add "-ok-go" 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("-ok-go").rsplit("-", 1)
)
print(view.first().tags)
```
* **Parameters:**
* **delimiter** – the delimiter string or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression
* **maxsplit** (*None*) – a maximum number of splits to perform, from the
right
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### second()
Returns the second portion of this date expression (in UTC) as a
number between 0 and 59.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Replaces the `label` attributes 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`](#fiftyone.core.expressions.ViewExpression) defining
the field to set
* **relative** (*True*) – whether to compute `value_or_expr` by applying
it to this expression (True), or to use it untouched (False)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sin()
Computes the sine of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sinh()
Computes the hyperbolic sine of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sort(key=None, numeric=False, 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 by `key`, which must be a field or embedded field.
Examples:
```default
#
# 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", numeric=True, 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 by
* **numeric** (*False*) – whether the array contains numeric values. By
default, the values will be sorted alphabetically by their
string representations
* **reverse** (*False*) – whether to sort in descending order
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression
* **maxsplit** (*None*) – a maximum number of splits to perform, from the
left
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sqrt()
Computes the square root of this expression, which must resolve to a
numeric value.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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](https://en.wikipedia.org/wiki/Standard_deviation#Estimation) for
more information on population (biased) vs sample (unbiased) standard
deviation.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### substr(start=None, end=None, count=None)
Extracts the specified substring from this expression, which must
resolve to a string.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sum()
Returns the sum of the values in this expression, which must resolve
to a numeric array.
Missing, non-numeric, or `None`-valued elements are ignored.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### switch(mapping, default=None)
Applies a switch statement to this expression, which effectively
computes the given pseudocode:
```default
for key, value in mapping.items():
if self.apply(key):
return value
if default is not None:
return default
```
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) keys to
literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) values
* **default** (*None*) – an optional literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) to
return if none of the switch branches are taken
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### tan()
Computes the tangent of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### tanh()
Computes the hyperbolic tangent of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_bool()
Converts the expression to a boolean value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toBool)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_date()
Converts the expression to a date value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toDate)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_double()
Converts the expression to a double precision value.
Examples:
```default
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](https://docs.mongodb.com/manual/reference/operator/aggregation/toDouble)
for conversion rules.
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_int()
Converts the expression to an integer value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toInt)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_string()
Converts the expression to a string value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toString)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### trunc(place=0)
Truncates this expression, which must resolve to a numeric value, at
the specified decimal place.
Positive values of `place` will truncate to `place` decimal
places:
```default
place=2: 1234.5678 --> 1234.56
```
Negative values of `place` will replace `place` digits left of the
decimal with zero:
```default
place=-1: 1234.5678 --> 1230
```
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### type()
Returns the type string of this expression.
See [this page](https://docs.mongodb.com/manual/reference/operator/aggregation/type)
for more details.
Examples:
```default
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 non-None uniqueness
unique_only_view = view.match(F("uniqueness").type() != "null")
print(len(unique_only_view))
```
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### unique()
Returns an array containing the unique values in this expression,
which must resolve to an array.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### upper()
Converts this expression, which must resolve to a string, to
uppercase.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### week()
Returns the week of the year of this date expression (in UTC) as a
number between 0 and 53.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### year()
Returns the year of this date expression (in UTC).
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances
resolving to arrays
* **use_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 when `use_longest == True` and the input
arrays are of different lengths. If no defaults are provided
and `use_longest == True`, then missing values are set to
`None`
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
### *class* fiftyone.core.expressions.ObjectId(oid)
Bases: [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
A [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) that refers to an
[ObjectId](https://docs.mongodb.com/manual/reference/method/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:
```default
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:**
| [`to_mongo`](#fiftyone.core.expressions.ObjectId.to_mongo)([prefix]) | Returns a MongoDB representation of the ObjectId. |
|---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`abs`](#fiftyone.core.expressions.ObjectId.abs)() | Computes the absolute value of this expression, which must resolve to a numeric value. |
| [`all`](#fiftyone.core.expressions.ObjectId.all)(exprs) | Checks whether all of the given expressions evaluate to True. |
| [`any`](#fiftyone.core.expressions.ObjectId.any)(exprs) | Checks whether any of the given expressions evaluate to True. |
| [`append`](#fiftyone.core.expressions.ObjectId.append)(value) | Appends the given value to this expression, which must resolve to an array. |
| [`apply`](#fiftyone.core.expressions.ObjectId.apply)(expr) | Applies the given expression to this expression. |
| [`arccos`](#fiftyone.core.expressions.ObjectId.arccos)() | Computes the inverse cosine of this expression, which must resolve to a numeric value, in radians. |
| [`arccosh`](#fiftyone.core.expressions.ObjectId.arccosh)() | Computes the inverse hyperbolic cosine of this expression, which must resolve to a numeric value, in radians. |
| [`arcsin`](#fiftyone.core.expressions.ObjectId.arcsin)() | Computes the inverse sine of this expression, which must resolve to a numeric value, in radians. |
| [`arcsinh`](#fiftyone.core.expressions.ObjectId.arcsinh)() | Computes the inverse hyperbolic sine of this expression, which must resolve to a numeric value, in radians. |
| [`arctan`](#fiftyone.core.expressions.ObjectId.arctan)() | Computes the inverse tangent of this expression, which must resolve to a numeric value, in radians. |
| [`arctanh`](#fiftyone.core.expressions.ObjectId.arctanh)() | Computes the inverse hyperbolic tangent of this expression, which must resolve to a numeric value, in radians. |
| [`cases`](#fiftyone.core.expressions.ObjectId.cases)(mapping[, default]) | Applies a case statement to this expression, which effectively computes the following pseudocode. |
| [`ceil`](#fiftyone.core.expressions.ObjectId.ceil)() | Computes the ceiling of this expression, which must resolve to a numeric value. |
| [`concat`](#fiftyone.core.expressions.ObjectId.concat)(\*args) | Concatenates the given string(s) to this expression, which must resolve to a string. |
| [`contains`](#fiftyone.core.expressions.ObjectId.contains)(values[, all]) | Checks whether this expression, which must resolve to an array, contains any of the given values. |
| [`contains_str`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.cos)() | Computes the cosine of this expression, which must resolve to a numeric value, in radians. |
| [`cosh`](#fiftyone.core.expressions.ObjectId.cosh)() | Computes the hyperbolic cosine of this expression, which must resolve to a numeric value, in radians. |
| [`day_of_month`](#fiftyone.core.expressions.ObjectId.day_of_month)() | Returns the day of the month of this date expression (in UTC) as a number between 1 and 31. |
| [`day_of_week`](#fiftyone.core.expressions.ObjectId.day_of_week)() | Returns the day of the week of this date expression (in UTC) as a number between 1 (Sunday) and 7 (Saturday). |
| [`day_of_year`](#fiftyone.core.expressions.ObjectId.day_of_year)() | Returns the day of the year of this date expression (in UTC) as a number between 1 and 366. |
| [`difference`](#fiftyone.core.expressions.ObjectId.difference)(values) | Computes the set difference of this expression, which must resolve to an array, and the given array or array expression. |
| [`ends_with`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.enumerate)(array[, start]) | Returns an array of `[index, element]` pairs enumerating the elements of the given expression, which must resolve to an array. |
| [`exists`](#fiftyone.core.expressions.ObjectId.exists)([bool]) | Determines whether this expression, which must resolve to a field, exists and is not None. |
| [`exp`](#fiftyone.core.expressions.ObjectId.exp)() | Raises Euler's number to this expression, which must resolve to a numeric value. |
| [`extend`](#fiftyone.core.expressions.ObjectId.extend)(\*args) | Concatenates the given array(s) or array expression(s) to this expression, which must resolve to an array. |
| [`filter`](#fiftyone.core.expressions.ObjectId.filter)(expr) | Applies the given filter to the elements of this expression, which must resolve to an array. |
| [`floor`](#fiftyone.core.expressions.ObjectId.floor)() | Computes the floor of this expression, which must resolve to a numeric value. |
| [`hour`](#fiftyone.core.expressions.ObjectId.hour)() | Returns the hour portion of this date expression (in UTC) as a number between 0 and 23. |
| [`if_else`](#fiftyone.core.expressions.ObjectId.if_else)(true_expr, false_expr) | Returns either `true_expr` or `false_expr` depending on the value of this expression, which must resolve to a boolean. |
| [`if_null`](#fiftyone.core.expressions.ObjectId.if_null)(false_expr) | Returns either this expression or `false_expr` if this expression is null. |
| [`insert`](#fiftyone.core.expressions.ObjectId.insert)(index, value) | Inserts the value before the given index in this expression, which must resolve to an array. |
| [`intersection`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.is_array)() | Determines whether this expression is an array. |
| [`is_in`](#fiftyone.core.expressions.ObjectId.is_in)(values) | Creates an expression that returns a boolean indicating whether `self in values`. |
| [`is_missing`](#fiftyone.core.expressions.ObjectId.is_missing)() | Determines whether this expression refers to a missing field. |
| [`is_null`](#fiftyone.core.expressions.ObjectId.is_null)() | Determines whether this expression is null. |
| [`is_number`](#fiftyone.core.expressions.ObjectId.is_number)() | Determines whether this expression is a number. |
| [`is_string`](#fiftyone.core.expressions.ObjectId.is_string)() | Determines whether this expression is a string. |
| [`is_subset`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.join)(delimiter) | Joins the elements of this expression, which must resolve to a string array, by the given delimiter. |
| [`length`](#fiftyone.core.expressions.ObjectId.length)() | Computes the length of this expression, which must resolve to an array. |
| [`let_in`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.literal)(value) | Returns an expression representing the given value without parsing. |
| [`ln`](#fiftyone.core.expressions.ObjectId.ln)() | Computes the natural logarithm of this expression, which must resolve to a numeric value. |
| [`log`](#fiftyone.core.expressions.ObjectId.log)(base) | Computes the logarithm base `base` of this expression, which must resolve to a numeric value. |
| [`log10`](#fiftyone.core.expressions.ObjectId.log10)() | Computes the logarithm base 10 of this expression, which must resolve to a numeric value. |
| [`lower`](#fiftyone.core.expressions.ObjectId.lower)() | Converts this expression, which must resolve to a string, to lowercase. |
| [`lstrip`](#fiftyone.core.expressions.ObjectId.lstrip)([chars]) | Removes whitespace characters from the beginning of this expression, which must resolve to a string. |
| [`map`](#fiftyone.core.expressions.ObjectId.map)(expr) | Applies the given expression to the elements of this expression, which must resolve to an array. |
| [`map_values`](#fiftyone.core.expressions.ObjectId.map_values)(mapping) | Replaces this expression with the corresponding value in the provided mapping dict, if it is present as a key. |
| [`matches_str`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.mean)() | Returns the average value in this expression, which must resolve to a numeric array. |
| [`millisecond`](#fiftyone.core.expressions.ObjectId.millisecond)() | Returns the millisecond portion of this date expression (in UTC) as an integer between 0 and 999. |
| [`min`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.minute)() | Returns the minute portion of this date expression (in UTC) as a number between 0 and 59. |
| [`month`](#fiftyone.core.expressions.ObjectId.month)() | Returns the month of this date expression (in UTC) as a number between 1 and 12. |
| [`pow`](#fiftyone.core.expressions.ObjectId.pow)(power) | Raises this expression, which must resolve to a numeric value, to the given power, `self ** power`. |
| [`prepend`](#fiftyone.core.expressions.ObjectId.prepend)(value) | Prepends the given value to this expression, which must resolve to an array. |
| [`rand`](#fiftyone.core.expressions.ObjectId.rand)() | Returns an expression that generates a uniform random float in `[0, 1]` each time it is called. |
| [`randn`](#fiftyone.core.expressions.ObjectId.randn)() | Returns an expression that generates a sample from the standard Gaussian distribution each time it is called. |
| [`range`](#fiftyone.core.expressions.ObjectId.range)(start[, stop]) | Returns an array expression containing the sequence of integers from the specified start (inclusive) to stop (exclusive). |
| [`re_match`](#fiftyone.core.expressions.ObjectId.re_match)(regex[, options]) | Performs a regular expression pattern match on this expression, which must resolve to a string. |
| [`reduce`](#fiftyone.core.expressions.ObjectId.reduce)(expr[, init_val]) | Applies the given reduction to this expression, which must resolve to an array, and returns the single value computed. |
| [`replace`](#fiftyone.core.expressions.ObjectId.replace)(old, new) | Replaces all occurrences of `old` with `new` in this expression, which must resolve to a string. |
| [`reverse`](#fiftyone.core.expressions.ObjectId.reverse)() | Reverses the order of the elements in the expression, which must resolve to an array. |
| [`round`](#fiftyone.core.expressions.ObjectId.round)([place]) | Rounds this expression, which must resolve to a numeric value, at the given decimal place. |
| [`rsplit`](#fiftyone.core.expressions.ObjectId.rsplit)(delimiter[, maxsplit]) | Splits this expression, which must resolve to a string, by the given delimiter. |
| [`rstrip`](#fiftyone.core.expressions.ObjectId.rstrip)([chars]) | Removes whitespace characters from the end of this expression, which must resolve to a string. |
| [`second`](#fiftyone.core.expressions.ObjectId.second)() | Returns the second portion of this date expression (in UTC) as a number between 0 and 59. |
| [`set_equals`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.sin)() | Computes the sine of this expression, which must resolve to a numeric value, in radians. |
| [`sinh`](#fiftyone.core.expressions.ObjectId.sinh)() | Computes the hyperbolic sine of this expression, which must resolve to a numeric value, in radians. |
| [`sort`](#fiftyone.core.expressions.ObjectId.sort)([key, numeric, reverse]) | Sorts this expression, which must resolve to an array. |
| [`split`](#fiftyone.core.expressions.ObjectId.split)(delimiter[, maxsplit]) | Splits this expression, which must resolve to a string, by the given delimiter. |
| [`sqrt`](#fiftyone.core.expressions.ObjectId.sqrt)() | Computes the square root of this expression, which must resolve to a numeric value. |
| [`starts_with`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.std)([sample]) | Returns the standard deviation of the values in this expression, which must resolve to a numeric array. |
| [`strip`](#fiftyone.core.expressions.ObjectId.strip)([chars]) | Removes whitespace characters from the beginning and end of this expression, which must resolve to a string. |
| [`strlen`](#fiftyone.core.expressions.ObjectId.strlen)() | Computes the length of this expression, which must resolve to a string. |
| [`substr`](#fiftyone.core.expressions.ObjectId.substr)([start, end, count]) | Extracts the specified substring from this expression, which must resolve to a string. |
| [`sum`](#fiftyone.core.expressions.ObjectId.sum)() | Returns the sum of the values in this expression, which must resolve to a numeric array. |
| [`switch`](#fiftyone.core.expressions.ObjectId.switch)(mapping[, default]) | Applies a switch statement to this expression, which effectively computes the given pseudocode. |
| [`tan`](#fiftyone.core.expressions.ObjectId.tan)() | Computes the tangent of this expression, which must resolve to a numeric value, in radians. |
| [`tanh`](#fiftyone.core.expressions.ObjectId.tanh)() | Computes the hyperbolic tangent of this expression, which must resolve to a numeric value, in radians. |
| [`to_bool`](#fiftyone.core.expressions.ObjectId.to_bool)() | Converts the expression to a boolean value. |
| [`to_date`](#fiftyone.core.expressions.ObjectId.to_date)() | Converts the expression to a date value. |
| [`to_double`](#fiftyone.core.expressions.ObjectId.to_double)() | Converts the expression to a double precision value. |
| [`to_int`](#fiftyone.core.expressions.ObjectId.to_int)() | Converts the expression to an integer value. |
| [`to_string`](#fiftyone.core.expressions.ObjectId.to_string)() | Converts the expression to a string value. |
| [`trunc`](#fiftyone.core.expressions.ObjectId.trunc)([place]) | Truncates this expression, which must resolve to a numeric value, at the specified decimal place. |
| [`type`](#fiftyone.core.expressions.ObjectId.type)() | Returns the type string of this expression. |
| [`union`](#fiftyone.core.expressions.ObjectId.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`](#fiftyone.core.expressions.ObjectId.unique)() | Returns an array containing the unique values in this expression, which must resolve to an array. |
| [`upper`](#fiftyone.core.expressions.ObjectId.upper)() | Converts this expression, which must resolve to a string, to uppercase. |
| [`week`](#fiftyone.core.expressions.ObjectId.week)() | Returns the week of the year of this date expression (in UTC) as a number between 0 and 53. |
| [`year`](#fiftyone.core.expressions.ObjectId.year)() | Returns the year of this date expression (in UTC). |
| [`zip`](#fiftyone.core.expressions.ObjectId.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:**
| [`is_frozen`](#fiftyone.core.expressions.ObjectId.is_frozen) | 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* all(exprs)
Checks whether all of the given expressions evaluate to True.
If no expressions are provided, returns True.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or iterable of
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression) instances
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* any(exprs)
Checks whether any of the given expressions evaluate to True.
If no expressions are provided, returns False.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or iterable of
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression) instances
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### append(value)
Appends the given value to this expression, which must resolve to an
array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### apply(expr)
Applies the given expression to this expression.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arccos()
Computes the inverse cosine of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arccosh()
Computes the inverse hyperbolic cosine of this expression, which
must resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arcsin()
Computes the inverse sine of this expression, which must resolve to
a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arcsinh()
Computes the inverse hyperbolic sine of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arctan()
Computes the inverse tangent of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### arctanh()
Computes the inverse hyperbolic tangent of this expression, which
must resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cases(mapping, default=None)
Applies a case statement to this expression, which effectively
computes the following pseudocode:
```default
for key, value in mapping.items():
if self == key:
return value
if default is not None:
return default
```
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) keys to
literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) values
* **default** (*None*) – an optional literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) to
return if none of the switch branches are taken
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### ceil()
Computes the ceiling of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### concat(\*args)
Concatenates the given string(s) to this expression, which must
resolve to a string.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
instances
* **before** (*False*) – whether to position `args` before this string in
the output string
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
that resolves to an array of values
* **all** (*False*) – whether this expression must contain all (True) or
any (False) of the given values
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cos()
Computes the cosine of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### cosh()
Computes the hyperbolic cosine of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### day_of_month()
Returns the day of the month of this date expression (in UTC) as a
number between 1 and 31.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### day_of_year()
Returns the day of the year of this date expression (in UTC) as a
number between 1 and 366.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that
resolves to an array
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that resolves to an array
* **start** (*0*) – the starting enumeration index to use
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### exists(bool=True)
Determines whether this expression, which must resolve to a field,
exists and is not None.
Examples:
```default
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 non-existent (False)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### exp()
Raises Euler’s number to this expression, which must resolve to a
numeric value.
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### extend(\*args)
Concatenates the given array(s) or array expression(s) to this
expression, which must resolve to an array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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` returns `True`.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) that returns a boolean
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### floor()
Computes the floor of this expression, which must resolve to a
numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### hour()
Returns the hour portion of this date expression (in UTC) as a
number between 0 and 23.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### if_else(true_expr, false_expr)
Returns either `true_expr` or `false_expr` depending on the
value of this expression, which must resolve to a boolean.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **false_expr** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### if_null(false_expr)
Returns either this expression or `false_expr` if this expression is null.
This is a shortcut for `self.is_null().if_else(false_expr, self)` and is useful
for replacing null values in a field with a default value.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Set `gt.detection.label` field to "unknown" if it does not exist
view = dataset.set_field(
"gt.detection.label",
F("gt.detection.label").if_null("unknown")
)
```
* **Parameters:**
**false_expr** – a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) or MongoDB expression dict
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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.
If `index >= self.length()`, the value is appended to this array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_array()
Determines whether this expression is an array.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_missing()
Determines whether this expression refers to a missing field.
Examples:
```default
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 non-existent field on all samples
view = dataset.match(F("foobar").is_missing())
print(len(view) == len(dataset))
```
* **Returns:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_null()
Determines whether this expression is null.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_number()
Determines whether this expression is a number.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### is_string()
Determines whether this expression is a string.
Examples:
```default
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:**
[`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) that
resolves to an array
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### join(delimiter)
Joins the elements of this expression, which must resolve to a
string array, by the given delimiter.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 a [`ViewField`](#fiftyone.core.expressions.ViewField), no
variable is defined and `expr` is directly returned.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *static* literal(value)
Returns an expression representing the given value without parsing.
See [this page](https://docs.mongodb.com/manual/reference/operator/aggregation/literal)
for more information on when this method is required.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### ln()
Computes the natural logarithm of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### log(base)
Computes the logarithm base `base` of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### log10()
Computes the logarithm base 10 of this expression, which must
resolve to a numeric value.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### lower()
Converts this expression, which must resolve to a string, to
lowercase.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### map_values(mapping)
Replaces this expression with the corresponding value in the
provided mapping dict, if it is present as a key.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### mean()
Returns the average value in this expression, which must resolve to
a numeric array.
Missing or `None`-valued elements are ignored.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### millisecond()
Returns the millisecond portion of this date expression (in UTC) as
an integer between 0 and 999.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### minute()
Returns the minute portion of this date expression (in UTC) as a
number between 0 and 59.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### month()
Returns the month of this date expression (in UTC) as a number
between 1 and 12.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### pow(power)
Raises this expression, which must resolve to a numeric value, to
the given power, `self ** power`.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### prepend(value)
Prepends the given value to this expression, which must resolve to
an array.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.set_field) and
[`fiftyone.core.view.DatasetView.save()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.save) to populate a
randomized field on a dataset.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.set_field) and
[`fiftyone.core.view.DatasetView.save()`](fiftyone.core.view.md#fiftyone.core.view.DatasetView.save) to populate a
randomized field on a dataset.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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
provided
* **stop** (*None*) – the stopping value, if both input arguments are
provided
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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
and `False` otherwise.
Examples:
```default
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:**
* **regex** – the regular expression to apply. Must be a Perl Compatible
Regular Expression (PCRE). See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/regexMatch/#regexmatch-regex)
for details
* **options** (*None*) – an optional string of regex options to apply. See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/regexMatch/#regexmatch-options)
for the available options
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 the [`VALUE`](#fiftyone.core.expressions.VALUE) expression to
properly define the reduction.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) defining the reduction expression
to apply. Must contain the [`VALUE`](#fiftyone.core.expressions.VALUE) expression
* **init_val** (*0*) – an initial value for the reduction
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### replace(old, new)
Replaces all occurrences of `old` with `new` in this expression,
which must resolve to a string.
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) resolving to a string
expression specifying the substring to replace
* **new** – a string or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) resolving to a string
expression specifying the replacement value
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### reverse()
Reverses the order of the elements in the expression, which must
resolve to an array.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### round(place=0)
Rounds this expression, which must resolve to a numeric value, at
the given decimal place.
Positive values of `place` will round to `place` decimal
places:
```default
place=2: 1234.5678 --> 1234.57
```
Negative values of `place` will round `place` digits left of the
decimal:
```default
place=-1: 1234.5678 --> 1230
```
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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 last `maxsplit` occurrences 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Add "-ok-go" 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("-ok-go").rsplit("-", 1)
)
print(view.first().tags)
```
* **Parameters:**
* **delimiter** – the delimiter string or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression
* **maxsplit** (*None*) – a maximum number of splits to perform, from the
right
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### second()
Returns the second portion of this date expression (in UTC) as a
number between 0 and 59.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
#
# Replaces the `label` attributes 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`](#fiftyone.core.expressions.ViewExpression) defining
the field to set
* **relative** (*True*) – whether to compute `value_or_expr` by applying
it to this expression (True), or to use it untouched (False)
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sin()
Computes the sine of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sinh()
Computes the hyperbolic sine of this expression, which must resolve
to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sort(key=None, numeric=False, 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 by `key`, which must be a field or embedded field.
Examples:
```default
#
# 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", numeric=True, 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 by
* **numeric** (*False*) – whether the array contains numeric values. By
default, the values will be sorted alphabetically by their
string representations
* **reverse** (*False*) – whether to sort in descending order
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression
* **maxsplit** (*None*) – a maximum number of splits to perform, from the
left
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sqrt()
Computes the square root of this expression, which must resolve to a
numeric value.
Examples:
```default
import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F
dataset = foz.load_zoo_dataset("quickstart")
# Bboxes are in [top-left-x, top-left-y, 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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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](https://en.wikipedia.org/wiki/Standard_deviation#Estimation) for
more information on population (biased) vs sample (unbiased) standard
deviation.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression)
resolving to a string expression specifying characters to
remove
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### substr(start=None, end=None, count=None)
Extracts the specified substring from this expression, which must
resolve to a string.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### sum()
Returns the sum of the values in this expression, which must resolve
to a numeric array.
Missing, non-numeric, or `None`-valued elements are ignored.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### switch(mapping, default=None)
Applies a switch statement to this expression, which effectively
computes the given pseudocode:
```default
for key, value in mapping.items():
if self.apply(key):
return value
if default is not None:
return default
```
Examples:
```default
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`](#fiftyone.core.expressions.ViewExpression) keys to
literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) values
* **default** (*None*) – an optional literal or [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) to
return if none of the switch branches are taken
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### tan()
Computes the tangent of this expression, which must resolve to a
numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### tanh()
Computes the hyperbolic tangent of this expression, which must
resolve to a numeric value, in radians.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_bool()
Converts the expression to a boolean value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toBool)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_date()
Converts the expression to a date value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toDate)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_double()
Converts the expression to a double precision value.
Examples:
```default
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](https://docs.mongodb.com/manual/reference/operator/aggregation/toDouble)
for conversion rules.
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_int()
Converts the expression to an integer value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toInt)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### to_string()
Converts the expression to a string value.
See
[this page](https://docs.mongodb.com/manual/reference/operator/aggregation/toString)
for conversion rules.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### trunc(place=0)
Truncates this expression, which must resolve to a numeric value, at
the specified decimal place.
Positive values of `place` will truncate to `place` decimal
places:
```default
place=2: 1234.5678 --> 1234.56
```
Negative values of `place` will replace `place` digits left of the
decimal with zero:
```default
place=-1: 1234.5678 --> 1230
```
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### type()
Returns the type string of this expression.
See [this page](https://docs.mongodb.com/manual/reference/operator/aggregation/type)
for more details.
Examples:
```default
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 non-None uniqueness
unique_only_view = view.match(F("uniqueness").type() != "null")
print(len(unique_only_view))
```
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### 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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances that
resolve to array expressions
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### unique()
Returns an array containing the unique values in this expression,
which must resolve to an array.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### upper()
Converts this expression, which must resolve to a string, to
uppercase.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### week()
Returns the week of the year of this date expression (in UTC) as a
number between 0 and 53.
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### year()
Returns the year of this date expression (in UTC).
Examples:
```default
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:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
#### *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:
```default
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`](#fiftyone.core.expressions.ViewExpression) instances
resolving to arrays
* **use_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 when `use_longest == True` and the input
arrays are of different lengths. If no defaults are provided
and `use_longest == True`, then missing values are set to
`None`
* **Returns:**
a [`ViewExpression`](#fiftyone.core.expressions.ViewExpression)
### fiftyone.core.expressions.VALUE(field) *= '$$value'*
A [`ViewExpression`](#fiftyone.core.expressions.ViewExpression) that refers to the current `$$value` in a
MongoDB reduction expression.
See [`ViewExpression.reduce()`](#fiftyone.core.expressions.ViewExpression.reduce) for more information.