fiftyone.core.aggregations¶
Aggregations.
Classes

Abstract base class for all aggregations. 

Computes the bounds of a numeric field of a collection. 

Counts the number of field values in a collection. 

Counts the occurrences of field values in a collection. 

Computes the distinct values of a field in a collection. 

Computes a histogram of the field values in a collection. 

Computes the arithmetic mean of the field values of a collection. 

Computes the standard deviation of the field values of a collection. 

Computes the sum of the field values of a collection. 

Extracts the values of the field from all samples in a collection. 
Exceptions
An error raised during the execution of an 

class
fiftyone.core.aggregations.
Aggregation
(field_name, expr=None)¶ Bases:
object
Abstract base class for all aggregations.
Aggregation
instances represent an aggregation or reduction of afiftyone.core.collections.SampleCollection
instance. Parameters
field_name – the name of the field to operate on
expr (None) – an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregating

property
field_name
¶ The field name being computed on.

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
the aggregation result

default_result
()¶ Returns the default result for this aggregation.
 Returns
the aggregation result

exception
fiftyone.core.aggregations.
AggregationError
¶ Bases:
Exception
An error raised during the execution of an
Aggregation
.
args
¶

with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.


class
fiftyone.core.aggregations.
Bounds
(field_name, expr=None)¶ Bases:
fiftyone.core.aggregations.Aggregation
Computes the bounds of a numeric field of a collection.
None
valued fields are ignored.This aggregation is typically applied to numeric field types (or lists of such types):
Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="/path/to/image1.png", numeric_field=1.0, numeric_list_field=[1, 2, 3], ), fo.Sample( filepath="/path/to/image2.png", numeric_field=4.0, numeric_list_field=[1, 2], ), fo.Sample( filepath="/path/to/image3.png", numeric_field=None, numeric_list_field=None, ), ] ) # # Compute the bounds of a numeric field # aggregation = fo.Bounds("numeric_field") bounds = dataset.aggregate(aggregation) print(bounds) # (min, max) # # Compute the a bounds of a numeric list field # aggregation = fo.Bounds("numeric_list_field") bounds = dataset.aggregate(aggregation) print(bounds) # (min, max) # # Compute the bounds of a transformation of a numeric field # aggregation = fo.Bounds("numeric_field", expr=2 * (F() + 1)) bounds = dataset.aggregate(aggregation) print(bounds) # (min, max)
 Parameters
field_name – the name of the field to operate on
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregating

default_result
()¶ Returns the default result for this aggregation.
 Returns
(None, None)

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
the
(min, max)
bounds

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.

class
fiftyone.core.aggregations.
Count
(field_name=None, expr=None)¶ Bases:
fiftyone.core.aggregations.Aggregation
Counts the number of field values in a collection.
None
valued fields are ignored.If no field is provided, the samples themselves are counted.
Examples:
import fiftyone as fo dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="/path/to/image1.png", predictions=fo.Detections( detections=[ fo.Detection(label="cat"), fo.Detection(label="dog"), ] ), ), fo.Sample( filepath="/path/to/image2.png", predictions=fo.Detections( detections=[ fo.Detection(label="cat"), fo.Detection(label="rabbit"), fo.Detection(label="squirrel"), ] ), ), fo.Sample( filepath="/path/to/image3.png", predictions=None, ), ] ) # # Count the number of samples in the dataset # aggregation = fo.Count() count = dataset.aggregate(aggregation) print(count) # the count # # Count the number of samples with `predictions` # aggregation = fo.Count("predictions") count = dataset.aggregate(aggregation) print(count) # the count # # Count the number of objects in the `predictions` field # aggregation = fo.Count("predictions.detections") count = dataset.aggregate(aggregation) print(count) # the count # # Count the number of samples with more than 2 predictions # expr = (F("detections").length() > 2).if_else(F("detections"), None) aggregation = fo.Count("predictions", expr=expr) count = dataset.aggregate(aggregation) print(count) # the count
 Parameters
field_name (None) – the name of the field to operate on. If none is provided, the samples themselves are counted
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregating

default_result
()¶ Returns the default result for this aggregation.
 Returns
0

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
the count

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.

class
fiftyone.core.aggregations.
CountValues
(field_name, expr=None)¶ Bases:
fiftyone.core.aggregations.Aggregation
Counts the occurrences of field values in a collection.
This aggregation is typically applied to countable field types (or lists of such types):
Examples:
import fiftyone as fo dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="/path/to/image1.png", tags=["sunny"], predictions=fo.Detections( detections=[ fo.Detection(label="cat"), fo.Detection(label="dog"), ] ), ), fo.Sample( filepath="/path/to/image2.png", tags=["cloudy"], predictions=fo.Detections( detections=[ fo.Detection(label="cat"), fo.Detection(label="rabbit"), ] ), ), fo.Sample( filepath="/path/to/image3.png", predictions=None, ), ] ) # # Compute the tag counts in the dataset # aggregation = fo.CountValues("tags") counts = dataset.aggregate(aggregation) print(counts) # dict mapping values to counts # # Compute the predicted label counts in the dataset # aggregation = fo.CountValues("predictions.detections.label") counts = dataset.aggregate(aggregation) print(counts) # dict mapping values to counts # # Compute the predicted label counts after some normalization # expr = F().map_values({"cat": "pet", "dog": "pet"}).upper() aggregation = fo.CountValues("predictions.detections.label", expr=expr) counts = dataset.aggregate(aggregation) print(counts) # dict mapping values to counts
 Parameters
field_name – the name of the field to operate on
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregating

default_result
()¶ Returns the default result for this aggregation.
 Returns
{}

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
a dict mapping values to counts

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.

class
fiftyone.core.aggregations.
Distinct
(field_name, expr=None)¶ Bases:
fiftyone.core.aggregations.Aggregation
Computes the distinct values of a field in a collection.
None
valued fields are ignored.This aggregation is typically applied to countable field types (or lists of such types):
Examples:
import fiftyone as fo dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="/path/to/image1.png", tags=["sunny"], predictions=fo.Detections( detections=[ fo.Detection(label="cat"), fo.Detection(label="dog"), ] ), ), fo.Sample( filepath="/path/to/image2.png", tags=["sunny", "cloudy"], predictions=fo.Detections( detections=[ fo.Detection(label="cat"), fo.Detection(label="rabbit"), ] ), ), fo.Sample( filepath="/path/to/image3.png", predictions=None, ), ] ) # # Get the distinct tags in a dataset # aggregation = fo.Distinct("tags") values = dataset.aggregate(aggregation) print(values) # list of distinct values # # Get the distinct predicted labels in a dataset # aggregation = fo.Distinct("predictions.detections.label") values = dataset.aggregate(aggregation) print(values) # list of distinct values # # Get the distinct predicted labels after some normalization # expr = F().map_values({"cat": "pet", "dog": "pet"}).upper() aggregation = fo.Distinct("predictions.detections.label", expr=expr) values = dataset.aggregate(aggregation) print(values) # list of distinct values
 Parameters
field_name – the name of the field to operate on
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregating

default_result
()¶ Returns the default result for this aggregation.
 Returns
[]

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
a sorted list of distinct values

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.

class
fiftyone.core.aggregations.
HistogramValues
(field_name, expr=None, bins=None, range=None, auto=False)¶ Bases:
fiftyone.core.aggregations.Aggregation
Computes a histogram of the field values in a collection.
This aggregation is typically applied to numeric field types (or lists of such types):
Examples:
import numpy as np import matplotlib.pyplot as plt import fiftyone as fo samples = [] for idx in range(100): samples.append( fo.Sample( filepath="/path/to/image%d.png" % idx, numeric_field=np.random.randn(), numeric_list_field=list(np.random.randn(10)), ) ) dataset = fo.Dataset() dataset.add_samples(samples) def plot_hist(counts, edges): counts = np.asarray(counts) edges = np.asarray(edges) left_edges = edges[:1] widths = edges[1:]  edges[:1] plt.bar(left_edges, counts, width=widths, align="edge") # # Compute a histogram of a numeric field # aggregation = fo.HistogramValues("numeric_field", bins=50) counts, edges, other = dataset.aggregate(aggregation) plot_hist(counts, edges) plt.show(block=False) # # Compute the histogram of a numeric list field # aggregation = fo.HistogramValues("numeric_list_field", bins=50) counts, edges, other = dataset.aggregate(aggregation) plot_hist(counts, edges) plt.show(block=False) # # Compute the histogram of a transformation of a numeric field # aggregation = fo.HistogramValues( "numeric_field", expr=2 * (F() + 1), bins=50 ) counts, edges, other = dataset.aggregate(aggregation) plot_hist(counts, edges) plt.show(block=False)
 Parameters
field_name – the name of the field to operate on
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregatingbins (None) – can be either an integer number of bins to generate or a monotonically increasing sequence specifying the bin edges to use. By default, 10 bins are created. If
bins
is an integer and norange
is specified, bin edges are automatically computed from the bounds of the fieldrange (None) – a
(lower, upper)
tuple specifying a range in which to generate equalwidth bins. Only applicable whenbins
is an integer orNone
auto (False) – whether to automatically choose bin edges in an attempt to evenly distribute the counts in each bin. If this option is chosen,
bins
will only be used if it is an integer, and therange
parameter is ignored

default_result
()¶ Returns the default result for this aggregation.
 Returns
a tuple of
counts:
[]
edges:
[]
other:
0

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
a tuple of
counts: a list of counts in each bin
edges: an increasing list of bin edges of length
len(counts) + 1
. Note that each bin is treated as having an inclusive lower boundary and exclusive upper boundary,[lower, upper)
, including the rightmost binother: the number of items outside the bins

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.

class
fiftyone.core.aggregations.
Mean
(field_name, expr=None)¶ Bases:
fiftyone.core.aggregations.Aggregation
Computes the arithmetic mean of the field values of a collection.
None
valued fields are ignored.This aggregation is typically applied to numeric field types (or lists of such types):
Examples:
import fiftyone as fo dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="/path/to/image1.png", numeric_field=1.0, numeric_list_field=[1, 2, 3], ), fo.Sample( filepath="/path/to/image2.png", numeric_field=4.0, numeric_list_field=[1, 2], ), fo.Sample( filepath="/path/to/image3.png", numeric_field=None, numeric_list_field=None, ), ] ) # # Compute the mean of a numeric field # aggregation = fo.Mean("numeric_field") mean = dataset.aggregate(aggregation) print(mean) # the mean # # Compute the mean of a numeric list field # aggregation = fo.Mean("numeric_list_field") mean = dataset.aggregate(aggregation) print(mean) # the mean # # Compute the mean of a transformation of a numeric field # aggregation = fo.Mean("numeric_field", expr=2 * (F() + 1)) mean = dataset.aggregate(aggregation) print(mean) # the mean
 Parameters
field_name – the name of the field to operate on
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregating

default_result
()¶ Returns the default result for this aggregation.
 Returns
0

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
the mean

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.

class
fiftyone.core.aggregations.
Std
(field_name, expr=None, sample=False)¶ Bases:
fiftyone.core.aggregations.Aggregation
Computes the standard deviation of the field values of a collection.
None
valued fields are ignored.This aggregation is typically applied to numeric field types (or lists of such types):
Examples:
import fiftyone as fo dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="/path/to/image1.png", numeric_field=1.0, numeric_list_field=[1, 2, 3], ), fo.Sample( filepath="/path/to/image2.png", numeric_field=4.0, numeric_list_field=[1, 2], ), fo.Sample( filepath="/path/to/image3.png", numeric_field=None, numeric_list_field=None, ), ] ) # # Compute the standard deviation of a numeric field # aggregation = fo.Std("numeric_field") std = dataset.aggregate(aggregation) print(std) # the standard deviation # # Compute the standard deviation of a numeric list field # aggregation = fo.Std("numeric_list_field") std = dataset.aggregate(aggregation) print(std) # the standard deviation # # Compute the standard deviation of a transformation of a numeric field # aggregation = fo.Std("numeric_field", expr=2 * (F() + 1)) std = dataset.aggregate(aggregation) print(std) # the standard deviation
 Parameters
field_name – the name of the field to operate on
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregatingsample (False) – whether to compute the sample standard deviation rather than the population standard deviation

default_result
()¶ Returns the default result for this aggregation.
 Returns
0

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
the standard deviation

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.

class
fiftyone.core.aggregations.
Sum
(field_name, expr=None)¶ Bases:
fiftyone.core.aggregations.Aggregation
Computes the sum of the field values of a collection.
None
valued fields are ignored.This aggregation is typically applied to numeric field types (or lists of such types):
Examples:
import fiftyone as fo dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="/path/to/image1.png", numeric_field=1.0, numeric_list_field=[1, 2, 3], ), fo.Sample( filepath="/path/to/image2.png", numeric_field=4.0, numeric_list_field=[1, 2], ), fo.Sample( filepath="/path/to/image3.png", numeric_field=None, numeric_list_field=None, ), ] ) # # Compute the sum of a numeric field # aggregation = fo.Sum("numeric_field") total = dataset.aggregate(aggregation) print(total) # the sum # # Compute the sum of a numeric list field # aggregation = fo.Sum("numeric_list_field") total = dataset.aggregate(aggregation) print(total) # the sum # # Compute the sum of a transformation of a numeric field # aggregation = fo.Sum("numeric_field", expr=2 * (F() + 1)) total = dataset.aggregate(aggregation) print(total) # the sum
 Parameters
field_name – the name of the field to operate on
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregating

default_result
()¶ Returns the default result for this aggregation.
 Returns
0

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
the sum

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.

class
fiftyone.core.aggregations.
Values
(field_name, expr=None, missing_value=None, unwind=False, _allow_missing=False)¶ Bases:
fiftyone.core.aggregations.Aggregation
Extracts the values of the field from all samples in a collection.
Note
Unlike other aggregations,
Values
does not automatically unwind list fields, which ensures that the returned values match the potentiallynested structure of the documents.You can optin to unwinding specific list fields using the
[]
syntax, or you can pass the optionalunwind=True
parameter to unwind all supported list fields. See Aggregating list fields for more information.Examples:
import fiftyone as fo from fiftyone import ViewField as F dataset = fo.Dataset() dataset.add_samples( [ fo.Sample( filepath="/path/to/image1.png", numeric_field=1.0, numeric_list_field=[1, 2, 3], ), fo.Sample( filepath="/path/to/image2.png", numeric_field=4.0, numeric_list_field=[1, 2], ), fo.Sample( filepath="/path/to/image3.png", numeric_field=None, numeric_list_field=None, ), ] ) # # Get all values of a field # aggregation = fo.Values("numeric_field") values = dataset.aggregate(aggregation) print(values) # [1.0, 4.0, None] # # Get all values of a list field # aggregation = fo.Values("numeric_list_field") values = dataset.aggregate(aggregation) print(values) # [[1, 2, 3], [1, 2], None] # # Get all values of transformed field # aggregation = fo.Values("numeric_field", expr=2 * (F() + 1)) values = dataset.aggregate(aggregation) print(values) # [4.0, 10.0, None]
 Parameters
field_name – the name of the field to operate on
expr (None) –
an optional
fiftyone.core.expressions.ViewExpression
or MongoDB expression to apply to the field before aggregatingmissing_value (None) – a value to insert for missing or
None
valued fieldsunwind (False) – whether to automatically unwind all recognized list fields

default_result
()¶ Returns the default result for this aggregation.
 Returns
[]

parse_result
(d)¶ Parses the output of
to_mongo()
. Parameters
d – the result dict
 Returns
the list of field values

to_mongo
(sample_collection)¶ Returns the MongoDB aggregation pipeline for this aggregation.
 Parameters
sample_collection – the
fiftyone.core.collections.SampleCollection
to which the aggregation is being applied Returns
a MongoDB aggregation pipeline (list of dicts)

property
expr
¶ The
fiftyone.core.expressions.ViewExpression
or MongoDB expression that will be applied to the field before aggregating, if any.

property
field_name
¶ The field name being computed on.