fiftyone.core.stages.GroupBy

class documentation

class GroupBy(ViewStage): (source)

Constructor: GroupBy(field_or_expr, order_by, reverse, flat, ...)

Creates a view that groups the samples in a collection by a specified field or expression.

Examples:

import fiftyone as fo
import fiftyone.zoo as foz
from fiftyone import ViewField as F

dataset = foz.load_zoo_dataset("cifar10", split="test")

#
# Take 1000 samples at random and group them by ground truth label
#

stage = fo.GroupBy("ground_truth.label")
view = dataset.take(1000).add_stage(stage)

for group in view.iter_groups():
    print("%s: %d" % (group[0].ground_truth.label, len(group)))

#
# Variation of above operation that arranges the groups in decreasing
# order of size and immediately flattens them
#

from itertools import groupby

stage = fo.GroupBy(
    "ground_truth.label",
    flat=True,
    sort_expr=F().length(),
    reverse=True,
)
view = dataset.take(1000).add_stage(stage)

rle = lambda v: [(k, len(list(g))) for k, g in groupby(v)]
for label, count in rle(view.values("ground_truth.label")):
    print("%s: %d" % (label, count))

Parameters
field_or_expr	the field or `embedded.field.name` to group by, or a list of field names defining a compound group key, or a `fiftyone.core.expressions.ViewExpression` or MongoDB aggregation expression that defines the value to group by
order_by	an optional field by which to order the samples in each group
reverse	whether to return the results in descending order. Applies to both `order_by` and `sort_expr`
flat	whether to return a grouped collection (False) or a flattened collection (True)
match_expr	an optional `fiftyone.core.expressions.ViewExpression` or MongoDB aggregation expression that defines which groups to include in the output view. If provided, this expression will be evaluated on the list of samples in each group. Only applicable when `flat=True`
sort_expr	an optional `fiftyone.core.expressions.ViewExpression` or MongoDB aggregation expression that defines how to sort the groups in the output view. If provided, this expression will be evaluated on the list of samples in each group. Only applicable when `flat=True`
create_index	whether to create an index, if necessary, to optimize the grouping. Only applicable when grouping by field(s), not expressions

Method	`__init__`	Undocumented
Method	`get_group_expr`	Returns the dynamic group expression for the given stage, if any.
Method	`get_media_type`	Returns the media type outputted by this stage when applied to the given collection, if and only if it is different from the input type.
Method	`to_mongo`	Returns the MongoDB aggregation pipeline for the stage.
Method	`validate`	Validates that the stage can be applied to the given collection.
Property	`create_index`	Whether to create an index, if necessary, to optimize the grouping.
Property	`field_or_expr`	The field or expression to group by.
Property	`flat`	Whether to generate a flattened collection.
Property	`match_expr`	An expression to apply to select groups in the output view.
Property	`order_by`	The field by which to order the samples in each group.
Property	`outputs_dynamic_groups`	Whether this stage outputs or flattens dynamic groups.
Property	`reverse`	Whether to sort the groups in descending order.
Property	`sort_expr`	An expression defining how the sort the groups in the output view.
Class Method	`_params`	Returns a list of JSON dicts describing the stage's supported parameters.
Method	`_get_group_expr`	Undocumented
Method	`_get_mongo_field_or_expr`	Undocumented
Method	`_get_mongo_match_expr`	Undocumented
Method	`_get_mongo_sort_expr`	Undocumented
Method	`_kwargs`	Returns a list of `[name, value]` lists describing the parameters of this stage instance.
Method	`_make_flat_pipeline`	Undocumented
Method	`_make_grouped_pipeline`	Undocumented
Method	`_needs_frames`	Whether the stage requires frame labels of video samples to be attached.
Method	`_needs_group_slices`	Whether the stage requires group slice(s) to be attached.
Instance Variable	`_create_index`	Undocumented
Instance Variable	`_field_or_expr`	Undocumented
Instance Variable	`_flat`	Undocumented
Instance Variable	`_match_expr`	Undocumented
Instance Variable	`_order_by`	Undocumented
Instance Variable	`_reverse`	Undocumented
Instance Variable	`_sort_expr`	Undocumented
Instance Variable	`_sort_stage`	Undocumented

Inherited from ViewStage:

Method	`__eq__`	Undocumented
Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Method	`get_edited_fields`	Returns a list of names of fields or embedded fields that may have been edited by the stage, if any.
Method	`get_excluded_fields`	Returns a list of fields that have been excluded by the stage, if any.
Method	`get_filtered_fields`	Returns a list of names of fields or embedded fields that contain arrays have been filtered by the stage, if any.
Method	`get_selected_fields`	Returns a list of fields that have been selected by the stage, if any.
Method	`load_view`	Loads the `fiftyone.core.view.DatasetView` containing the output of the stage.
Property	`has_view`	Whether this stage's output view should be loaded via `load_view` rather than appending stages to an aggregation pipeline via `to_mongo`.
Class Method	`_from_dict`	Creates a `ViewStage` instance from a serialized JSON dict representation of it.
Method	`_serialize`	Returns a JSON dict representation of the `ViewStage`.
Instance Variable	`_uuid`	Undocumented

def __init__(self, field_or_expr, order_by=None, reverse=False, flat=False, match_expr=None, sort_expr=None, create_index=True): (source) ¶

Undocumented

def get_group_expr(self, sample_collection): (source) ¶

overrides fiftyone.core.stages.ViewStage.get_group_expr

Returns the dynamic group expression for the given stage, if any.

Only usable if outputs_dynamic_groups is True.

Parameters
sample_collection	the `fiftyone.core.collections.SampleCollection` to which the stage is being applied
Returns
a tuple of the group expression, or `None` if the stage does not generate dynamic groups whether the group expression is an ObjectId field, or `None`

def get_media_type(self, sample_collection): (source) ¶

overrides fiftyone.core.stages.ViewStage.get_media_type

Returns the media type outputted by this stage when applied to the given collection, if and only if it is different from the input type.

Parameters
sample_collection	the `fiftyone.core.collections.SampleCollection` to which the stage is being applied
Returns
the media type, or `None` if the stage does not change the type

def to_mongo(self, sample_collection): (source) ¶

overrides fiftyone.core.stages.ViewStage.to_mongo

Returns the MongoDB aggregation pipeline for the stage.

Only usable if has_view is False.

Parameters
sample_collection	the `fiftyone.core.collections.SampleCollection` to which the stage is being applied
Returns
a MongoDB aggregation pipeline (list of dicts)